Agent Setup

The ServerBee agent is a lightweight Rust binary that runs on each server you want to monitor. It collects system metrics (CPU, memory, disk, network, load, temperature, GPU, disk I/O) and reports them to the central ServerBee server over a persistent WebSocket connection.

What the Agent Does

• Collects system metrics every 3 seconds (configurable), including disk I/O throughput on all platforms
• Reports metrics to the server over WebSocket
• Executes ping probes (ICMP, TCP, HTTP) assigned by the server
• Provides a PTY shell for web terminal access
• Runs remote commands dispatched from the server
• Manages remote file operations (browse, read, write, upload, download) with path sandbox security
• Monitors Docker containers when Docker daemon is available (stats, logs, events, networks, volumes)
• Supports automatic self-upgrade when the server pushes new versions
• Reconnects automatically with exponential backoff if the connection drops

Installation

Pre-built Binary

Download the agent binary for your platform from the releases page:

chmod +x serverbee-agent

Install Script

Use the install script to download the binary and configure a systemd service automatically:

curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo bash -s agent

Build from Source

cargo build --release -p serverbee-agent

The binary is located at target/release/serverbee-agent.

Docker (Not Recommended)

If you still prefer Docker, the agent needs privileged access to collect host system metrics:

docker run -d \
  --name serverbee-agent \
  --privileged \
  --net=host \
  --pid=host \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v /etc/serverbee:/etc/serverbee \
  --restart unless-stopped \
  ghcr.io/zingerlittlebee/serverbee-agent:latest

Limitations of Docker deployment:

• Requires --privileged for full metrics collection
• Temperature and GPU monitoring may not work inside containers
• Web terminal accesses the container environment, not the host

Registration Flow

Agents authenticate with the server using a token. There are two ways to obtain a token:

Automatic Registration (Recommended)

1. Get the auto-discovery key from the server startup logs
2. Configure the agent with the key:

server_url = "http://your-server-ip:9527"
auto_discovery_key = "your-auto-discovery-key"

3. Start the agent. It will:
   • Send a registration request to POST /api/agent/register using the key as a Bearer token
   • Receive a server_id and token from the server
   • Save the token to the config file automatically
   • Connect via WebSocket using the token for all future sessions

Manual Token

If you prefer not to use auto-discovery, you can manually create a server entry in the dashboard and provide the token directly:

server_url = "http://your-server-ip:9527"
token = "the-agent-token-from-dashboard"

Configuration

The agent reads configuration from TOML files in the following order:

1. /etc/serverbee/agent.toml (system-wide, preferred)
2. agent.toml (working directory)
3. Environment variables with SERVERBEE_ prefix

Here is a complete agent.toml with all available options:

# Required: URL of your ServerBee server
server_url = "http://your-server-ip:9527"

# Authentication token (auto-populated after registration)
token = ""

# Auto-discovery key for automatic registration (used only if token is empty)
auto_discovery_key = ""

[collector]
interval = 3                   # Metric collection interval in seconds
enable_gpu = false             # Enable NVIDIA GPU monitoring (requires nvidia-smi)
enable_temperature = true      # Enable temperature sensor monitoring

[log]
level = "info"                 # Log level: trace, debug, info, warn, error
file = ""                      # Log file path (empty = stdout only)

Environment Variables

Like the server, all options support SERVERBEE_ prefixed environment variables:

export SERVERBEE_SERVER_URL="http://your-server-ip:9527"
export SERVERBEE_TOKEN="your-agent-token"
export SERVERBEE_COLLECTOR__INTERVAL=5
export SERVERBEE_COLLECTOR__ENABLE_GPU=true

GPU Monitoring

GPU monitoring is disabled by default because it requires nvidia-smi to be available on the system. To enable it:

1. Ensure NVIDIA drivers and nvidia-smi are installed
2. Set enable_gpu = true in the agent config

[collector]
enable_gpu = true

When enabled, the agent collects per-GPU metrics:

• Device name
• Memory total and used
• GPU utilization percentage
• GPU temperature

These metrics appear in the server dashboard and can be used in alert rules.

Running as a Systemd Service

For production deployments, run the agent as a systemd service so it starts automatically on boot.

Create /etc/systemd/system/serverbee-agent.service:

[Unit]
Description=ServerBee Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/serverbee-agent
Restart=always
RestartSec=5
User=root
WorkingDirectory=/etc/serverbee

# Optional: limit resource usage
MemoryMax=128M
CPUQuota=10%

[Install]
WantedBy=multi-user.target

Then enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable serverbee-agent
sudo systemctl start serverbee-agent

Check the status:

sudo systemctl status serverbee-agent
journalctl -u serverbee-agent -f

Auto-Update

The server can push upgrade commands to connected agents. When an upgrade is triggered:

1. The server sends an Upgrade message with a download URL and version
2. The agent downloads the new binary
3. Verifies the SHA-256 checksum (if provided via x-checksum-sha256 header)
4. Backs up the current binary (.bak extension)
5. Replaces itself with the new binary
6. Restarts automatically

This process is transparent and requires no manual intervention on the agent side.

Connection Behavior

The agent maintains a persistent WebSocket connection to the server. If the connection drops:

• It reconnects using exponential backoff starting at 1 second
• The maximum backoff interval is 30 seconds
• A random jitter of +/-20% is applied to avoid thundering herd reconnections
• Upon successful reconnection, the backoff resets to 1 second

During the initial connection:

1. The server sends a Welcome message with the assigned server_id and report_interval
2. The agent sends its SystemInfo (CPU name, cores, arch, OS, kernel, memory, disk, IP addresses, virtualization type, agent version)
3. The server acknowledges with an Ack
4. The server syncs any assigned ping tasks
5. The agent begins its periodic metric reporting loop

Collected Metrics