Quick Install

The recommended way to deploy ServerBee is the deploy/install.sh one-line script. It handles the tedious parts for you — architecture detection, binary downloads, service registration — so it works out of the box:

• Interactive wizard — run it with no arguments to pick the language, component, and install method through prompts
• Architecture aware — detects amd64/arm64 and pulls the matching Release binary
• systemd integration — creates and starts the service, enables it on boot
• Binary or Docker — switch with --method; Docker is recommended for the server, binary for agents
• Automatic HTTPS — pass --domain when installing the server and the script sets up Caddy and issues a certificate
• Unified management CLI — installs a serverbee command for upgrades, restarts, config changes, and uninstalls

The guide below walks through deployment from two angles: the Server and the Client (monitored node / Agent).

Prerequisites

• A Linux host (amd64 / arm64); the script must run as root (it checks and errors out otherwise). Use sudo as a regular user; if you are already root (e.g. logged in as root or inside a container) you can drop the sudo from the commands
• The binary method needs systemd; the Docker method needs Docker 20.10+ and Compose V2
• The server's port 9527 open in your firewall so agents and browsers can reach it

Server

The server is the central node: it receives metrics from agents, stores them, and serves the web dashboard.

Step 1: Install the server

There are two quick ways to install the server — pick one based on whether you have a domain.

Option A: Install with an IP (plain HTTP)

Fastest to get going; use this when you don't have a domain. You'll reach it at http://<server-ip>:9527:

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

The script writes auth.secure_cookie = false so browser login works over plain HTTP.

Option B: Install with a domain (automatic HTTPS)

If you already have a domain whose DNS A record points to this server, add --domain and the script sets up Caddy and issues an HTTPS certificate for you. You'll reach it at https://your-domain:

curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo bash -s -- server \
  --domain monitor.example.com \
  --email admin@example.com \
  -y

The script first checks that the domain resolves to this server; if it doesn't resolve or points to a different IP, installation stops and tells you which DNS record to add. --email is for Let's Encrypt notices and can be omitted. To add a domain to an already-installed server, run sudo serverbee domain setup --domain monitor.example.com --email admin@example.com.

Either way, the script automatically:

1. Detects the system architecture (amd64 / arm64)
2. Downloads the matching binary from GitHub Releases
3. Installs the binary to /opt/serverbee/bin/ and symlinks the management CLI to /usr/local/bin/serverbee
4. Creates the /opt/serverbee/etc/ config directory and generates a default config (data dir /opt/serverbee/data/)
5. Creates a systemd service unit
6. Starts the service and enables it on boot

Step 2: Get the first-run admin password

On its first start the server creates an admin account with a random password and prints it to the logs exactly once:

sudo journalctl -u serverbee-server --no-pager | grep -A8 'FIRST-RUN ADMIN CREDENTIALS' | tail -n 9

For the Docker method, use sudo serverbee status or docker logs serverbee-server.

Step 3: First login

1. Open http://<server-ip>:9527 in your browser (or https://your-domain for the domain method)
2. Log in with the default account admin and the random password from the logs
3. Complete the forced password change; you can pick a new username while you're at it

Manage the server

After installation, use the serverbee command to manage the instance:

sudo serverbee status                     # Status of all components
sudo serverbee upgrade -y                  # Upgrade to the latest version
sudo serverbee restart                     # Restart services
sudo serverbee config                      # View current config
sudo serverbee config set <key> <value>    # Change config
sudo serverbee uninstall server --purge    # Uninstall and wipe data

Client (Agent)

The agent is a lightweight probe running on each monitored machine; it reports CPU, memory, disk, and network metrics back to the server.

Step 1: Generate a one-time enrollment code on the server

Sign in to the dashboard as an admin, go to Settings, generate a one-time enrollment code, and copy it.

The code is single-use and short-lived (10 minute default expiry), and is only needed the first time an agent registers. Generate a fresh one for each new agent.

Step 2: Install and start the agent

On the machine you want to monitor, run the install script and pass the server URL and enrollment code as arguments:

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

The script detects the architecture, downloads the binary, writes the config, registers a systemd service, and brings the agent up.

On its first start the agent registers with the server: once registration succeeds the code is spent, and the agent receives its own token and writes it back to the config file. Later starts use that persisted token and no longer need the code. If an agent loses its token and has to re-onboard, just generate a new code in Settings.

Step 3: Verify the connection

Back in the dashboard, the new server shows up online within seconds and live metrics start flowing. You can also check from the agent machine:

sudo serverbee status
sudo journalctl -u serverbee-agent -n 80 --no-pager

Manage the agent

sudo serverbee status               # Agent status
sudo serverbee upgrade -y            # Upgrade the agent
sudo serverbee restart               # Restart the agent
sudo serverbee uninstall agent       # Uninstall the agent

For collector, logging, and other tunable options, see Agent Configuration and the full configuration reference.

Accessing by IP vs Domain

ServerBee works with a direct server IP or behind a domain and reverse proxy. What extra setup you need depends on whether the browser ends up on plain HTTP or HTTPS.

Alternative: Deploy the server manually with Docker Compose

If you'd rather manage the server with your own Compose file, create a docker-compose.yml:

services:
  serverbee-server:
    image: ghcr.io/zingerlittlebee/serverbee-server:latest
    container_name: serverbee-server
    ports:
      - "9527:9527"
    volumes:
      - serverbee-data:/data
    environment:
      - SERVERBEE_AUTH__SECURE_COOKIE=false
    restart: unless-stopped

volumes:
  serverbee-data:

Start it and read the first-run admin password:

docker compose up -d
docker compose logs serverbee-server