ServerBee

Configuration Reference

Complete reference for all ServerBee server and agent configuration options.

ServerBee uses Figment for configuration loading, which supports layered configuration from multiple sources. This page provides a complete reference for every configuration option.

Configuration Loading Priority

Configuration values are merged in the following order. Later sources override earlier ones:

  1. TOML file (system): /etc/serverbee/server.toml or /etc/serverbee/agent.toml
  2. TOML file (local): server.toml or agent.toml in the working directory
  3. Runtime environment variables: Prefixed with SERVERBEE_, using __ (double underscore) as the nested key separator

Environment Variable Mapping

Every TOML runtime configuration key maps directly to an environment variable. Replace dots with __ and prefix with SERVERBEE_:

Developer Workflow Env Vars

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

Environment VariableUsed ByDescription
SERVERBEE_PROD_URLmake db-pull, make web-dev-prodProduction base URL used by the database pull script and the frontend prod-proxy workflow
SERVERBEE_PROD_API_KEYmake db-pullAdmin-scoped API key for the production backup API. Do not reuse this for make web-dev-prod
SERVERBEE_PROD_READONLY_API_KEYmake web-dev-prodMember-scoped API key injected by the frontend dev proxy for live production browsing
ALLOW_WRITESmake web-dev-prodLocal opt-in override. Set to 1 to disable the proxy's read-method-only block. When set, the UI banner changes from the normal read-only warning to a stronger write-enabled warning

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

There is no admin username/password environment variable. On first start (when no users exist) the server auto-creates an admin account with a randomly generated password and prints it once to the server/container logs as a highlighted credentials banner. Capture it from the logs, then on first login you are required to change this password and may optionally choose a different username.

Environment VariableDefaultDescription
SERVERBEE_SERVER__LISTEN0.0.0.0:9527Listen address and port

Common

Environment VariableDefaultDescription
SERVERBEE_SERVER__DATA_DIR./dataData directory for database and backups
SERVERBEE_AUTH__MAX_SERVERS0Maximum servers allowed via enrollment (0 = no limit). Best-effort soft cap
SERVERBEE_SERVER__TRUSTED_PROXIESprivate/loopback CIDRsCIDR list of trusted reverse proxies. Defaults to RFC 1918 + loopback. Set to [] to disable
SERVERBEE_SCHEDULER__TIMEZONEUTCTimezone for daily traffic aggregation (e.g. Asia/Shanghai)
SERVERBEE_FEATURE__CUSTOM_THEMEStrueSet feature.custom_themes to false to disable user-defined themes. Custom refs are read-coerced to preset:default
SERVERBEE_LOG__LEVELinfoLog level: trace, debug, info, warn, error
SERVERBEE_LOG__FILE""Log file path. Empty means stdout only

OAuth (Optional)

Environment VariableDefaultDescription
SERVERBEE_OAUTH__BASE_URL""Public server URL for constructing OAuth callback URLs
SERVERBEE_OAUTH__ALLOW_REGISTRATIONfalseAuto-create user accounts on first OAuth login
SERVERBEE_OAUTH__GITHUB__CLIENT_ID--GitHub OAuth App client ID
SERVERBEE_OAUTH__GITHUB__CLIENT_SECRET--GitHub OAuth App client secret
SERVERBEE_OAUTH__GOOGLE__CLIENT_ID--Google OAuth client ID
SERVERBEE_OAUTH__GOOGLE__CLIENT_SECRET--Google OAuth client secret
SERVERBEE_OAUTH__OIDC__ISSUER_URL--OIDC provider issuer URL
SERVERBEE_OAUTH__OIDC__CLIENT_ID--OIDC client ID
SERVERBEE_OAUTH__OIDC__CLIENT_SECRET--OIDC client secret
SERVERBEE_OAUTH__OIDC__SCOPES["openid", "email", "profile"]OAuth scopes to request

GeoIP (Optional)

Environment VariableDefaultDescription
SERVERBEE_GEOIP__MMDB_PATH""Path to a MaxMind-compatible MMDB file. Non-empty path enables this custom GeoIP database; otherwise admins can download the DB-IP Lite database from Settings → GeoIP Database

Resend (Email Notifications)

Environment VariableDefaultDescription
SERVERBEE_RESEND__API_KEY""Resend API key. Required for Email notifications. Sender domain must be verified at resend.com/domains

Data Retention (Tuning)

Environment VariableDefaultDescription
SERVERBEE_RETENTION__RECORDS_DAYS7Raw metric records retention in days
SERVERBEE_RETENTION__RECORDS_HOURLY_DAYS90Hourly aggregated records retention in days
SERVERBEE_RETENTION__GPU_RECORDS_DAYS7GPU metric records retention in days
SERVERBEE_RETENTION__PING_RECORDS_DAYS7Ping probe records retention in days
SERVERBEE_RETENTION__NETWORK_PROBE_DAYS7Raw network probe records retention in days
SERVERBEE_RETENTION__NETWORK_PROBE_HOURLY_DAYS90Hourly network probe aggregates retention in days
SERVERBEE_RETENTION__AUDIT_LOGS_DAYS180Audit log retention in days
SERVERBEE_RETENTION__TRAFFIC_HOURLY_DAYS7Traffic hourly records retention in days
SERVERBEE_RETENTION__TRAFFIC_DAILY_DAYS400Traffic daily records retention in days
SERVERBEE_RETENTION__TASK_RESULTS_DAYS7Task results retention in days
SERVERBEE_RETENTION__DOCKER_EVENTS_DAYS7Docker event records retention in days
SERVERBEE_RETENTION__SERVICE_MONITOR_DAYS30Service monitor records retention in days

Mobile (Optional)

Environment VariableDefaultDescription
SERVERBEE_MOBILE__ACCESS_TTL900Mobile access token lifetime in seconds (15 min)
SERVERBEE_MOBILE__REFRESH_TTL2592000Mobile refresh token lifetime in seconds (30 days)

Internal

The following variables have sensible defaults and rarely need modification. Only adjust when you have a specific requirement.

Environment VariableDefaultDescription
SERVERBEE_DATABASE__PATHserverbee.dbSQLite database file path (relative to data_dir)
SERVERBEE_DATABASE__MAX_CONNECTIONS10Maximum database connection pool size
SERVERBEE_AUTH__SESSION_TTL86400Session token TTL in seconds (default 24h)
SERVERBEE_AUTH__SECURE_COOKIEtrueSet the Secure flag on session cookies. Use false only when the browser accesses ServerBee over plain HTTP, such as direct IP quick-start installs
SERVERBEE_RATE_LIMIT__LOGIN_MAX5Max login attempts per IP within 15-minute window
SERVERBEE_RATE_LIMIT__REGISTER_MAX3Max agent registrations per IP within 15-minute window
SERVERBEE_UPGRADE__RELEASE_BASE_URLhttps://github.com/ZingerLittleBee/ServerBee/releasesBase URL for agent upgrade release assets
SERVERBEE_UPGRADE__LATEST_VERSION_URL""Optional custom URL for latest version API. If empty, uses GitHub API
SERVERBEE_FILE__MAX_UPLOAD_SIZE104857600Maximum file upload size in bytes (default 100 MB)

Agent Environment Variables

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

Quick Start

Environment VariableDefaultDescription
SERVERBEE_SERVER_URL-- (required)Server HTTP base URL (e.g. http://your-server:9527). Agent appends API paths automatically
SERVERBEE_ENROLLMENT_CODE""One-time enrollment code minted by an admin in Settings. Single-use and short-lived (default 10 min). Only used when token is empty

Common

Environment VariableDefaultDescription
SERVERBEE_COLLECTOR__INTERVAL3Metric report interval in seconds
SERVERBEE_COLLECTOR__ENABLE_GPUfalseEnable NVIDIA GPU monitoring (requires nvml)
SERVERBEE_COLLECTOR__ENABLE_TEMPERATUREtrueEnable CPU temperature monitoring
SERVERBEE_FILE__ENABLEDfalseEnable file management on this agent
SERVERBEE_FILE__ROOT_PATHS[]Allowed root paths (comma-separated, e.g. /home,/var/log). Empty rejects all file operations
SERVERBEE_IP_CHANGE__ENABLEDtrueEnable periodic IP change detection
SERVERBEE_IP_CHANGE__CHECK_EXTERNAL_IPfalseAlso query an external URL to detect public/NAT IP changes
SERVERBEE_LOG__LEVELinfoLog level: trace, debug, info, warn, error
SERVERBEE_LOG__FILE""Log file path. Empty means stdout only

Internal

The following variables have sensible defaults and rarely need modification. Only adjust when you have a specific requirement.

Environment VariableDefaultDescription
SERVERBEE_TOKENauto-populatedAgent auth token. Auto-populated after registration, do not set manually
SERVERBEE_FILE__MAX_FILE_SIZE1073741824Max file size in bytes for read/download (default 1GB)
SERVERBEE_FILE__DENY_PATTERNS*.key,*.pem,...Glob patterns for files the agent refuses to access
SERVERBEE_IP_CHANGE__EXTERNAL_IP_URLhttps://api.ipify.orgURL that returns the agent's external IP as plain text
SERVERBEE_IP_CHANGE__INTERVAL_SECS300IP check interval in seconds (default 5 minutes)

Upgrade (Agent)

Environment VariableDefaultDescription
SERVERBEE_UPGRADE__RELEASE_REPO_URLhttps://github.com/ZingerLittleBee/ServerBee/releasesPinned release source base URL the Agent downloads upgrades from. Any HTTPS host mirroring the GitHub releases path layout {base}/download/v{version}/{asset} and {base}/download/v{version}/checksums.txt works. Compile-time default is overridable via the SERVERBEE_RELEASE_REPO build-time env
SERVERBEE_UPGRADE__RELEASE_CERT_SPKI_SHA256""Optional TLS certificate SPKI pin for the release host. 64 lowercase hex chars = SHA-256 of the leaf cert SubjectPublicKeyInfo DER. Empty = disabled. If set, the Agent additionally pins the leaf cert SPKI after standard chain validation. Invalid (non-64/non-hex) values are rejected at startup

Server Configuration (server.toml)

[server] -- Core Server Settings

KeyTypeDefaultDescription
listenstring"0.0.0.0:9527"IP address and port the server listens on
data_dirstring"./data"Directory for database files and other persistent data
trusted_proxiesstring[]private/loopback CIDRsCIDR ranges of trusted reverse proxies. Defaults to RFC 1918 + loopback ranges. Set to [] to disable X-Forwarded-For extraction

[database] -- Database Settings

KeyTypeDefaultDescription
pathstring"serverbee.db"Database filename (relative to data_dir)
max_connectionsu3210Maximum number of connections in the SQLite pool

[auth] -- Authentication Settings

KeyTypeDefaultDescription
session_ttli6486400Session cookie lifetime in seconds (24 hours)
max_serversu320Maximum servers allowed via enrollment (0 = no limit). Best-effort soft cap
secure_cookiebooltrueSet the Secure flag on session cookies. Use false only when the browser accesses ServerBee over plain HTTP

[retention] -- Data Retention

KeyTypeDefaultDescription
records_daysu327Days to keep raw metric records
records_hourly_daysu3290Days to keep hourly aggregated records
gpu_records_daysu327Days to keep per-GPU metric records
ping_records_daysu327Days to keep ping probe records
network_probe_daysu327Days to keep raw network probe records
network_probe_hourly_daysu3290Days to keep hourly aggregated network probe records
audit_logs_daysu32180Days to keep audit log entries
traffic_hourly_daysu327Days to keep hourly traffic records
traffic_daily_daysu32400Days to keep daily traffic records
task_results_daysu327Days to keep task execution results
docker_events_daysu327Days to keep Docker event records
service_monitor_daysu3230Days to keep service monitor check records

Raw metric records are collected every 60 seconds and retained for 7 days by default. The hourly aggregator computes averages so you can keep long-term trends for 90 days without excessive storage. Adjust these values based on your disk space and monitoring needs.

[scheduler] -- Scheduler

KeyTypeDefaultDescription
timezonestring"UTC"Timezone for daily traffic aggregation and billing cycle computation. Use IANA timezone names (e.g. Asia/Shanghai, US/Eastern)

[feature] -- Feature Flags

KeyTypeDefaultDescription
custom_themesbooltrueDisable user-defined themes when false. Custom refs are read-coerced to preset:default

[rate_limit] -- Rate Limiting

KeyTypeDefaultDescription
login_maxu325Maximum login attempts per rate-limit window
register_maxu323Maximum agent registration attempts per rate-limit window

[log] -- Logging

KeyTypeDefaultDescription
levelstring"info"Log verbosity: trace, debug, info, warn, error
filestring""Path to log file. If empty, logs go to stdout only

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

[geoip] -- GeoIP Lookup

KeyTypeDefaultDescription
mmdb_pathstring""Path to a MaxMind-compatible MMDB file. Non-empty path enables this custom GeoIP database; if empty, the UI can download DB-IP Lite into the server data directory

[resend] -- Email Notifications

KeyTypeDefaultDescription
api_keystring""Resend API key (resend.com/api-keys). Required to use the Email notification channel. The from address on each email channel must belong to a domain verified at resend.com/domains

[oauth] -- OAuth / SSO

KeyTypeDefaultDescription
base_urlstring""Public URL of your ServerBee instance (for callback URLs)
allow_registrationboolfalseCreate new user accounts on first OAuth login

[oauth.github] -- GitHub OAuth

KeyTypeDefaultDescription
client_idstring--GitHub OAuth App client ID
client_secretstring--GitHub OAuth App client secret

[oauth.google] -- Google OAuth

KeyTypeDefaultDescription
client_idstring--Google OAuth client ID
client_secretstring--Google OAuth client secret

[oauth.oidc] -- OpenID Connect

KeyTypeDefaultDescription
issuer_urlstring--OIDC issuer URL (e.g., https://auth.example.com/realms/main)
client_idstring--OIDC client ID
client_secretstring--OIDC client secret
scopesstring[]["openid", "email", "profile"]OAuth scopes to request

[upgrade] -- Agent Upgrade

KeyTypeDefaultDescription
release_base_urlstring"https://github.com/ZingerLittleBee/ServerBee/releases"Base URL for agent upgrade release assets. The server appends /download/v{version}/ to construct the asset download URL
latest_version_urlstring""Optional custom URL for latest version API. If empty, the server queries GitHub API to determine the latest version. Use this to override with a custom version endpoint

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

KeyTypeDefaultDescription
max_upload_sizeu64104857600Maximum file upload size in bytes (default 100 MB)

[mobile] -- Mobile Authentication

KeyTypeDefaultDescription
access_ttli64900Mobile access token lifetime in seconds (default 15 minutes)
refresh_ttli642592000Mobile refresh token lifetime in seconds (default 30 days)

Agent Configuration (agent.toml)

Docker Agent: Mount the host's machine-id for correct fingerprint identification:

-v /etc/machine-id:/etc/machine-id:ro

Top-Level Options

KeyTypeDefaultDescription
server_urlstringrequiredURL of the ServerBee server (e.g., http://10.0.0.1:9527)
tokenstring""Agent authentication token (auto-populated after registration)
enrollment_codestring""One-time enrollment code from server Settings (used only when token is empty; consumed on first successful registration)

[collector] -- Metric Collection

KeyTypeDefaultDescription
intervalu323Collection interval in seconds
enable_gpuboolfalseEnable NVIDIA GPU monitoring (requires nvidia-smi)
enable_temperaturebooltrueEnable CPU temperature sensor monitoring

[file] -- File Management

KeyTypeDefaultDescription
enabledboolfalseEnable file management capability. The server must also enable CAP_FILE for the agent
root_pathsstring[][]Restrict browsing to these directories. Empty array rejects all file operations
max_file_sizeu641073741824Maximum file size (bytes) for read and download operations (default 1 GB)
deny_patternsstring[]["*.key", "*.pem", "id_rsa*", ".env*", "shadow", "passwd"]Glob patterns for files the agent will refuse to access

[ip_change] -- IP Change Detection

KeyTypeDefaultDescription
enabledbooltrueEnable periodic IP change detection. Agent enumerates NIC addresses and reports changes
check_external_ipboolfalseAlso query an external URL to detect public/NAT IP changes
external_ip_urlstring"https://api.ipify.org"URL that returns the agent's external IP as plain text (used when check_external_ip is true)
interval_secsu64300IP check interval in seconds (default 5 minutes)

[log] -- Logging

KeyTypeDefaultDescription
levelstring"info"Log verbosity: trace, debug, info, warn, error
filestring""Path to log file. If empty, logs go to stdout only

[upgrade] -- Upgrade Source (Agent)

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

KeyTypeDefaultDescription
release_repo_urlstring"https://github.com/ZingerLittleBee/ServerBee/releases"Base URL for agent upgrade release assets. Must replicate the GitHub releases directory layout: {base}/download/v{version}/{asset} for binaries and {base}/download/v{version}/checksums.txt for checksum verification. The compile-time default is overridable via the SERVERBEE_RELEASE_REPO build-time env var
release_cert_spki_sha256string""Optional TLS SPKI pin for the release host. Set to 64 lowercase hex characters (SHA-256 of the leaf certificate's SubjectPublicKeyInfo DER encoding). Empty disables pinning. If set, the agent additionally validates the leaf cert SPKI after standard chain validation. Invalid format (non-64-char or non-hex) is rejected at startup

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)

The dashboard "latest version" check uses the Server-configured release source (upgrade.release_base_url / upgrade.latest_version_url). Those are separate Server-side settings used only for the dashboard's "latest version" lookup, and are distinct from the Agent's [upgrade] release_repo_url, which governs what the Agent actually downloads. For consistent upgrade behavior, point both the Server and the Agent at the same release repository unless you intentionally want them to track different sources.

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 in 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"

[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 Settings>"

Example: Production Agent Configuration

server_url = "https://monitor.example.com"
token = "previously-obtained-token"

[collector]
interval = 3
enable_gpu = true
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
check_external_ip = false

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

Agent Setup

Install and configure the ServerBee agent on your monitored servers.

Monitoring

Real-time system monitoring, dashboards, and historical data.

On this page

Configuration Loading PriorityEnvironment Variable MappingDeveloper Workflow Env VarsServer Environment VariablesQuick StartCommonOAuth (Optional)GeoIP (Optional)Resend (Email Notifications)Data Retention (Tuning)Mobile (Optional)InternalAgent Environment VariablesQuick StartCommonInternalUpgrade (Agent)Server Configuration (server.toml)[server] -- Core Server Settings[database] -- Database Settings[auth] -- Authentication Settings[retention] -- Data Retention[scheduler] -- Scheduler[feature] -- Feature Flags[rate_limit] -- Rate Limiting[log] -- Logging[geoip] -- GeoIP Lookup[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 AuthenticationAgent Configuration (agent.toml)Top-Level Options[collector] -- Metric Collection[file] -- File Management[ip_change] -- IP Change Detection[log] -- Logging[upgrade] -- Upgrade Source (Agent)Example: Minimal Server ConfigurationExample: Production Server ConfigurationExample: Minimal Agent ConfigurationExample: Production Agent Configuration