Architecture

This page describes ServerBee's internal architecture for developers and operators who want to understand how the system works under the hood. ServerBee follows a hub-and-spoke design: a central Server receives metrics from distributed Agents over WebSocket, stores them in SQLite, and serves a React SPA dashboard.

System Overview

+--------------------------------------------------+
|              ServerBee Dashboard                  |
|                                                   |
|  +---------------------------------------------+ |
|  | Frontend (React SPA, embedded via rust-embed)| |
|  | React 19, TanStack Router/Query             | |
|  | shadcn/ui, Tailwind CSS v4, Bklit charts        | |
|  +---------------------------------------------+ |
|  +---------------------------------------------+ |
|  | Server (Rust)                                | |
|  | Axum Router                                  | |
|  |  +-- REST API handlers                      | |
|  |  +-- WebSocket: Agent + Browser + Terminal   | |
|  |  +-- Static files (rust-embed)              | |
|  | Service Layer                                | |
|  |  +-- AgentManager (connections/state)        | |
|  |  +-- AlertService (rule evaluation)          | |
|  |  +-- RecordService (metrics/aggregation)     | |
|  |  +-- NotificationService (dispatch)          | |
|  | Entity Layer (sea-orm)                       | |
|  |  +-- SQLite                                  | |
|  +---------------------------------------------+ |
+--------------------------+-----------------------+
                           | WebSocket (JSON)
+--------------------------v-----------------------+
|              ServerBee Agent (Rust)               |
|  common crate (shared types/protocol)             |
|  +-- Collector (system metrics)                   |
|  +-- Reporter (WebSocket + reconnect)             |
|  +-- Pinger (ICMP/TCP/HTTP probes)                |
|  +-- TerminalManager (PTY sessions)               |
+---------------------------------------------------+

Component Roles

Server (crates/server)

The central hub that:

• Serves the web dashboard (React SPA embedded via rust-embed)
• Exposes REST API endpoints for CRUD operations
• Manages WebSocket connections from agents and browsers
• Stores all data in SQLite
• Runs background tasks (record writing, aggregation, cleanup, alerting, offline detection)
• Dispatches notifications

Its main service modules are:

Agent (crates/agent)

A lightweight daemon deployed on each monitored server that:

• Collects system metrics using the sysinfo crate
• Reports metrics to the server over WebSocket every N seconds
• Runs ping probes as instructed by the server
• Provides PTY terminal sessions for remote shell access
• Executes remote commands dispatched by the server
• Supports self-upgrade when instructed

Its main modules are:

Common (crates/common)

A shared library crate containing the types and protocol shared between the agent and server:

• Protocol definitions -- AgentMessage, ServerMessage, BrowserMessage enums
• Data types -- SystemInfo, SystemReport, GpuReport, PingResult, ServerStatus, etc.
• Constants -- Protocol version, default ports, timeouts, retention periods, alert parameters

Frontend (apps/web)

A React 19 single-page application, embedded into the server binary via rust-embed after build:

• Routing -- TanStack Router (file-based)
• Data fetching -- TanStack Query for REST, native WebSocket for real-time updates (sharing the same cache)
• UI components -- shadcn/ui with the base-nova theme
• Styling -- Tailwind CSS v4
• Charts -- Bklit chart primitives (visx) behind shared wrappers in components/charts/
• Terminal -- xterm.js web terminal emulator
• Build -- Vite 7

The built frontend is embedded into the server binary at compile time, so there is nothing to deploy separately.

Communication Protocol

Agent reporting and control traffic uses WebSocket. Browsers use REST for initial data, history, and management operations, plus WebSocket for real-time updates. WebSocket application messages are JSON text frames; terminal I/O data is carried inside the message's data field, base64-encoded. The current Agent protocol version is 6, sent in the Welcome message on connect.

The agent connects to ws://<server>/api/agent/ws and authenticates with Authorization: Bearer <agent_token>. The Server temporarily accepts the legacy ?token= form so older Agents can reconnect and upgrade.

Agent to Server (AgentMessage)

Server to Agent (ServerMessage)

Server to Browser (BrowserMessage)

Browsers obtain data two ways: the REST API for initial load and historical queries, and a WebSocket at ws://<server>/api/ws/servers for real-time pushes. The WebSocket is one-way (Server -> Browser). REST results and WebSocket messages are projected into the same live server catalog so views stay current.

Handshake

Agent                              Server
  |                                  |
  |--- WebSocket connect + token --->|
  |                                  | verify token, look up server
  |<-- Welcome { server_id,         |
  |     protocol_version: 6,        |
  |     report_interval: 3 } -------|
  |                                  |
  |--- SystemInfo { cpu_name,       |  static info on connect/reconnect
  |     os, mem_total, ... } ------>|
  |<-- Ack { msg_id } -------------|
  |                                  |
  |--- Report (every 3s) ---------->|  periodic metric report

Message Size Limits

Terminal Data Transport

Terminal traffic uses the same JSON text protocol as the rest of the system, relayed through the server:

Browser <--JSON WebSocket--> Server <--JSON WebSocket--> Agent (PTY)

The raw PTY byte stream is base64-encoded into the data field of a JSON message, because terminal output is not UTF-8 safe.

Browser <-> Server messages (all JSON text):

• Browser -> Server: { "type": "input", "data": <base64> }, { "type": "resize", "rows": <n>, "cols": <n> }
• Server -> Browser: { "type": "session", "session_id": <id> }, { "type": "started" }, { "type": "output", "data": <base64> }, { "type": "error", "error": <message> }

Server <-> Agent messages reuse the agent protocol:

• Server -> Agent: ServerMessage::TerminalOpen, TerminalInput (data base64), TerminalResize, TerminalClose
• Agent -> Server: AgentMessage::TerminalStarted, TerminalOutput (data base64), TerminalError

Database Design

ServerBee uses SQLite (WAL mode), managed through sea-orm. The representative tables below cover the core schema, grouped by category.

Authentication

Server Management

Monitoring Data

Alerting & Operations

All tables use UTC timestamps. IDs are UUIDs (string type) for most entities, and auto-incrementing integers for high-volume records.

SQLite Configuration

• WAL mode -- PRAGMA journal_mode=WAL runs on startup to improve concurrent read performance.
• Busy timeout -- 5000ms; writers wait automatically on write contention.
• Synchronous mode -- PRAGMA synchronous=NORMAL.
• Connection pool -- Up to 10 connections, primarily for concurrent reads.

Background Tasks

The server spawns several long-running background tasks via tokio::spawn:

Ordering guarantees:

• Hourly tasks: aggregation -> cleanup (aggregate before cleaning so no long-term data is lost).
• Minute tasks: record write -> alert evaluation (so evaluation reads the freshly written data).

Security Model

Authentication Paths

User-facing REST and WebSocket requests resolve a user from a session cookie, API key, or Bearer session token. The authorization check then uses that user's current role. Agent WebSocket connections use a separate per-Agent run token.

Request arrives
  +-- Cookie: session_token=xxx         --> Session auth (browser)
  +-- Header: X-API-Key: serverbee_xxx  --> API key auth (automation)
  +-- Header: Authorization: Bearer xxx  --> Session auth (mobile)

Agent WebSocket connects
  +-- Header: Authorization: Bearer xxx  --> Agent run-token auth
  +-- Query: ?token=xxx                  --> Legacy Agent compatibility only

Session-based (browser)

• User logs in with username/password, verified with argon2.
• A random 32-byte token (base64url-encoded) is generated.
• The token is stored in the sessions table with an HttpOnly + SameSite=Strict cookie.
• Sliding expiry: each valid request extends expires_at (default TTL 24 hours).

API Key (automation)

• Admin users can create named API keys for programmatic access.
• Key format: serverbee_ + 32 random bytes (base64url).
• Keys are hashed with argon2; an 8-character plaintext prefix is stored for identification.
• On verification, the prefix narrows the lookup, then argon2 verifies the key.
• A key authenticates as its owning user and inherits that user's current admin or member role. An API key is a credential type, not a third role.

Agent Token (agents)

• An enrollment offer is bound to one Server, single-use, and short-lived. Its lifecycle is owned by the Agent Authority module.
• Before claiming an offer, the Agent generates and persists its run token, then submits it as proposed_run_token. The Server never generates or returns that token.
• The run token is hashed with argon2 and stored in the servers table; only the Agent retains the plaintext.
• Agents authenticate with the Authorization: Bearer <agent_token> header. Current Agents never place the raw token in the URI; query-token authentication remains a deprecated compatibility path for older releases.
• WebSocket admission has two stages: preflight validation before the HTTP upgrade, then final validation while holding the Server lifecycle lock. Authority transitions and frame dispatch share that lock, so a revoked or replaced connection cannot race through after fencing.
• Every authority/offer transition appends a secret-free event. Events retain a snapshot of the Server identity and survive Server deletion.

Role-Based Access

Two user roles exist: admin (full access) and member (read-only dashboard access). Session cookies, Bearer session tokens, and API keys are credentials for one of these users; they do not define additional roles.

Browser-facing WebSockets re-check the persisted session or API key and the user's role while connected. Logout, API-key deletion, password-reset session revocation, account deletion, or a role change closes the existing socket within two seconds instead of preserving handshake-time privileges.

OAuth

OAuth login is supported for GitHub, Google, and generic OIDC providers. The allow_registration flag controls whether new users are automatically created on first OAuth login.

Rate Limiting

Implemented as tower middleware with an in-memory map of IP to counter. Login and agent registration endpoints are rate-limited per IP to prevent brute-force attacks.

Exceeding a limit returns 429 Too Many Requests. Admins can clear an active window from Settings → Rate limits.

TOTP

Users can enable TOTP-based two-factor authentication for additional security.

Workspace Structure

The project uses a Cargo workspace for the Rust crates. The frontend is a separate Bun/Node project under apps/web/.

ServerBee/
  Cargo.toml                    # Workspace root
  crates/
    common/                     # Shared: protocol, data types, constants
      src/
        lib.rs
        protocol.rs             # Agent <-> Server message types
        types.rs                # SystemReport, GpuInfo, etc.
        constants.rs            # Protocol version, default values
    server/                     # Server binary (Axum, sea-orm, background tasks)
      src/
        main.rs
        config.rs
        state.rs                # AppState
        router/                 # REST API + WebSocket handlers
        service/                # Business logic
        entity/                 # sea-orm entities (one module per table)
        migration/              # Database migrations
        middleware/             # Auth, logging middleware
    agent/                      # Agent binary (collection, reporting, control)
      src/
        main.rs
        config.rs
        collector/              # Per-metric collectors
        reporter/               # WebSocket reporting, reconnect, commands, and file operations
        pinger.rs                # ICMP/TCP/HTTP ping tasks
        probe_utils.rs           # Shared probe validation and networking helpers
        network_prober.rs        # Scheduled network probes
        traceroute.rs            # Traceroute execution
        terminal.rs             # PTY terminal
        file_manager.rs          # Restricted remote file operations
        docker/                  # Docker inspection, actions, and log streaming
        security/                # Host security event detection
        firewall/                # Firewall block management
        ip_quality/              # IP quality checks
        upgrade.rs               # Self-upgrade coordinator
        upgrade/                 # Transactional self-upgrade support
  apps/
    web/                        # React frontend (Vite, TanStack, shadcn/ui)
    docs/                       # Documentation site (TanStack Start + Fumadocs)
  docs/                         # Design documents and plans