Environment Variables Configuration
Updated
This page provides a comprehensive reference for all environment variables available when self-hosting NetBird. Environment variables allow you to configure the Management Server, Signal Server, Relay Server (including the embedded STUN server), and Dashboard services.
Environment variables set in your setup.env file are used by the configure.sh script to generate the final configuration files. Changes to setup.env require re-running ./configure.sh to take effect.
Overview
NetBird uses two types of environment variables:
- Setup Variables (
NETBIRD_prefix) - Used in docker-compose templates andsetup.envfor initial configuration - Runtime Variables (
NB_prefix) - Can override CLI flags at runtime using the pattern--flag-name→NB_FLAG_NAME
Core Setup Variables
These variables are set in your setup.env file before running the configuration script.
Domain and Network
| Variable | Description | Example |
|---|---|---|
NETBIRD_DOMAIN | Your NetBird domain name | netbird.example.com |
NETBIRD_LETSENCRYPT_EMAIL | Email for Let's Encrypt certificates | admin@example.com |
NETBIRD_DISABLE_LETSENCRYPT | Disable automatic Let's Encrypt | true |
Port Configuration
| Variable | Default | Description |
|---|---|---|
NETBIRD_MGMT_API_PORT | 33073 | Management API port |
NETBIRD_SIGNAL_PORT | 10000 | Signal server port |
NETBIRD_RELAY_PORT | 33080 | Relay server port |
NGINX_SSL_PORT | 443 | Dashboard HTTPS port |
STUN Configuration
The default quickstart deployment uses the relay service's embedded STUN server. The variables below configure STUN functionality within the relay container via relay.env.
| Variable | Default | Description |
|---|---|---|
NB_ENABLE_STUN | true | Enable embedded STUN server in relay |
NB_STUN_PORTS | 3478 | STUN server UDP ports |
NB_STUN_LOG_LEVEL | info | STUN server log level |
Management Server Variables
Database Configuration
| Variable | Default | Description |
|---|---|---|
NETBIRD_STORE_CONFIG_ENGINE | sqlite | Store engine: sqlite, postgres, or mysql (deprecated) |
NETBIRD_STORE_ENGINE_POSTGRES_DSN | - | PostgreSQL connection string |
NETBIRD_STORE_ENGINE_MYSQL_DSN | - | MySQL connection string. Deprecated, see Migrate from MySQL to PostgreSQL |
NETBIRD_DATASTORE_ENC_KEY | Auto-generated | Encryption key for sensitive data |
See Management Postgres Store for PostgreSQL setup details.
Single Account Mode
| Variable | Default | Description |
|---|---|---|
NETBIRD_MGMT_SINGLE_ACCOUNT_MODE_DOMAIN | - | Domain for single account mode |
NetBird runs in single account mode by default since v0.10.1. All users joining your self-hosted instance will be part of the same account/network.
Relay Configuration
| Variable | Description |
|---|---|
NETBIRD_RELAY_ENDPOINT | Relay server endpoint URL |
NETBIRD_RELAY_AUTH_SECRET | Shared authentication secret for relay |
Signal Configuration
| Variable | Description |
|---|---|
NETBIRD_SIGNAL_PROTOCOL | Protocol: http or https |
DNS Configuration
| Variable | Default | Description |
|---|---|---|
NETBIRD_MGMT_DNS_DOMAIN | netbird.selfhosted | DNS domain for peer resolution |
TLS/Certificates
| Variable | Description |
|---|---|
NETBIRD_MGMT_API_CERT_FILE | Path to TLS certificate file |
NETBIRD_MGMT_API_CERT_KEY_FILE | Path to TLS certificate key file |
Metrics and Analytics
| Variable | Default | Description |
|---|---|---|
NETBIRD_DISABLE_ANONYMOUS_METRICS | false | Disable anonymous usage metrics |
Runtime Environment Variables (NB_ prefix)
These variables can override CLI flags at runtime. The naming convention is NB_<FLAG_NAME> where the flag name is uppercased and hyphens are replaced with underscores.
Management Server Runtime
| Variable | Description |
|---|---|
NB_PORT | Server port (overrides --port) |
NB_DATADIR | Data directory (overrides --datadir) |
NB_CONFIG | Config file path (overrides --config) |
NB_LOG_LEVEL | Log level: debug, info, warn, error |
NB_LOG_FILE | Log file path |
NB_METRICS_PORT | Prometheus metrics port |
NB_LETSENCRYPT_DOMAIN | Let's Encrypt domain |
NB_CERT_FILE | TLS certificate file |
NB_CERT_KEY | TLS certificate key file |
NB_DNS_DOMAIN | DNS domain for peers |
NB_DISABLE_GEOLITE_UPDATE | Disable GeoLite database updates |
NB_SETUP_PAT_ENABLED | Enable optional Personal Access Token creation from /api/setup during initial setup. See Automated Setup. |
The Management server does not read an environment variable for --letsencrypt-listen-address. Pass it as a command-line flag. See the NB_LETSENCRYPT_LISTEN_ADDRESS entry under Signal Server Variables for what the setting does.
Advanced Runtime Variables
| Variable | Description |
|---|---|
NB_PPROF_ADDR | Start the unauthenticated Go pprof HTTP listener at a host:port address, for example 127.0.0.1:6060. Unset disables it. Bind to loopback or another trusted interface and restart the server after changing it; never expose pprof directly to the public internet. |
NB_EVENT_ACTIVITY_LOG_ENABLED | Enable activity log events |
NB_GET_ACCOUNT_BUFFER_INTERVAL | Account buffer interval duration |
NB_SQL_MAX_OPEN_CONNS | Maximum SQL database connections |
NB_STORE_TRANSACTION_TIMEOUT | Store transaction timeout |
NB_ACCESS_LOG_STORE_ENGINE | Access log store engine: sqlite or postgres. Defaults to the main store engine |
NB_ACCESS_LOG_POSTGRES_DSN | Connection string for a dedicated access log PostgreSQL database. Defaults to the main store DSN |
NB_ACCESS_LOG_SQLITE_FILE | Access log SQLite file, resolved against the data directory when relative. Defaults to access_logs.db |
NB_ACCESS_LOG_SQL_MAX_OPEN_CONNS | Maximum connections of the access log PostgreSQL pool. Defaults to NB_SQL_MAX_OPEN_CONNS |
NB_API_RATE_LIMITING_ENABLED | Enable API rate limiting |
NB_API_RATE_LIMITING_RPM | Rate limit requests per minute |
NB_API_RATE_LIMITING_BURST | Rate limit burst size |
NETBIRD_METRICS_INTERVAL_IN_SECONDS | Metrics push interval |
MCP Server Runtime
Set these on the netbird-server container, or on management in a multi-container deployment. See MCP Server for Self-Hosted NetBird.
| Variable | Default | Description |
|---|---|---|
NB_MCP_ENABLED | false | Turn on the MCP server at /api/mcp. OAuth sign-in starts only with the embedded identity provider or a PKCEAuthorizationFlow. Read as a boolean. |
NB_MCP_TOOLS | All tools | Comma-separated list of the MCP tools to expose. An unknown tool name stops management at startup. |
NB_MCP_OAUTH_KEY | Datastore encryption key | Secret of at least 32 bytes that seals MCP OAuth codes and tokens. Changing it signs every MCP client out. Generate one with openssl rand -base64 32. |
NB_CACHE_REDIS_ADDRESS | - | Redis URL for management's shared cache, such as redis://redis:6379. When set, MCP sign-ins are stored there and survive restarts. Management does not start if it cannot reach Redis. NB_IDP_CACHE_REDIS_ADDRESS is the legacy name. |
Signal Server Variables
Runtime Variables
| Variable | Description |
|---|---|
NB_PORT | Signal server port |
NB_METRICS_PORT | Prometheus metrics port |
NB_SSL_DIR | SSL certificates directory |
NB_LETSENCRYPT_DOMAIN | Let's Encrypt domain |
NB_LETSENCRYPT_LISTEN_ADDRESS | Address of the separate Let's Encrypt challenge listener (overrides --letsencrypt-listen-address). Default :443. Used only when Let's Encrypt is on and NB_PORT is not 443. Set it to an empty value to disable the separate listener when public port 443 is forwarded to NB_PORT. |
NB_CERT_FILE | TLS certificate file |
NB_CERT_KEY | TLS certificate key file |
NB_LOG_LEVEL | Log level |
NB_LOG_FILE | Log file path |
Combined Server Variables
The combined netbird-server container reads its settings from config.yaml. From NetBird v0.83.0, two of its secrets can come from environment variables on the container instead, so config.yaml can be kept in version control without them. A variable that is set and not empty overrides the config.yaml field. See Keeping secrets out of the config file for the version requirement and the exceptions.
| Variable | Overrides | Description |
|---|---|---|
NB_AUTH_SECRET | server.authSecret | Shared secret of the relay that runs inside netbird-server. With external relays, applies only when server.relays.secret is empty |
NB_STORE_ENCRYPTION_KEY | server.store.encryptionKey | Database encryption key. On self-hosted Enterprise, also the key its integrations use |
Relay Server Variables
Setup Variables
| Variable | Description |
|---|---|
NETBIRD_RELAY_TAG | Docker image tag |
NETBIRD_RELAY_PORT | Relay port (default: 33080) |
NETBIRD_RELAY_ENDPOINT | Relay endpoint address |
NETBIRD_RELAY_AUTH_SECRET | Authentication secret |
NETBIRD_RELAY_DOMAIN | Relay server domain |
Runtime Variables
| Variable | Default | Description |
|---|---|---|
NB_LOG_LEVEL | info | Log level |
NB_LISTEN_ADDRESS | :443 | Listen address |
NB_EXPOSED_ADDRESS | - | Exposed address for peers |
NB_AUTH_SECRET | - | Authentication secret |
NB_METRICS_PORT | - | Prometheus metrics port |
NB_TLS_CERT_FILE | - | TLS certificate file |
NB_TLS_KEY_FILE | - | TLS key file |
NB_LETSENCRYPT_DATA_DIR | - | Let's Encrypt data directory |
NB_LETSENCRYPT_DOMAINS | - | Let's Encrypt domains |
NB_LETSENCRYPT_EMAIL | - | Let's Encrypt email |
NB_HEALTH_LISTEN_ADDRESS | - | Health check listen address |
NB_TRUSTED_PROXIES | - | Comma-separated IP addresses or CIDRs for immediate upstream proxies whose X-Real-Ip and X-Real-Port headers the relay may trust. Empty trusts no forwarding headers. |
NB_ENABLE_STUN | false | Enable embedded STUN server |
NB_STUN_PORTS | 3478 | STUN server UDP ports (comma-separated) |
NB_STUN_LOG_LEVEL | info | STUN server log level |
Dashboard Variables
| Variable | Description |
|---|---|
NETBIRD_MGMT_API_ENDPOINT | Management API endpoint URL |
NETBIRD_MGMT_GRPC_API_ENDPOINT | Management gRPC endpoint |
LETSENCRYPT_DOMAIN | Let's Encrypt domain (set to none if using own certs) |
LETSENCRYPT_EMAIL | Let's Encrypt email |
Dashboard authentication is automatically configured when using the embedded identity provider. The dashboard connects to the management server's built-in OAuth2 endpoints.
Coturn (TURN Server) Variables (Legacy)
The default quickstart deployment no longer uses a separate Coturn container. STUN functionality is now embedded in the relay service. The variables below are only relevant for legacy deployments or advanced configurations that still use Coturn.
Coturn configuration is generated from templates using these variables:
| Variable | Default | Description |
|---|---|---|
TURN_DOMAIN | - | TURN server domain |
TURN_USER | - | TURN username |
TURN_PASSWORD | - | TURN password |
TURN_MIN_PORT | 49152 | Minimum relay port |
TURN_MAX_PORT | 65535 | Maximum relay port |
TURN_EXTERNAL_IP_CONFIG | - | External IP configuration |
The Coturn service uses static ports: 3478 (STUN/TURN) and 5349 (TLS TURN).
Configuration Examples
Basic Setup
# setup.env
NETBIRD_DOMAIN="netbird.example.com"
NETBIRD_LETSENCRYPT_EMAIL="admin@example.com"
PostgreSQL Database
# setup.env
NETBIRD_STORE_CONFIG_ENGINE="postgres"
NETBIRD_STORE_ENGINE_POSTGRES_DSN="postgres://user:password@localhost:5432/netbird?sslmode=disable"
Custom Ports (Behind Reverse Proxy)
# setup.env
NETBIRD_DOMAIN="netbird.example.com"
NETBIRD_DISABLE_LETSENCRYPT="true"
NETBIRD_MGMT_API_PORT="443"
NETBIRD_SIGNAL_PORT="443"
Disable Anonymous Metrics
# setup.env
NETBIRD_DISABLE_ANONYMOUS_METRICS="true"
Enable API Rate Limiting
Set these in your container environment or docker-compose:
environment:
- NB_API_RATE_LIMITING_ENABLED=true
- NB_API_RATE_LIMITING_RPM=60
- NB_API_RATE_LIMITING_BURST=10
Enable the MCP Server
Set these in your container environment or docker-compose:
environment:
- NB_MCP_ENABLED=true
# Optional: expose only some tools
- NB_MCP_TOOLS=list_peers,get_peer,list_groups,get_group
Variable Precedence
Configuration values are applied in the following order (later values override earlier):
- Default values
- Configuration file (
config.yamlfor combined setup,management.jsonfor older multi-container setup) - Environment variables
- Command-line flags
See Also
- Self-hosting Quickstart Guide
- Advanced Self-hosting Guide
- Configuration Files Reference - Detailed documentation for docker-compose.yml, config.yaml, and other config files
- Management SQLite Store
- Management Postgres Store
- MCP Server for Self-Hosted NetBird

