ServerBee

ServerBee

Lightweight, self-hosted VPS monitoring — one Rust binary, real-time everything.

English | 简体中文

---

ServerBee watches all your servers from one place. A central server receives metrics from lightweight agents over WebSocket, stores them in embedded SQLite, and serves a real-time React dashboard — no external database, no heavy runtime.

• 🪶 Tiny footprint — agents use ~4.3 MB at cold start and ~27 MB in steady state, and the server stays lightweight as your fleet grows.
• ⚡ Real-time — live WebSocket dashboard for CPU, memory, disk, network, load, temperature, disk I/O, and optional NVIDIA GPU metrics from a self-built Agent (--features gpu; prebuilt binaries exclude GPU support).
• 📦 Single binary — server + embedded web UI in one file. Deploy with Docker, a one-line script, or Railway.
• 🔋 Batteries included — alerts, notifications, web terminal, file manager, Docker, firewall, status pages, and more.
• 🔒 Secure by default — OAuth + 2FA, RBAC, audit logs, one-time agent enrollment, agent-owned capability gates.
• ✅ Battle-tested — 3,800+ automated tests and over 91% measured Rust region coverage, including integration suites that drive the real router over HTTP + WebSocket via a mock-agent harness; green on every CI run.

[!NOTE] ServerBee is in active development (v1.0.0-alpha.12). Expect rapid iteration.

Quick Start

1. Install the server

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

Open http://your-server:9527. The admin password is auto-generated and printed to the startup log — change it on first login.

The install script supports both Docker and native binary installs via --method docker|binary. Docker is recommended for the server; omit the flag to choose interactively. Prefer the cloud? Use the Railway one-click deploy below.

2. Enroll an agent

Sign in as admin, choose Add Server, and copy the generated install command. Its Server-bound enrollment offer is single-use and expires in about 10 minutes. Then run it on that node:

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

A native binary is recommended for agents — smallest footprint and full host-level metrics. Pass --method docker to run the agent in a container instead.

The Agent generates and persists its run token before claiming the offer, then reconnects automatically afterwards. The code is only needed once. That's it. 🎉

Features

📊 Monitoring	Real-time metrics (CPU/mem/disk/network/load/temp/disk I/O, plus optional self-built NVIDIA GPU support) · historical charts (1h–30d) · Docker container stats, logs & events · monthly traffic statistics with billing-cycle prediction · cost insights (burn rate, per-resource unit cost, 0–100 value score)
🔔 Alerts	14+ metric types · threshold / offline / traffic / expiration rules · Webhook, Telegram, Bark, Email & APNs channels with notification groups
🌐 Network	Ping monitoring (ICMP/TCP/HTTP) · network-quality probing (96 China 3-ISP + international presets) · service monitors (SSL/DNS/HTTP-keyword/TCP/WHOIS) · IP-quality & streaming-unlock detection with fraud scoring
🛠️ Remote management	Browser web terminal (PTY over WS) · sandboxed file manager with Monaco editor · firewall blocklist via nftables · agent-owned capability gates with host-local temporary grants · agent auto-update
🔐 Security & access	SSH login / brute-force / port-scan detection · OAuth (GitHub/Google/OIDC) + TOTP 2FA · Admin/Member RBAC · audit logs · one-time agent enrollment codes
🖥️ Dashboards & sharing	Drag-and-drop custom dashboards (17 widget types) · public status pages with 90-day uptime timelines · custom OKLCH themes · server groups with country flags · native iOS companion app
⚙️ Ops	serverbee management CLI · backup & restore · GeoIP region detection · OpenAPI/Swagger docs (180+ endpoints)

Configuration

Configure via TOML files or SERVERBEE_-prefixed environment variables (__ is the nested separator, e.g. SERVERBEE_AUTH__MAX_SERVERS). The minimum to get going:

# /etc/serverbee/server.toml
[server]
listen = "0.0.0.0:9527"
data_dir = "/var/lib/serverbee"

[admin]
password = ""   # leave empty to auto-generate

# /etc/serverbee/agent.toml
server_url = "http://your-server:9527"
enrollment_code = ""   # one-time code from Add Server; only used for first claim

[collector]
interval = 3           # seconds between reports

📖 Full reference: ENV.md · OAuth, retention, rate limiting, GeoIP, and more in the documentation.

Deployment

Railway (one-click)

Add a volume mounted at /data to persist data. The server auto-creates an admin account on first start — check the deploy logs for the credentials banner.

Management CLI

The installer drops a serverbee CLI at /usr/local/bin/serverbee:

sudo serverbee status         # status of all components
sudo serverbee upgrade -y     # upgrade to latest
sudo serverbee upgrade --channel beta -y  # upgrade to the latest beta
sudo serverbee restart        # restart services
sudo serverbee config         # view / set config
sudo serverbee uninstall agent -y

Reverse proxy

Behind Nginx/Caddy, proxy / to 127.0.0.1:9527 and make sure the WebSocket routes /api/ws/ and /api/agent/ws forward the Upgrade/Connection headers with a long read timeout. See the deployment docs for a ready-to-use Nginx config.

Development

git clone https://github.com/ZingerLittleBee/ServerBee.git
cd ServerBee

make dev-full         # server (:9527) + Vite dev server (:5173) — login admin / admin123
make cargo-test       # Rust tests
make test             # frontend tests
make cargo-clippy     # Rust lint

make dev-full runs Vite with HMR at http://localhost:5173, proxies /api/* to the Rust server at :9527, creates a development Server, and prints its one-time Agent enrollment command.

Stack: Rust (Axum 0.8 · sea-orm · SQLite WAL) · React 19 (Vite 7 · TanStack Router/Query · Bklit · shadcn/ui · Tailwind CSS v4) · Rust agents (sysinfo · tokio-tungstenite).

Testing & quality

ServerBee ships with 3,800+ automated tests — 3,200+ Rust (unit + 42 integration suites that drive the real Axum router over HTTP/WebSocket with a mock-agent harness) and 600+ frontend Vitest tests. Coverage is measured with cargo-llvm-cov (over 91% region overall; common ~98%, agent ~90%, server ~92%). CI runs zero-warning Clippy, the Rust suite, and frontend type/lint checks for the areas each change touches. See the Testing & Quality guide.

Commit and PR attribution

bun install sets up a Lefthook commit-msg hook that blocks Co-authored-by trailers, "Generated by/with" agent text, 🤖 Generated, Assisted-by, and any email address on git commit. The Check commit attribution CI job scans every commit in a pull request and the PR title and description, so --no-verify or LEFTHOOK=0 will not get past it. To fix a rejected commit, run git rebase -i <base-sha>, drop the matching lines, and force-push. Maintainers should mark Check commit attribution as a required check in branch protection; the workflow cannot enable that itself.

API

Interactive OpenAPI docs are served at /swagger-ui while the server runs.

License

AGPL-3.0