Self-hosted service
ZingerLittleBee/ServerBee avatar
ZingerLittleBee/ServerBee

ServerBee pushes VPS metrics over one WebSocket into embedded SQLite

Lightweight VPS monitoring with agent + server + web dashboard. Rust + React monorepo.

350 stars31 forksRustAGPL-3.0

At a glance

What is it?
ServerBee runs a central Rust server that collects metrics from small agents over WebSocket, keeps history in an embedded SQLite file, and serves the React dashboard from the same executable. It is AGPL licensed and shipping weekly 1.0 beta tags.
Who is it for?
The fit is a single operator or a small team that wants one dashboard over a handful of Linux VPS boxes and refuses to run a separate database or metrics backend alongside it. The cost of that consolidation is visible in the design: the server holds the whole fleet's history in one embedded SQLite file, the web terminal and file manager run inside that same trust boundary, and each agent's own capability gates are the only thing between a browser session and the host.
Can I use it commercially?
Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
Is it still maintained?
Yes. The repository last received commits 29 days ago.
What is it written in?
Mainly Rust, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • ZingerLittleBee/ServerBee350 ★ · +10
Star history
Repository2026-09-102026-11-15
ZingerLittleBee/ServerBee340350

10 Stars in the last 66 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Agents push metrics up one WebSocket instead of being polled

ServerBee flips the usual direction of data flow. A central server receives metrics from lightweight agents over WebSocket, and each agent reports on a timer rather than waiting to be asked. The cadence lives in the agent configuration under the collector table, and the shipped default is 3 seconds. Whatever arrives is written into an embedded SQLite database inside the server process, so there is no external database to provision, and the React frontend is served out of the same executable the server runs from.

The agent footprint is quoted at about 4.3 MB at cold start and about 27 MB once it has settled into steady state, with the server staying lightweight as a fleet grows. Per host the collector reads CPU, memory, disk, network, load, temperature, and disk I/O, plus NVIDIA GPU numbers when you supply them yourself. History is charted from 1h out to 30d. Next to the raw metrics sit Docker container stats with logs and events, monthly traffic statistics that predict where the current billing cycle lands, and a cost panel reporting burn rate, per-resource unit cost, and a value score from 0 to 100.

toml
[collector]
interval = 3           # seconds between reports

Two install methods, and a container that keeps its data in /data

The installer is one shell pipeline that takes a role and a method. For the server, Docker is the recommended path:

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

`--method docker|binary` is the entire choice, and omitting the flag makes the script ask interactively instead. Open `http://your-server:9527` afterwards. The admin password is not one you set on the first boot: it is auto-generated and printed to the startup log, and you are expected to change it on first login.

Docker Compose runs a single service off `ghcr.io/zingerlittlebee/serverbee-server:latest`, publishing 9527 and mounting a named volume at `/data`:

yaml
  serverbee-server:
    image: ghcr.io/zingerlittlebee/serverbee-server:latest
    ports:
      - "9527:9527"
    volumes:
      - serverbee-data:/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:9527/healthz"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

The healthcheck hits `/healthz` every 30 seconds, allows 5 seconds, retries three times, and grants a 10 second start period before judging the container. The comment inside the compose file spells out the credential flow: a random password is printed once to the container logs and read back with `docker compose logs serverbee-server`. On Railway that volume has to be attached by hand at `/data`, and the credentials banner appears in the deploy logs instead.

The enrollment offer is single-use and expires in about ten minutes

Adding a host does not mean pasting a long-lived token into a config file. You sign in as admin, choose Add Server, and the dashboard hands you a generated install command. That enrollment offer is bound to one server, can be claimed once, and expires in about 10 minutes. What runs on the node is the same pipeline with the agent role:

bash
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

Two details in that command matter. The agent generates and persists its run token before it claims the offer, so a crash partway through does not burn the code. After the claim succeeds it reconnects automatically with that stored token, which is why the enrollment code is only needed the once. Agents are meant to be native binaries: that is the smallest footprint and the path that yields the full host-level metric set. Passing `--method docker` puts the agent in a container instead, at the cost of that host-level access.

Each agent also owns its capability gates and can issue host-local temporary grants, so what a given agent is permitted to do stays a property of that agent rather than a global switch on the central server. Agent auto-update is part of the same surface.

Two TOML files, an environment override, and a management CLI

The runtime image is a three-stage build: bun produces the web bundle, `rust:1-alpine` compiles `serverbee-server` and `serverbee-agent` in release mode, and the final stage is bare `alpine:3.21` with ca-certificates. The data directory is set by environment rather than baked into a file:

dockerfile
FROM alpine:3.21
RUN apk add --no-cache ca-certificates
VOLUME /data
ENV SERVERBEE_SERVER__DATA_DIR=/data
EXPOSE 9527
CMD ["serverbee-server"]

That name matters because the same key on disk is `data_dir`. A native install defaults `data_dir` to `/var/lib/serverbee`, while the image moves it to `/data`, so a swap between the two install methods leaves you looking in a different directory for the same database. Nested keys are reached with two underscores in the environment form, and `SERVERBEE_AUTH__MAX_SERVERS` is the worked example for an auth limit. The minimum on-disk configuration looks like this:

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

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

An empty admin password means generate one. OAuth, retention, rate limiting, and GeoIP knobs are covered in ENV.md and on the configuration pages at docs.serverbee.app. The installer also leaves a management binary at `/usr/local/bin/serverbee`:

bash
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

Note the split here: the CLI can move a native install onto the beta channel, while the compose file tracks the image tag `latest`. Those two knobs are set independently and can land you on different builds of the same week. Backup and restore are part of the same ops surface, alongside GeoIP region detection and OpenAPI and Swagger docs covering 180 or more endpoints.

Two WebSocket paths decide whether the dashboard is live or stuck

Metrics travel on two routes, and they are the reason a reverse proxy setup fails in a very specific way. Behind Nginx or Caddy you proxy `/` to `127.0.0.1:9527`, and both `/api/ws/` for the dashboard and `/api/agent/ws` for the agents have to forward the `Upgrade` and `Connection` headers with a long read timeout. Drop either header and the page still loads, the REST calls still answer, and the live panels simply never update, which reads like a broken monitor rather than a proxy mistake. Set the read timeout too short and you get the same symptom on a timer.

The default bind address is `0.0.0.0:9527`, so the port listens on every interface of the host unless you change `listen` under `[server]`. A ready-to-use Nginx configuration is provided on the deployment docs page rather than left for you to assemble the header handling yourself. The README does not spell out a read timeout value to use, so take that number from the deployment page rather than inventing one.

The proxy requirement is the concrete thing to check first when someone reports a dashboard that renders but never refreshes. Nothing else in the stack fails that way: SQLite writes, the agent timer, and the reporting interval are all independent of the proxy hop.

Alerts fire on 14 metric types and travel five delivery channels

Alerting reaches past an uptime ping. There are 14 or more metric types behind rules of four shapes: threshold, offline, traffic, and expiration. Delivery goes to Webhook, Telegram, Bark, Email, and APNs, and messages are grouped into notification groups so a burst of related events lands as one item rather than forty.

The network side is where this stops being a conventional server monitor. Ping monitoring speaks ICMP, TCP, or HTTP depending on the target. Network quality probing runs from presets covering 96 China 3-ISP probes plus international sets. Service monitors check SSL, DNS, HTTP keyword, TCP, and WHOIS. On top of that, IP quality and streaming unlock detection run with fraud scoring attached, so a datacenter address that fails a streaming unlock check gets scored instead of merely reported as reachable. GeoIP region detection feeds the country flags on server groups, and public status pages carry 90-day uptime timelines alongside custom dashboards built by drag and drop from 17 widget types.

Capability gates and RBAC sit between the browser terminal and the host

The remote management half is where the security decisions live. There is a browser web terminal running a PTY over a WebSocket connection, and a file manager that is sandboxed and edits through the Monaco editor. The firewall tool is a blocklist pushed via nftables. Each agent owns its capability gates and can issue host-local temporary grants, which is the mechanism that keeps someone holding a logged-in browser session from having standing administrative reach over every node at once.

Access control on the web side is OAuth through GitHub, Google, or OIDC, TOTP as a second factor, an Admin and Member split on the RBAC side, and audit logs on top. The server also watches each host for SSH logins, brute-force attempts, and port scans. Dashboard theming runs through custom OKLCH values, and a native iOS companion app sits alongside the web UI.

The frontend is React 19 on Vite 7 with TanStack Router and Query, shadcn components, and Tailwind CSS v4. The Rust side is Axum 0.8 with sea-orm over SQLite in WAL mode, and the agents use sysinfo with tokio-tungstenite.

The README still names an alpha build the Cargo workspace moved past

The version numbers disagree with each other. The release tags and the crate workspace both sit at `1.0.0-beta.4`, published 2026-09-30, with `v1.0.0-beta.3` on 2026-09-29 and `v1.0.0-beta.2` on 2026-09-24, three beta tags inside six days. The note near the top of the README still says the project is at `v1.0.0-alpha.12` and expects rapid iteration. The default branch was last pushed on 2026-10-01, the repository is not archived, and it carries 340 stars, 27 forks, and 28 open issues.

Because the tags move that fast, pinning matters. The workspace is edition 2024 and AGPL-3.0-or-later across three crates:

toml
[workspace]
resolver = "2"
members = [
    "crates/common",
    "crates/server",
    "crates/agent",
]

[workspace.package]
version = "1.0.0-beta.4"
edition = "2024"
license = "AGPL-3.0-or-later"

Quality is claimed as more than 3,800 automated tests and over 91% measured Rust region coverage, including integration suites that drive the real router over HTTP and WebSocket through a mock-agent harness.

The development loop is one make target, which is also where a fixed credential appears:

bash
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` brings the server up on 9527 and Vite on 5173 with hot reload, proxies `/api/*` to the Rust side, creates a development server, and prints a one-time agent enrollment command. The admin and admin123 login is a development fixture. Elsewhere, type checking spans three workspaces, the frontend test script runs `bun --filter @serverbee/web test`, linting goes through `ultracite check` on top of the Biome binary, and lefthook installs itself as a prepare hook. The JavaScript catalog pins drizzle-orm 0.45.1 and @libsql/client 0.15.15 next to better-auth 1.5.2 and the oRPC 1.12 packages, so a second data access stack shares the workspace with the sea-orm and SQLite WAL story on the Rust side.

Editorial conclusion

The fit is a single operator or a small team that wants one dashboard over a handful of Linux VPS boxes and refuses to run a separate database or metrics backend alongside it. The cost of that consolidation is visible in the design: the server holds the whole fleet's history in one embedded SQLite file, the web terminal and file manager run inside that same trust boundary, and each agent's own capability gates are the only thing between a browser session and the host. Before trusting it with production machines, pin an explicit beta tag rather than tracking latest, read what the two WebSocket paths do to an existing Nginx or Caddy config, and check the AGPL terms against a deployment you intend to modify.

Frequently asked questions

How does ServerBee collect metrics from a host it does not control the hardware of?

A small Rust agent runs on each node and reports over a WebSocket connection to the central server, which writes the values into embedded SQLite and serves the React dashboard from the same executable. The report cadence comes from the collector interval in the agent TOML, which ships a default of 3 seconds.

What does the ServerBee agent cost in memory at runtime?

The agent is quoted at about 4.3 MB at cold start and about 27 MB in steady state, with the server staying lightweight as the fleet grows. A native binary is the recommended agent method because it gives the smallest footprint and the full host-level metric set.

Does ServerBee require a separate database to store its history?

No. Metrics go into an embedded SQLite database inside the server process, with the Rust side running sea-orm and SQLite in WAL mode, so there is no external database to provision alongside the monitor.

Can ServerBee report NVIDIA GPU usage out of the box?

Only from an agent you build yourself with `--features gpu`. The prebuilt binaries that the install script downloads exclude GPU support, so GPU numbers are unavailable from a default install.

What can the serverbee management CLI do after installation?

It reports status of all components, upgrades the install, restarts services, views and sets configuration, and uninstalls components. Upgrades accept a channel, so `sudo serverbee upgrade --channel beta -y` moves a native install to the latest beta, while the compose file independently tracks the image tag `latest`.

Official sources

  1. License: AGPL-3.0
  2. Project website
  3. README
  4. Releases
  5. ZingerLittleBee/ServerBee on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/zingerlittlebee-serverbee.svg)](https://hysenlabs.com/projects/zingerlittlebee-serverbee)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/zingerlittlebee-serverbee.svg)](https://hysenlabs.com/projects/zingerlittlebee-serverbee)

Was this useful?