Environment Variables¶

WireBuddy reads configuration from process environment variables. Local starts through python run.py also load .env; the configuration loader retains settings.env as a lower-precedence compatibility source. Docker Compose uses the root .env file explicitly in the documented commands.

Most reverse-proxy and origin-dependent behavior (CSRF, passkeys, Host-header validation, secure cookies) auto-derives from a single WIREBUDDY_PUBLIC_ORIGIN setting. Configure that first; only add the more specific variables below if you have a concrete reason to override the derived default.

Quick Configuration¶

cp .env-example .env
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

Store the generated value in .env:

WIREBUDDY_SECRET_KEY=<generated-value>
LOG_LEVEL=INFO
TZ=Etc/UTC

Start the supplied Docker deployment with:

docker compose --env-file .env -f docker/docker-compose.yml up -d

Core Application¶

WIREBUDDY_SECRET_KEY¶

Required in master mode. It encrypts WireGuard private keys, preshared keys, OTP secrets, and other sensitive values and must contain at least 32 UTF-8 bytes.

WIREBUDDY_SECRET_KEY=<generated-value>

Generate it with either:

openssl rand -base64 32
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

The key is not required in node mode because enrolled nodes authenticate with their node credentials.

SERVER_MODE¶

Selects the process role:

• master: web UI, API, database, DNS, scheduling, and node management
• node: remote WireGuard node daemon without the web UI

Default: master.

LOG_LEVEL¶

Accepted values: CRITICAL, ERROR, WARNING, INFO, and DEBUG.

Default: INFO. Invalid values fall back to INFO.

TZ¶

IANA time-zone name used by scheduled tasks and UI formatting.

TZ=Europe/Berlin

Docker default: Etc/UTC.

WIREBUDDY_DATA_DIR¶

Base directory for persistent data. The database, TSDB, DNS files, certificates, and GeoIP databases live below it.

• Local default: <project>/data
• Supplied Docker Compose value: /app/data

WIREBUDDY_DEV_RELOAD¶

Set to true, 1, or yes to enable Uvicorn reload when starting through python run.py. Development only.

Web Server¶

WIREBUDDY_HOST¶

Docker-entrypoint override for the web bind address.

Without this override, the entrypoint reads Only listen on Localhost from the database and otherwise listens on 0.0.0.0 for a fresh installation.

WIREBUDDY_HOST=127.0.0.1

WIREBUDDY_PORT¶

Docker-entrypoint override for the GUI port. Valid range: 1–65535.

Without this override, the entrypoint uses the database setting HTTP Port (GUI). Fresh-installation default: 8000. The supplied Compose file always sets WIREBUDDY_PORT, so there the database setting has no effect.

WIREBUDDY_PORT=8080

HOST and PORT are not WireBuddy configuration variables.

UVICORN_GRACEFUL_SHUTDOWN_TIMEOUT¶

Docker Uvicorn graceful-shutdown timeout in seconds. Accepted range: 1–300.

Default: 8.

Reverse Proxy and Origin Handling¶

WIREBUDDY_PUBLIC_ORIGIN¶

Canonical public URL of this instance, e.g. https://vpn.example.com. Configuring this alone derives:

• CSRF allowed origins
• The passkey/WebAuthn relying-party ID and expected origin
• The Host-header allowlist (TrustedHostMiddleware), unless WIREBUDDY_ALLOWED_HOSTS is set explicitly
• Secure cookie flags and HSTS — enabled automatically for https:// origins

WIREBUDDY_PUBLIC_ORIGIN=https://vpn.example.com

WIREBUDDY_TRUSTED_PROXIES¶

Comma-separated reverse-proxy IPs/CIDRs. This single variable is used for:

• Uvicorn's --forwarded-allow-ips (which peers may set X-Forwarded-*)
• Application-level client-IP extraction and HTTPS-cookie detection
• The node mTLS client-certificate fingerprint header (master side)

Default: 127.0.0.0/8,::1/128 for cookie/HTTPS detection and Uvicorn's forwarded-header trust (a local reverse proxy on the same host just works). The public /status page and node mTLS fingerprint trust are more sensitive and default to trusting nothing beyond loopback until this is set explicitly — see Status Page.

WIREBUDDY_TRUSTED_PROXIES=192.168.1.10/32

* is rejected by the Docker entrypoint.

WIREBUDDY_CSRF_ALLOWED_ORIGINS¶

Comma-separated additional origins accepted by CSRF origin validation, beyond WIREBUDDY_PUBLIC_ORIGIN. Only needed when serving under multiple hostnames.

WIREBUDDY_CSRF_ALLOWED_ORIGINS=https://vpn2.example.com

WIREBUDDY_ALLOWED_HOSTS¶

Optional comma-separated Host-header allowlist. Derived automatically from the hostname in WIREBUDDY_PUBLIC_ORIGIN when unset. Set this explicitly only to accept additional hostnames or when no public origin is configured. If neither is set, Host-header validation is off and startup logs a warning, or only an informational message when the listener is bound to loopback.

WIREBUDDY_ALLOWED_HOSTS=vpn.example.com,localhost

FORCE_HTTPS_COOKIES¶

Forces the Secure attribute on authentication and CSRF cookies even when HTTPS is not otherwise detected. Secure cookies and HSTS are already enabled automatically when WIREBUDDY_PUBLIC_ORIGIN uses https://; this override is only needed for edge cases such as a TLS-terminating load balancer without a configured public origin.

Default: disabled (except when derived from WIREBUDDY_PUBLIC_ORIGIN).

WIREBUDDY_FORCE_HSTS¶

Always emits HSTS even when TLS terminates at a proxy and the upstream request appears as HTTP.

Default: disabled. HSTS is otherwise emitted automatically when WIREBUDDY_PUBLIC_ORIGIN uses https://, or when the request is detected as HTTPS.

Passkeys¶

PASSKEY_RP_ID¶

Optional WebAuthn relying-party ID override. Derived automatically from WIREBUDDY_PUBLIC_ORIGIN when unset; falls back to the request host for localhost development.

PASSKEY_RP_NAME¶

WebAuthn relying-party display name. Default: WireBuddy.

MAX_PASSKEYS_PER_USER¶

Maximum registered passkeys per account. Values are clamped to 1–100.

Default: 20.

Node Mode¶

WIREBUDDY_ENROLLMENT_TOKEN¶

Required for first node enrollment. Create it from the master's Nodes page. The token contains the master URL, node ID, and bootstrap API secret.

WIREBUDDY_ENROLLMENT_VERIFY_KEY¶

HMAC key used to verify the enrollment token locally. Required for normal first enrollment and generated alongside the enrollment token.

WIREBUDDY_MASTER_CA_FILE¶

Optional path to a custom CA file used to verify the master's HTTPS certificate. System CAs are used when unset.

WIREBUDDY_MASTER_CA_FILE=/app/data/certs/master-ca.pem

WIREBUDDY_NODE_SYNC_INTERVAL¶

Normal synchronization interval in seconds. Minimum: 5; default: 30.

WIREBUDDY_NODE_SYNC_INTERVAL_FAST¶

Fallback interval while SSE is disconnected. Minimum: 1; default: 5.

WIREBUDDY_ENROLLMENT_RETRY_ATTEMPTS¶

Enrollment retries after transient failures. Minimum: 1; default: 3.

WIREBUDDY_NO_FIREWALL_FIX¶

Disables the node's automatic DNS-related firewall correction when set to 1, true, or yes.

Default: disabled, so the correction is active.

Node Development Overrides¶

The following switches weaken enrollment or transport validation and are for isolated development/migration scenarios only:

• WIREBUDDY_ALLOW_INSECURE_MASTER_HTTP=1
• WIREBUDDY_ALLOW_UNVERIFIED_ENROLLMENT_TOKEN=1
• WIREBUDDY_ALLOW_LEGACY_NODE_SECRET=1

Do not enable them in production.

WIREBUDDY_MASTER_URL is not read by the current node daemon; the master URL is carried in the enrollment token and then persisted in node state.

GeoIP¶

GeoIP database paths and download URLs auto-resolve under WIREBUDDY_DATA_DIR with a built-in download source; overriding them is only needed for air-gapped installs or mirrored downloads.

WIREBUDDY_GEOIP_DB_PATH¶

Explicit GeoLite2 City database path. Default: <WIREBUDDY_DATA_DIR>/geolite2/GeoLite2-City.mmdb.

WIREBUDDY_ASN_DB_PATH¶

Explicit GeoLite2 ASN database path. Default: <WIREBUDDY_DATA_DIR>/geolite2/GeoLite2-ASN.mmdb.

WIREBUDDY_GEOIP_CITY_DOWNLOAD_URL¶

Optional HTTPS download URL for the City database.

WIREBUDDY_GEOIP_ASN_DOWNLOAD_URL¶

Optional HTTPS download URL for the ASN database.

WIREBUDDY_GEOIP_ALLOWED_HOSTS¶

Additional comma-separated HTTPS hosts allowed for custom GeoIP URLs and redirects. The built-in GitHub hosts remain allowed.

WIREBUDDY_GEOIP_CACHE_SIZE¶

In-memory GeoIP lookup cache size, clamped to 128–65536.

Default: 4096.

Security and Runtime Tuning¶

WIREBUDDY_CLEANUP_STALE_INTERFACES¶

Opt-in cleanup of active WireBuddy-managed WireGuard interfaces that no longer have matching configuration files. Disabled by default because cleanup is destructive.

WIREBUDDY_MANAGE_RESOLV_CONF¶

Allows WireBuddy to point /etc/resolv.conf at its managed Unbound resolver.

Default: disabled.

WIREBUDDY_REQUIRE_HTTPS_AUTH¶

Opt-in. Set to true, 1, or yes to reject authentication over plaintext HTTP. When enabled, password logins and node bearer/enrollment authentication are refused unless the request arrives over HTTPS. A single implicit exception applies to loopback peers, so local HTTP development keeps working.

Default: disabled. With the flag off and the built-in HTTPS listener off, plaintext authentication is allowed but logs a warning, preserving the historical behaviour for documented plain-HTTP LAN installs.

This flag is independent of Settings → General → Serve GUI over HTTPS: enabling the built-in HTTPS listener already forces the same rejection, and this variable additionally enforces it when the listener is off (for example behind a TLS-terminating reverse proxy). See Security Configuration.

WIREBUDDY_RATE_LIMIT_UI_HEAVY¶

Rate limit string (N/second|minute|hour|day) for expensive UI routes; an invalid value stops startup. Default: 60/minute.

Login Lockout Tuning¶

Login lockouts use three policies. Defaults are:

These values must be positive integers. Route-level request limits remain defined by the application.

WIREBUDDY_PBKDF2_ITERATIONS¶

PBKDF2 work factor used by vault key derivation. Default: 480000; values are clamped to 310000–2000000.

Changing this value after encrypted data has been written can prevent existing vault values from being decrypted. Treat it as an immutable deployment choice.

WIREBUDDY_DEPLOYMENT_ID¶

Optional deployment-specific vault derivation context. Changing or removing it after encrypted values exist makes those values unreadable.

WIREBUDDY_RUNTIME_DIR¶

Directory for the process banner lock. Default: /run/wirebuddy.

Development and CI¶

WIREBUDDY_SKIP_APPLICATION_LOCK¶

Set to 1, true, or yes to skip the exclusive lock on the data directory. The lock makes a second control plane on the same data directory fail at startup. Use this only on a filesystem without flock support (some network filesystems) and only if you can guarantee that a single instance runs; WireBuddy logs a warning and cannot detect a second instance when it is set.

WIREBUDDY_SKIP_NETWORK_CHECK¶

Skips Docker host-network verification. Use only in tests or CI; production Compose does not set it.

WIREBUDDY_TEST_MODE and WIREBUDDY_MIN_GEOIP_SIZE¶

Relax GeoIP fixture size checks for tests. They are not production settings and should only be set by the test suite itself, never in .env.

TESTING¶

Used by test helpers and passkey test paths. Do not enable in production.

Settings Managed in the UI¶

The following are database settings, not environment variables:

• GUI port and localhost-only binding (unless overridden by WIREBUDDY_PORT/WIREBUDDY_HOST in Docker)
• Swagger enablement
• public status-page enablement
• WireGuard, DNS, speed-test, backup, and retention settings

Variables such as SWAGGER_ENABLED, SESSION_COOKIE_*, RATELIMIT_*, CORS_ORIGINS, HOST, PORT, and WORKERS are not read by the current application.

Precedence¶

Local python run.py¶

1. Existing process environment
2. Root .env
3. Compatibility settings.env
4. Application defaults and database settings

Docker Compose¶

1. Compose environment entries
2. Values interpolated from the file supplied with --env-file
3. Image/entrypoint defaults and database settings

Verifying Effective Configuration¶

docker compose --env-file .env -f docker/docker-compose.yml config
docker compose --env-file .env -f docker/docker-compose.yml exec wirebuddy env | sort

Be careful when sharing this output because it contains the secret key and possibly enrollment credentials.

Related¶

• Docker Setup
• Security Configuration
• Multi-Node Deployment