I maintain this and other Home Assistant add-ons in my free time: keeping up with upstream changes, HA changes, and testing on real hardware takes a lot of time (and some money). I use around 5-10 of my >110 addons so regularly I install test machines (and purchase some test services such as vpn) that I don't use myself to troubleshoot and improve the addons.

If this add-on saves you time or makes your setup easier, I would be very grateful for your support!

Addon information

About

NetBird is a secure, WireGuard-based overlay network platform. This add-on packages the management, signal, and optional dashboard services in a single monolithic Home Assistant add-on (no ingress UI, no split services). It uses the upstream NetBird Docker images for the binaries and dashboard assets.

Installation

The installation of this add-on is pretty straightforward and not different in comparison to installing any other Hass.io add-on.

Add my Hass.io add-ons repository to your Hass.io instance.
Install this add-on.
Click the Save button to store your configuration.
Start the add-on.
Check the logs of the add-on to see if everything went well.

Configuration

Important

: NetBird requires OIDC configuration. The add-on will generate a starter management.json in /data/netbird if one does not exist. Replace the placeholder OIDC values with your IdP configuration before connecting clients.

Example add-on options:

{
  "domain": "netbird.example.com",
  "management_port": 33073,
  "signal_port": 10000,
  "dashboard_port": 33080,
  "enable_dashboard": true,
  "auth_issuer": "https://accounts.example.com/",
  "auth_audience": "netbird",
  "auth_jwt_certs": "https://accounts.example.com/jwks.json",
  "auth_oidc_configuration_endpoint": "https://accounts.example.com/.well-known/openid-configuration",
  "auth_client_id": "netbird-dashboard",
  "auth_client_secret": "your-secret",
  "ssl_cert": "/ssl/fullchain.pem",
  "ssl_key": "/ssl/privkey.pem"
}

Options

Option	Description
`data_path`	Persistent data directory (default: `/data/netbird`).
`domain`	Public hostname used for NetBird endpoints.
`management_port`	Management API port.
`signal_port`	Signal service port.
`dashboard_port`	Dashboard port (only used if enabled).
`enable_dashboard`	Start the NetBird dashboard (requires OIDC settings).
`management_dns_domain`	DNS suffix handed to peers.
`single_account_domain`	Optional single-account mode domain.
`disable_anonymous_metrics`	Disable anonymous metrics.
`disable_default_policy`	Disable the default NetBird policy on first run.
`auth_*`	OIDC settings for the management server and dashboard.
`ssl_cert`, `ssl_key`	Optional TLS certificate/key paths.
`env_vars`	Extra environment variables passed into NetBird processes.

Files and persistent data

/data/netbird/management.json: management server configuration (generated on first start).
/data/netbird: runtime data for NetBird components.

Ports

33073/tcp: NetBird management API.
10000/tcp: NetBird signal.
33080/tcp: NetBird dashboard (optional).

Logs and status

The add-on uses s6 supervision; if any NetBird component exits, the supervisor restarts the service and logs the failure to the Home Assistant add-on log stream.

Local build/test

# From the repository root
ha addons build netbird
ha addons install ./netbird