Configuration Reference

ServerBee loads configuration with Figment, which layers values from multiple sources. This page is a complete reference for every configuration option.

Configuration Loading Priority

Server values are merged in this order, with later sources overriding earlier ones:

1. Built-in defaults
2. /etc/serverbee/server.toml
3. /opt/serverbee/etc/server.toml (the path used by the install script)
4. server.toml in the working directory
5. Environment variables prefixed with SERVERBEE_

The Agent uses built-in defaults, then /etc/serverbee/agent.toml, agent.toml in its working directory, and finally SERVERBEE_ environment variables. The managed service uses /opt/serverbee/etc as its working directory, so its third source is /opt/serverbee/etc/agent.toml.

This lets you override effective settings at runtime without editing the TOML file. Compatibility-only fields, such as the Agent's collector.interval, are called out below.

Environment Variable Mapping

Every TOML key maps directly to an environment variable: add the SERVERBEE_ prefix, uppercase the key, and replace each level of nesting with __ (double underscore). For example, auth.secure_cookie becomes SERVERBEE_AUTH__SECURE_COOKIE.

Developer Workflow Env Vars

These variables drive local repo tooling and developer workflows. They are not Figment-backed runtime config for the server or agent binaries.

These variables are intentionally scoped to local tooling. ALLOW_WRITES is not a server feature flag; it is an explicit local override for the frontend prod-proxy workflow only.

Server Environment Variables

Quick Start

Common

Development Only

OAuth (Optional)

GeoIP (Optional)

Resend (Email Notifications)

Data Retention (Tuning)

Mobile (Optional)

Firewall (Optional)

Tier-2 guardrail for the Firewall Blocklist feature. CIDRs / IPs listed here are refused by POST /api/firewall/blocks even if an administrator tries to insert them. Tier 1 (hard-coded protected ranges: loopback, RFC 1918, link-local, multicast, unspecified) is always enforced.

IP Quality

By default, the Server calls ipapi.is anonymously (100 requests per client IP per UTC day). ServerBee uses the minimal response's proxy, VPN, datacenter, Tor, and abuse flags and derives an IP type, but no numeric risk score. A free account/API key provides 1,000 requests per day and the full response required for the 0–100 score. The Server falls back to ip-api.com only when the primary request fails, including HTTP 429, not when a successful response lacks a score. See IP Quality for details and the fallback's non-commercial/HTTP warning.

Network Probe Anomaly Thresholds

Average-latency cutoffs used to classify network-probe records returned by /api/servers/{id}/network-probes/anomalies and the anomaly_count field on the network-probe overview. Records strictly above very_high_latency_ms are tagged very_high_latency; records above high_latency_ms (and at or below the very-high cutoff) are tagged high_latency.

Internal

These variables have sensible defaults and rarely need changing. Adjust them only when you have a specific requirement.

Agent Environment Variables

Agent top-level keys use single underscore. Nested keys use __ (double underscore).

Quick Start

Common

Internal

These variables have sensible defaults and rarely need changing. Adjust them only when you have a specific requirement.

Upgrade (Agent)

Security (Agent)

Tunes the agent-side security event detectors (SSH login / brute force, port scan). Detection runs entirely on the agent; the server only stores events and evaluates alert rules. Configure per-host since traffic profiles differ.

Server Configuration (server.toml)

[server] -- Core Server Settings

[database] -- Database Settings

[auth] -- Authentication Settings

[dev] -- Local Development

[retention] -- Data Retention

[scheduler] -- Scheduler

[rate_limit] -- Rate Limiting

[log] -- Logging

The log level can also be set via the RUST_LOG environment variable, which takes precedence.

[geoip] -- GeoIP Lookup

[asn] -- ASN Lookup (Traceroute)

[resend] -- Email Notifications

[oauth] -- OAuth / SSO

[oauth.github] -- GitHub OAuth

[oauth.google] -- Google OAuth

[oauth.oidc] -- OpenID Connect

[upgrade] -- Agent Upgrade

[file] -- File Upload (Server-side)

[mobile] -- Mobile Authentication

[push_relay] -- Verified Mobile Setup

Set SERVERBEE_PUSH_RELAY__URL to the final HTTPS Worker URL. “Verified” here means authenticated Server account, installation and session ownership; there is no App Attest or Relay grant. The app registers its token, APNs environment and per-installation content key with the Server over HTTPS. The Server encrypts content and sends token, environment, event identity, expiry and envelope to the Worker's public POST /v1/send. Local Server fixtures may use http://127.0.0.1:<port>; the app requires HTTPS and rejects redirects.

Worker-only bindings are APNS_TEAM_ID, APNS_KEY_ID, APNS_TOPIC, APNS_ENVIRONMENTS and the APNS_PRIVATE_KEY secret containing PKCS#8 PEM text. They never belong in Server configuration or the app. APNS_TOPIC=app.serverbee matches the official main app; never use the extension identifier app.serverbee.notifications. APNS_ENVIRONMENTS=sandbox,production allows both device environments; topic and APNs hosts are fixed by the Worker. There is no database, challenge/grant lifecycle, version/distribution policy or Bun/OpenSSL runtime. See Cloudflare setup.

The public endpoint accepts abuse risk: known valid tokens can receive junk/generic notifications, while arbitrary traffic or an attacker's own token can consume quota. Strict payload limits, bounded streaming reads, deadlines, concurrency and bounded isolate-local source/target rate limits are best-effort safeguards, not global admission or cost guarantees. Content keys and business plaintext never cross Relay.

The Server retains authenticated subscriptions, recipient checks, durable encrypted outbox/retry, and a 30-minute deadline from original event creation. Alert triggers/recoveries, administrator security-rule matches and owner-only final scheduled-task outcomes remain supported; task success is opt-in. Role/session/subscription/revision changes stop later eligible sends. Terminal ciphertext is erased, and accepted or in-flight notifications cannot be recalled. APNs acceptance is a provider receipt, not proof of device presentation. Shared app/NSE Keychain signing and live device acceptance still require separate verification. See Mobile and Push Relay Operations.

[firewall] -- Firewall Blocklist Guardrail

[ip_quality] -- IP Quality Risk Scoring

By default, the Server calls ipapi.is anonymously (100 requests per client IP per UTC day). ServerBee uses the minimal response's proxy, VPN, datacenter, Tor, and abuse flags and derives an IP type, but no numeric risk score. A free account/API key provides 1,000 requests per day and the full response required for the 0–100 score. The Server falls back to ip-api.com only when the primary request fails, including HTTP 429, not when a successful response lacks a score. Local baseline metadata is available only when a usable GeoIP MMDB is loaded. See IP Quality for details and the fallback's non-commercial/HTTP warning.

[ip_quality.ipapi_is] -- ipapi.is

[network_probe] -- Anomaly Thresholds

Agent Configuration (agent.toml)

Top-Level Options

[collector] -- Metric Collection

[file] -- File Management

[capabilities] -- Agent-Owned Capability Policy

Capabilities are owned by the agent host. The agent starts from the default set (CAP_DEFAULT = 1852), applies allow/deny from this block, then applies any --allow-cap/--deny-cap CLI flags, and reports the result to the server. The server cannot override this. See Capabilities for the full key list and enforcement model.

[capabilities]
allow = ["terminal", "file"]
deny = ["ip_quality"]
# Footgun guard for `serverbee-agent grant --for ...`; defaults to 24h.
temporary_max_duration = "24h"
state_dir = "/var/lib/serverbee"

[ip_change] -- IP Change Detection

[security] -- Security Event Detection

[log] -- Logging

[upgrade] -- Upgrade Source (Agent)

The agent downloads upgrades from a locally-pinned release source rather than trusting a URL from the server.

Configuration precedence (highest wins):

1. --release-repo CLI flag
2. SERVERBEE_UPGRADE__RELEASE_REPO_URL environment variable
3. /etc/serverbee/agent.toml or agent.toml [upgrade] section
4. Compile-time default (official GitHub releases URL)

How to obtain the SPKI pin for a release host certificate:

openssl x509 -in cert.pem -pubkey -noout \
  | openssl pkey -pubin -outform der \
  | openssl dgst -sha256 -r | awk '{print $1}'

Example: Minimal Server Configuration

[server]
data_dir = "./data"

Everything else uses sensible defaults. On first startup, ServerBee creates the admin user with a random password and prints it once to the server logs.

Example: Production Server Configuration

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

[auth]
secure_cookie = true

[retention]
records_days = 14
records_hourly_days = 180

[geoip]
mmdb_path = "/var/lib/serverbee/GeoLite2-City.mmdb"

[asn]
mmdb_path = "/var/lib/serverbee/GeoLite2-ASN.mmdb"

[log]
level = "info"
file = "/var/log/serverbee/server.log"

[oauth]
base_url = "https://monitor.example.com"
allow_registration = false

[oauth.github]
client_id = "Iv1.abc123"
client_secret = "secret123"

Example: Minimal Agent Configuration

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

Example: Production Agent Configuration

server_url = "https://monitor.example.com"
token = "<agent-generated persisted token>"

[collector]
enable_gpu = true  # Requires a GPU-enabled build and an NVIDIA driver that provides NVML
enable_temperature = true

[file]
enabled = true
root_paths = ["/home", "/var/log", "/etc"]
max_file_size = 1073741824
deny_patterns = ["*.key", "*.pem", "id_rsa*", ".env*", "shadow", "passwd"]

[ip_change]
enabled = true
# external_ip_urls defaults to a curated list of public IP services.
# Override only to point at internal mirrors or to disable (set to []).

[log]
level = "info"
file = "/var/log/serverbee/agent.log"