Set Up Netbird as a Self-Hosted Peer-to-Peer VPN

What Netbird Actually Does (and Why It’s Different)

Most VPN setups force all your traffic through a central server, which means latency, bandwidth bottlenecks, and a single point of failure baked right into the architecture. Netbird takes a different approach: it builds an encrypted mesh network where devices connect directly to each other using WireGuard under the hood, with a management plane that handles authentication, peer discovery, and access control. You get the security posture of a traditional VPN without the hairpin routing that makes them slow.

The self-hosted path is where Netbird earns its reputation among privacy-focused engineers and homelab operators. Instead of sending your peer metadata to Netbird’s cloud, you run the management server, signal server, and TURN relay on your own infrastructure. Your network topology stays yours. Setup takes roughly an hour if you know your way around Docker and a Linux server, and the result is a production-grade overlay network that works across NATs, firewalls, and mobile connections without manual port forwarding.

What You Need Before You Start

You need a publicly accessible Linux server to host the management stack. A small VPS works fine – Netbird’s management components are lightweight and run comfortably on 1-2 vCPUs and 2GB of RAM. The server needs ports 80 and 443 open for the web UI and API, port 3478 for STUN/TURN, and port 10000 (UDP) for the TURN relay traffic. You’ll also need a domain name pointed at that server, because the TLS certificate is non-negotiable for the signal server to function correctly.

Docker and Docker Compose are the fastest path to a working install. Netbird publishes an official docker-compose.yml that bundles the management server, signal server, Coturn (the TURN relay), and Zitadel (the identity provider) into a single stack. Zitadel handles OAuth2 authentication, so your peers authenticate with real user accounts rather than pre-shared keys. If you already run your own identity provider like Keycloak, Netbird supports that too, but Zitadel is what the official quickstart configures out of the box.

Before pulling any containers, generate a wildcard or multi-domain TLS certificate for your domain. Certbot with the DNS challenge method works cleanly here because you won’t need to expose port 80 during renewal. Store the certificate and key somewhere stable – /etc/letsencrypt/live/yourdomain.com/ is the conventional location – and plan to mount those paths into the Compose stack.

Running the Install

Netbird provides a setup script that generates a preconfigured docker-compose.yml and a .env file tailored to your domain and chosen ports. Pull it with curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/netbird_install.sh | bash, or download and inspect it first if you prefer not to pipe scripts directly to bash – which is fair practice regardless of how well you trust the source. The script asks for your domain, your desired management URL, and whether you want to use the bundled Zitadel or an external IdP.

Once the script finishes generating configs, run docker compose up -d from the directory it created. Zitadel takes a minute or two to initialize its database on first boot – watch the logs with docker compose logs -f zitadel until you see the ready signal. After that, navigate to your management URL in a browser. You’ll land on the Netbird dashboard, which prompts you to complete Zitadel’s admin setup: create an admin user, configure the OAuth2 application, and copy the client credentials back into Netbird’s settings page. The dashboard walks you through each step with inline instructions.

With the server side running, installing the Netbird client on your devices is straightforward. On Linux, the official install script handles repository setup and service registration in one command. On macOS and Windows, there are native packages. Once installed, run netbird up --management-url https://your-management-domain.com and authenticate through the browser flow that opens. The client registers itself with your management server, negotiates a WireGuard key pair, and appears in your dashboard’s peer list within seconds.

Peer-to-peer connections establish automatically when two clients can reach each other directly. When they can’t – because both are behind strict NATs – traffic routes through your Coturn relay. You can verify which path a connection is using by running netbird status on any client: it shows each peer, its assigned IP in the 100.x.x.x range, connection latency, and whether the path is direct or relayed. Direct connections typically show single-digit millisecond latency between nearby hosts, which is the practical difference between a mesh VPN and a hub-and-spoke setup.

Access Control and Network Policy

Netbird’s access control system works through groups and policies defined in the dashboard. Every peer belongs to at least one group, and policies specify which groups can communicate with which other groups. By default, a new installation creates an “All” group and a permissive policy that lets every peer talk to every other peer. That’s fine for a homelab, but for any multi-user or multi-tenant setup, you’ll want to tighten this immediately.

A practical starting structure separates peers into groups by function: one group for personal devices, one for servers, one for trusted external users. You then create policies that allow personal devices to reach servers bidirectionally, but prevent external users from reaching personal devices entirely. Each policy maps to WireGuard AllowedIPs rules that the management server pushes to clients automatically – you don’t touch config files on individual machines after the initial setup.

Netbird also supports network routes, which let a single peer act as a gateway for a subnet not running the Netbird client. If you have a LAN segment at 192.168.1.0/24 that you want reachable from all Netbird peers, you designate one machine on that LAN as a route peer and publish the subnet through the dashboard. All other clients automatically get a route entry pointing that prefix at the designated peer. This makes it viable for accessing lab equipment, printers, or NAS devices that don’t run the client directly.

One operational detail worth keeping in mind: the management server is the control plane, not the data plane. If your management server goes offline, existing peer connections stay up because WireGuard maintains its tunnels independently. New peers can’t register and policy changes won’t propagate, but nothing breaks for clients already connected. That architecture means a brief management server outage – a reboot, a cert renewal, a container update – doesn’t drop your active network, which is a meaningful difference from VPN designs where the central server carries all the traffic.