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 values are merged in the following order. Later sources override earlier ones:
TOML file (system): /etc/serverbee/server.toml or /etc/serverbee/agent.tomlTOML file (local): server.toml or agent.toml in the working directoryEnvironment variables: Prefixed with SERVERBEE_, using __ (double underscore) as the nested key separator
Every TOML configuration key maps directly to an environment variable. Replace dots with __ and prefix with SERVERBEE_:
Environment Variable Default Description SERVERBEE_ADMIN__PASSWORDauto-generated Admin password. Leave empty to auto-generate and print to log SERVERBEE_SERVER__LISTEN0.0.0.0:9527Listen address and port
Environment Variable Default Description SERVERBEE_SERVER__DATA_DIR./dataData directory for database and backups SERVERBEE_AUTH__AUTO_DISCOVERY_KEYauto-generated Agent discovery key. Leave empty to auto-generate on first startup SERVERBEE_ADMIN__USERNAMEadminInitial admin username (only used when no users exist) SERVERBEE_SERVER__TRUSTED_PROXIESprivate/loopback CIDRs CIDR 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_LOG__LEVELinfoLog level: trace, debug, info, warn, error SERVERBEE_LOG__FILE""Log file path. Empty means stdout only
Environment Variable Default Description 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
Environment Variable Default Description SERVERBEE_GEOIP__MMDB_PATH""Path to MaxMind GeoLite2-City.mmdb file. Non-empty path enables GeoIP
Environment Variable Default Description 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
The following variables have sensible defaults and rarely need modification. Only adjust when you have a specific requirement.
Environment Variable Default Description 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 Secure flag on session cookies. Set false for HTTP-only dev 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_FILE__MAX_UPLOAD_SIZE104857600Maximum file upload size in bytes (default 100 MB)
Agent top-level keys use single underscore. Nested keys use __ (double underscore).
Environment Variable Default Description SERVERBEE_SERVER_URL-- (required) Server HTTP base URL (e.g. http://your-server:9527). Agent appends API paths automatically SERVERBEE_AUTO_DISCOVERY_KEY""Discovery key for first-time registration. Only used when token is empty
Environment Variable Default Description 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
The following variables have sensible defaults and rarely need modification. Only adjust when you have a specific requirement.
Environment Variable Default Description SERVERBEE_TOKENauto-populated Agent 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)
Key Type Default Description 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 CIDRs CIDR ranges of trusted reverse proxies. Defaults to RFC 1918 + loopback ranges. Set to [] to disable X-Forwarded-For extraction
Key Type Default Description pathstring "serverbee.db"Database filename (relative to data_dir) max_connectionsu32 10Maximum number of connections in the SQLite pool
Key Type Default Description session_ttli64 86400Session cookie lifetime in seconds (24 hours) auto_discovery_keystring ""Fixed agent discovery key. If empty, auto-generated on first start secure_cookiebool trueSet the Secure flag on session cookies. Disable only for HTTP-only development
Key Type Default Description usernamestring "admin"Admin username (used only on first startup when no users exist) passwordstring ""Admin password. If empty, a random password is generated and logged
Key Type Default Description records_daysu32 7Days to keep raw metric records records_hourly_daysu32 90Days to keep hourly aggregated records gpu_records_daysu32 7Days to keep per-GPU metric records ping_records_daysu32 7Days to keep ping probe records network_probe_daysu32 7Days to keep raw network probe records network_probe_hourly_daysu32 90Days to keep hourly aggregated network probe records audit_logs_daysu32 180Days to keep audit log entries traffic_hourly_daysu32 7Days to keep hourly traffic records traffic_daily_daysu32 400Days to keep daily traffic records task_results_daysu32 7Days to keep task execution results docker_events_daysu32 7Days to keep Docker event records service_monitor_daysu32 30Days 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.
Key Type Default Description timezonestring "UTC"Timezone for daily traffic aggregation and billing cycle computation. Use IANA timezone names (e.g. Asia/Shanghai, US/Eastern)
Key Type Default Description login_maxu32 5Maximum login attempts per rate-limit window register_maxu32 3Maximum agent registration attempts per rate-limit window
Key Type Default Description 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.
Key Type Default Description mmdb_pathstring ""Path to a MaxMind GeoLite2-City MMDB file. Non-empty path enables GeoIP
Key Type Default Description base_urlstring ""Public URL of your ServerBee instance (for callback URLs) allow_registrationbool falseCreate new user accounts on first OAuth login
Key Type Default Description client_idstring -- GitHub OAuth App client ID client_secretstring -- GitHub OAuth App client secret
Key Type Default Description client_idstring -- Google OAuth client ID client_secretstring -- Google OAuth client secret
Key Type Default Description 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
Key Type Default Description 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
Key Type Default Description max_upload_sizeu64 104857600Maximum file upload size in bytes (default 100 MB)
Key Type Default Description server_urlstring required URL of the ServerBee server (e.g., http://10.0.0.1:9527) tokenstring ""Agent authentication token (auto-populated after registration) auto_discovery_keystring ""Discovery key for automatic registration (used only when token is empty)
Key Type Default Description intervalu32 3Collection interval in seconds enable_gpubool falseEnable NVIDIA GPU monitoring (requires nvidia-smi) enable_temperaturebool trueEnable CPU temperature sensor monitoring
Key Type Default Description enabledbool falseEnable 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_sizeu64 1073741824Maximum 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
Key Type Default Description enabledbool trueEnable periodic IP change detection. Agent enumerates NIC addresses and reports changes check_external_ipbool falseAlso 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_secsu64 300IP check interval in seconds (default 5 minutes)
Key Type Default Description levelstring "info"Log verbosity: trace, debug, info, warn, error filestring ""Path to log file. If empty, logs go to stdout only
[ admin ] password = "my-secure-password" Everything else uses sensible defaults. This is sufficient to start a working server that listens on port 9527 with a SQLite database in ./data/.
[ server ] listen = "127.0.0.1:9527" data_dir = "/var/lib/serverbee" [ admin ] username = "admin" password = "a-very-strong-password" [ 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" server_url = "http://your-server-ip:9527" auto_discovery_key = "your-key-here" 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"