NetBird
5 min read
NetBird is an open-source overlay network built on WireGuard. Instead of routing everything through a VPN gateway, it forms a peer-to-peer mesh: every machine running the client gets an address in the 100.64.0.0/10 range and talks directly to every other peer it is allowed to reach. A central control plane distributes keys and policy but never sees traffic.
It is BSD-3 licensed and can be used as a hosted service (NetBird Cloud, free tier available) or self-hosted in full.
Architecture
Four components, only the first of which is on the data path:
• Client / agent — runs on each machine. Generates the WireGuard key pair (the private key never leaves the host), registers with Management via SSO or a setup key, receives network updates, brings up the tunnels, and applies firewall and DNS rules.
• Management service — the control plane. Authenticates peers, keeps the network map and the peers' WireGuard public keys, assigns overlay IPs, distributes changes, and holds access control and DNS configuration.
• Signal service — a lightweight notification bus peers use to find each other and exchange ICE candidates. Messages are point-to-point encrypted, so Signal cannot read them, and it drops out of the picture once a direct connection is up.
• Relay service — a TURN server (Coturn, or a WebSocket-based relay) used only when NAT or firewalls defeat direct connection. Traffic stays end-to-end encrypted through it.
Connection setup: peers gather candidates with ICE (via Pion's WebRTC stack), exchange them over Signal, then establish a direct WireGuard tunnel. If that fails, traffic falls back to the Relay transparently. Because encryption is WireGuard's own cryptokey routing done at the peers, no intermediary service can decrypt anything — which is what makes self-hosting optional rather than obligatory.
Concepts
• Groups — collections of peers. A peer can be in several groups. The built-in All group contains every peer and cannot be edited.
• Policies — rules for which group may reach which, over which protocols and ports, uni- or bidirectionally. Only ALLOW policies exist — there is no ordering or priority, so a connection is permitted if any policy permits it. A new account starts with a permissive default policy (All → All), i.e. full mesh; tightening the network means replacing it.
• Posture checks — attach conditions to a policy so a peer only connects if it meets requirements (client version, OS, geo-location, network location, firewall/antivirus/MDM state).
• Network routes — expose a subnet, VPC or on-prem network through a peer acting as routing peer, for site-to-site access without installing the client everywhere.
• DNS — private nameservers and per-zone resolution pushed to peers.
• Setup keys — non-interactive enrolment for servers and containers, as an alternative to SSO login.
Identity comes from an IdP: Google, Microsoft, Okta and other OIDC providers, with user/group provisioning and MFA enforcement. There is a REST API and a Terraform provider, plus audit logs and event streaming to a SIEM.
Install & use
Clients run on Linux, macOS, Windows, Android, iOS, Docker, and on routers and appliances — Synology, TrueNAS, pfSense, OPNsense, OpenWrt, MikroTik, Raspberry Pi, Proxmox VE.
sh
netbird up # SSO login in the browser, then connect
netbird up --setup-key <KEY> # unattended enrolment
netbird status # peer connection status
netbird down # disconnect, daemon goes idle
sh
docker run --network host --privileged --rm -d \
-e NB_SETUP_KEY=<KEY> -v netbird-client:/var/lib/netbird \
netbirdio/netbird:<TAG>
Other useful commands:
• netbird ssh — SSH to a peer over the overlay, including command execution and port forwarding (the target needs --allow-server-ssh)
• netbird expose — publish a local service through NetBird's reverse proxy, optionally gated by PIN, password or SSO group
• netbird service install|start|stop|restart|reconfigure — daemon lifecycle; --disable-profiles / --disable-update-settings lock the configuration down
• netbird status --check live|ready|startup — health checks for container orchestrators
• netbird debug bundle — diagnostic archive; debug for <duration> captures trace logs, debug log level <level> adjusts verbosity live, and debug trace simulates a packet through the firewall rules to work out why an ACL is blocking it
Configuration precedence, highest first: environment variables (NB_WIREGUARD_PORT) → CLI flags (--wireguard-port) → the profile JSON in the platform config directory.
Self-hosting
Requirements are modest: a Linux VM with 1 CPU and 2 GB RAM, a public domain resolving to it, and TCP 80/443 plus UDP 3478 reachable. Docker with the compose plugin, jq and curl are needed for the installer.
sh
curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash
This generates a docker-compose.yml, config.yaml and env files for all services. The script offers five reverse-proxy options — Traefik with automatic Let's Encrypt (the default and simplest), an existing Traefik, an Nginx template, Nginx Proxy Manager, or Caddy/manual. Optional extras: the NetBird Proxy service for selectively exposing internal resources (needs a wildcard DNS record *.netbird.example.com), and CrowdSec for IP-reputation blocking.
The deployment starts with no users — visit https://netbird.example.com/setup to create the admin account. User management is handled by an embedded Dex, or delegated to an external IdP for SSO.
Compared to plain WireGuard
Plain WireGuard requires hand-maintaining AllowedIPs and public keys on every peer, and a publicly reachable endpoint (or manual NAT traversal). NetBird keeps WireGuard as the data plane but automates key distribution, addressing, NAT traversal and access control, and adds identity-based policy on top. The trade-off is a control plane that has to exist somewhere — hosted or self-run.