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.

Overview

NetBird uses two types of environment variables:

  1. Setup Variables (NETBIRD_ prefix) - Used in docker-compose templates and setup.env for initial configuration
  2. 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

VariableDescriptionExample
NETBIRD_DOMAINYour NetBird domain namenetbird.example.com
NETBIRD_LETSENCRYPT_EMAILEmail for Let's Encrypt certificatesadmin@example.com
NETBIRD_DISABLE_LETSENCRYPTDisable automatic Let's Encrypttrue

Port Configuration

VariableDefaultDescription
NETBIRD_MGMT_API_PORT33073Management API port
NETBIRD_SIGNAL_PORT10000Signal server port
NETBIRD_RELAY_PORT33080Relay server port
NGINX_SSL_PORT443Dashboard HTTPS port

STUN Configuration

VariableDefaultDescription
NB_ENABLE_STUNtrueEnable embedded STUN server in relay
NB_STUN_PORTS3478STUN server UDP ports
NB_STUN_LOG_LEVELinfoSTUN server log level

Management Server Variables

Database Configuration

VariableDefaultDescription
NETBIRD_STORE_CONFIG_ENGINEsqliteStore 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_KEYAuto-generatedEncryption key for sensitive data

Single Account Mode

VariableDefaultDescription
NETBIRD_MGMT_SINGLE_ACCOUNT_MODE_DOMAIN-Domain for single account mode

Relay Configuration

VariableDescription
NETBIRD_RELAY_ENDPOINTRelay server endpoint URL
NETBIRD_RELAY_AUTH_SECRETShared authentication secret for relay

Signal Configuration

VariableDescription
NETBIRD_SIGNAL_PROTOCOLProtocol: http or https

DNS Configuration

VariableDefaultDescription
NETBIRD_MGMT_DNS_DOMAINnetbird.selfhostedDNS domain for peer resolution

TLS/Certificates

VariableDescription
NETBIRD_MGMT_API_CERT_FILEPath to TLS certificate file
NETBIRD_MGMT_API_CERT_KEY_FILEPath to TLS certificate key file

Metrics and Analytics

VariableDefaultDescription
NETBIRD_DISABLE_ANONYMOUS_METRICSfalseDisable 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

VariableDescription
NB_PORTServer port (overrides --port)
NB_DATADIRData directory (overrides --datadir)
NB_CONFIGConfig file path (overrides --config)
NB_LOG_LEVELLog level: debug, info, warn, error
NB_LOG_FILELog file path
NB_METRICS_PORTPrometheus metrics port
NB_LETSENCRYPT_DOMAINLet's Encrypt domain
NB_CERT_FILETLS certificate file
NB_CERT_KEYTLS certificate key file
NB_DNS_DOMAINDNS domain for peers
NB_DISABLE_GEOLITE_UPDATEDisable GeoLite database updates
NB_SETUP_PAT_ENABLEDEnable optional Personal Access Token creation from /api/setup during initial setup. See Automated Setup.

Advanced Runtime Variables

VariableDescription
NB_PPROF_ADDRStart 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_ENABLEDEnable activity log events
NB_GET_ACCOUNT_BUFFER_INTERVALAccount buffer interval duration
NB_SQL_MAX_OPEN_CONNSMaximum SQL database connections
NB_STORE_TRANSACTION_TIMEOUTStore transaction timeout
NB_ACCESS_LOG_STORE_ENGINEAccess log store engine: sqlite or postgres. Defaults to the main store engine
NB_ACCESS_LOG_POSTGRES_DSNConnection string for a dedicated access log PostgreSQL database. Defaults to the main store DSN
NB_ACCESS_LOG_SQLITE_FILEAccess log SQLite file, resolved against the data directory when relative. Defaults to access_logs.db
NB_ACCESS_LOG_SQL_MAX_OPEN_CONNSMaximum connections of the access log PostgreSQL pool. Defaults to NB_SQL_MAX_OPEN_CONNS
NB_API_RATE_LIMITING_ENABLEDEnable API rate limiting
NB_API_RATE_LIMITING_RPMRate limit requests per minute
NB_API_RATE_LIMITING_BURSTRate limit burst size
NETBIRD_METRICS_INTERVAL_IN_SECONDSMetrics 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.

VariableDefaultDescription
NB_MCP_ENABLEDfalseTurn 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_TOOLSAll toolsComma-separated list of the MCP tools to expose. An unknown tool name stops management at startup.
NB_MCP_OAUTH_KEYDatastore encryption keySecret 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

VariableDescription
NB_PORTSignal server port
NB_METRICS_PORTPrometheus metrics port
NB_SSL_DIRSSL certificates directory
NB_LETSENCRYPT_DOMAINLet's Encrypt domain
NB_LETSENCRYPT_LISTEN_ADDRESSAddress 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_FILETLS certificate file
NB_CERT_KEYTLS certificate key file
NB_LOG_LEVELLog level
NB_LOG_FILELog 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.

VariableOverridesDescription
NB_AUTH_SECRETserver.authSecretShared secret of the relay that runs inside netbird-server. With external relays, applies only when server.relays.secret is empty
NB_STORE_ENCRYPTION_KEYserver.store.encryptionKeyDatabase encryption key. On self-hosted Enterprise, also the key its integrations use

Relay Server Variables

Setup Variables

VariableDescription
NETBIRD_RELAY_TAGDocker image tag
NETBIRD_RELAY_PORTRelay port (default: 33080)
NETBIRD_RELAY_ENDPOINTRelay endpoint address
NETBIRD_RELAY_AUTH_SECRETAuthentication secret
NETBIRD_RELAY_DOMAINRelay server domain

Runtime Variables

VariableDefaultDescription
NB_LOG_LEVELinfoLog level
NB_LISTEN_ADDRESS:443Listen 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_STUNfalseEnable embedded STUN server
NB_STUN_PORTS3478STUN server UDP ports (comma-separated)
NB_STUN_LOG_LEVELinfoSTUN server log level

Dashboard Variables

VariableDescription
NETBIRD_MGMT_API_ENDPOINTManagement API endpoint URL
NETBIRD_MGMT_GRPC_API_ENDPOINTManagement gRPC endpoint
LETSENCRYPT_DOMAINLet's Encrypt domain (set to none if using own certs)
LETSENCRYPT_EMAILLet's Encrypt email

Coturn (TURN Server) Variables (Legacy)

Coturn configuration is generated from templates using these variables:

VariableDefaultDescription
TURN_DOMAIN-TURN server domain
TURN_USER-TURN username
TURN_PASSWORD-TURN password
TURN_MIN_PORT49152Minimum relay port
TURN_MAX_PORT65535Maximum 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):

  1. Default values
  2. Configuration file (config.yaml for combined setup, management.json for older multi-container setup)
  3. Environment variables
  4. Command-line flags

See Also