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

Install Script (recommended)

The install script detects the architecture, downloads the binary, generates the config, and registers a systemd service automatically:

curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo bash -s -- agent \
  --server-url http://your-server-ip:9527 \
  --enrollment-code YOUR_ONE_TIME_CODE

Layout: binary in /opt/serverbee/bin/, config in /opt/serverbee/etc/agent.toml, and the management CLI symlinked to /usr/local/bin/serverbee.

After installation, manage the agent with the serverbee CLI (automatically installed):

sudo serverbee status
sudo serverbee upgrade agent -y
sudo serverbee restart agent
sudo serverbee config agent
sudo serverbee uninstall agent -y

Pre-built Binary (manual)

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

chmod +x serverbee-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/machine-id:/etc/machine-id: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:

Enrollment Code Registration (Recommended)

1. Sign in to the web UI as an admin, open Settings, and generate a one-time enrollment code (also available via POST /api/agent/enrollments, admin-only). The code is single-use and short-lived (default 10 minute expiry).
2. Configure the agent with the code:

server_url = "http://your-server-ip:9527"
enrollment_code = "<one-time code from Settings>"

3. Start the agent. It will:
   • Send a registration request to POST /api/agent/register presenting the one-time enrollment code
   • Receive a server_id and per-server token from the server (the code is consumed on this first successful registration)
   • Save the token to the config file automatically
   • Connect via WebSocket using the token for all future sessions -- the enrollment code is no longer needed

When the agent can read a stable machine identifier, it also sends a fingerprint during registration. Repeated registration from the same machine reuses the existing server row instead of creating duplicate placeholders. If a code is lost, expired, or already used, the server responds with HTTP 401 and the agent logs Registration failed: HTTP 401 ... enrollment code ... expired or already used; mint a fresh code in Settings to retry.

Correcting a Wrong Enrollment Code

If the agent was installed with a mistyped enrollment code (or wrong server_url) and has not yet registered (no token saved), fix it without reinstalling. Enrollment codes are single-use, so a typo'd or already-consumed code cannot be reused — generate a fresh one in Settings first if needed, then:

serverbee config set enrollment_code <new-code> -y
# if the server URL was also wrong:
serverbee config set server_url http://your-server-ip:9527 -y

The -y flag restarts the agent so it retries registration immediately. Without -y the value is written but the service is not restarted; run serverbee restart agent afterwards.

If you are unsure of the agent's state, simply re-run the agent installer — it rewrites agent.toml:

serverbee install agent --method <binary|docker> \
  --server-url http://your-server-ip:9527 \
  --enrollment-code <new-code> -y

Once the agent has already registered (a token is present in agent.toml), the enrollment code is no longer used and does not need correcting; point the agent at a different server only by re-registering with a fresh code from that server.

Manual Token

If you prefer not to use enrollment codes, 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 = ""

# One-time enrollment code for first-time registration (used only if token is empty)
enrollment_code = ""

[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

Local Capability Locks

Agent-local capability policy can be tightened from the command line without changing the server-side configuration:

serverbee-agent --allow-cap terminal --allow-cap exec
serverbee-agent --deny-cap ping_http

• Low-risk capabilities (upgrade, ping_icmp, ping_tcp, ping_http) are enabled by default
• High-risk capabilities (terminal, exec, file, docker) are disabled by default
• --deny-cap always wins over --allow-cap

This policy is local to the agent process. The server can only further restrict capabilities, it cannot override an agent-local deny.

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

Resource Footprint

The Agent has negligible CPU cost (<1%) and a steady-state memory footprint in the tens of MB. For the full measured Agent and Server CPU/memory/disk/network data, see Resource Usage.