How to Use NetBird: The Beginner's Guide (First Install, First Peer, Setup Keys, and the Self-Host Lane)

CodexFuse Team · 2026-11-01T11:04:42.793Z · 13 min read

What is NetBird, exactly?

NetBird is an open-source mesh VPN built on WireGuard that connects your devices into one private network with no inbound firewall ports to open. If you are learning how to use NetBird, the one-sentence version is this: you install a small client on each machine, the clients find each other through a management service, and traffic flows peer to peer over encrypted WireGuard tunnels. The project ships under a mixed license — BSD-3-Clause for most of the code, AGPLv3 for the management, signal, and relay services — and as of the v0.82.0 release (October 29, 2026) the GitHub repository holds roughly 30,500 stars and 1,800 forks, which makes it the largest self-hostable mesh-VPN project in the open-source world.

NetBird sits next to Tailscale in the mesh-VPN family, but the products are not rivals — read the Tailscale beginner guide first if you want the closed-ecosystem managed lane; NetBird is the lane where you can run the entire control plane yourself. There is no homonym confusion to worry about: page-one results for the name are the product's own docs and independent how-tos, not a competing product. Once your first peer is online you can confirm its overlay address with an IP lookup tool, which is handy when you start wiring access policies by address.

How do you use NetBird? The 10-step arc

Every NetBird setup tutorial reduces to one arc you can repeat for every device you own: install, enroll, connect, restrict. Here is the short version; the rest of this guide walks each step slowly.

1. Create a NetBird account at netbird.io and open the dashboard at app.netbird.io.
2. Install the client on your first machine: curl -fsSL https://pkgs.netbird.io/install.sh | sh on Linux.
3. Run sudo netbird up and authorize the machine in the browser tab that opens.
4. Check netbird status — you should see the peer online with an address in 100.64.0.0/10.
5. Ping your first peer; the connection works immediately because onboarding creates a Default Policy that allows all traffic.
6. Create a setup key in Settings → Setup Keys for headless machines.
7. Enroll the rest of your devices with netbird up --setup-key <KEY>.
8. Group your peers in the dashboard and write access policies that replace the default allow-all.
9. Delete or tighten the Default Policy so the network is allow-by-exception.
10. Decide whether the cloud control plane is enough — or self-host the stack with getting-started.sh.

How do you get started with NetBird Cloud?

You start at netbird.io, choose Get Started, and sign in through any OIDC identity provider — a Gmail or GitHub social login works for personal use. The official getting-started guide walks you through an in-dashboard onboarding wizard that asks how you plan to use the product: plain peer-to-peer connectivity, remote network access, or a mix.

The first thing to understand about the dashboard is the Default Policy. Onboarding creates one policy that allows every device to talk to every other device — this is why your first ping just works. It is also why step 9 of the arc exists: a mesh where everything can reach everything is a flat network, and flat networks are exactly what access policies exist to undo. For now, leave the Default Policy in place until every peer is enrolled and talking, then tighten it.

How do you install the NetBird client?

The fastest install on Linux is the official script: curl -fsSL https://pkgs.netbird.io/install.sh | sh. The same page ships native package repositories for apt, dnf, and yum, so Debian, Ubuntu, RHEL, and Rocky installs can use your normal package manager instead. Beyond Linux, the product covers Windows, macOS, Android, and iOS apps, Docker containers, routers like pfSense, OPNsense, MikroTik, and OpenWRT, and NAS boxes like Synology and TrueNAS — the install lane you pick decides how much of the arc is automated.

How do you join your first peer?

You enroll a machine by running sudo netbird up, which opens a browser tab for device authorization — the dashboard asks you to confirm that this machine belongs to your account. That interactive flow is perfect for your own laptop or server, because it ties the peer to your identity rather than to a shared secret.

On Linux the client creates a WireGuard interface named wt0 and the peer receives an overlay address from 100.64.0.0/10. Run netbird status --detail to see the peer's connection state: Connected (P2P) means the clients found a direct path, while Connected (Relayed) means traffic is falling back to a relay server. Ping that 100.64 address from another enrolled machine and the mesh is alive.

What is a NetBird setup key, and how do you make one?

A setup key is a token that lets machines join your network without the interactive browser login — it is how headless servers, containers, and bulk rollouts get enrolled. You create one in the dashboard under Settings → Setup Keys, where you choose between a one-off key (a single machine) and a reusable key (a configurable number of machines, unlimited by default).

Three details matter more than anything else about setup keys. First, the creation dialog pre-fills a 7-day expiry — clear that field and the key never expires, which is convenient and also a commitment, so prefer short-lived keys for anything you do not own. Second, revoking or expiring a key does not disconnect machines that already joined with it; you have to remove the peers themselves. Third, the key dialog offers an ephemeral-peer option that auto-removes the peer after it stays offline, which keeps short-lived CI runners and test VMs from accumulating in your dashboard forever.

How do access policies keep your network from being flat?

NetBird's rule is simple: nothing is reachable until a policy says so. NetBird access policies live under Access Control → Policies → Add policy, and each policy names a source group and a destination group, a protocol (ALL, TCP, UDP, or ICMP), and ports or port ranges — plus a direction flag for unidirectional versus bidirectional traffic. There are no DENY rules and no ordering: NetBird only has ALLOW policies, which keeps the mental model small.

The default group called All contains every peer and cannot be deleted, so the usual beginner pattern is: put devices into named groups (laptops, servers, iot), write policies between the groups with the minimum ports each actually needs, and then tighten or delete the onboarding Default Policy. One load-bearing edge case: standalone Network resources in the dashboard are deny-by-default even before you touch the Default Policy, so if a network route resource is unreachable while peers can ping, the missing piece is a policy covering the resource, not the peer.

How do peers find each other without open firewall ports?

NetBird clients never need an inbound port open — they connect outbound to the management, signal, and relay services, and peers negotiate direct paths with ICE and STUN-based NAT traversal, the same family of techniques WebRTC uses. When no direct path exists, traffic falls back to the relay server automatically, which is exactly what the Connected (Relayed) marker in netbird status tells you.

This is the property that makes SSH-over-the-mesh practical: you can close public SSH on your servers because the mesh gives you a private path in. The safety rule is to close port 22 only after you have verified mesh SSH works and you still have an out-of-band recovery path — a serial console or provider rescue shell — in case the mesh client ever fails to start.

How do you self-host NetBird?

Self-hosting runs the whole control plane — management, signal, relay — on your own infrastructure with the official quickstart: curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash. Pin a tagged release and read the script before you pipe it, because the latest one-liner drifts and the self-host stack has changed shape recently. The requirements are modest: a Linux VM with at least 1 vCPU and 2 GB of RAM, a public domain, TCP 80 and 443 plus UDP 3478 reachable, and Docker with the Compose plugin plus curl and jq.

The script asks three things: your domain, which reverse proxy to use (Traefik is the tested default and brings automatic Let's Encrypt TLS), and whether to enable the NetBird Proxy service. This is the netbird self host path in full: the script generates the netbird docker compose stack — docker-compose.yml plus setup.env and configure.sh — in the run directory. The default stack is three containers: netbird-server (management API, signal, and relay with an embedded STUN server, plus an embedded IdP running in single-account mode since v0.10.1), the dashboard, and Traefik. Your first admin account is created through a setup wizard on your first dashboard visit — and if you want a refresher on the container tooling before you start, the Docker beginner guide covers the Compose patterns this stack uses; the what is VPS hosting guide explains the kind of server this stack expects.

Two self-host facts beginners miss. First, peers enroll against your server with an extra flag: sudo netbird up --setup-key <KEY> --management-url https://netbird.example.com — without --management-url the client phones home to NetBird Cloud. Second, the self-hosted management service collects anonymous usage metrics by default: peer counts, account and feature counts, the IdP manager type, and a per-installation ID, pushed every 12 hours. Say it once and remember it: you opt out with the --disable-anonymous-metrics=true startup flag or NETBIRD_DISABLE_ANONYMOUS_METRICS=true in setup.env, then re-run ./configure.sh to apply it.

What is the /dev/net/tun gotcha in containers?

NetBird is a WireGuard client, and WireGuard needs the kernel TUN device — containers do not always have it. The classic failure is a Proxmox LXC unprivileged container: the install succeeds, netbird up fails, and the official Proxmox guide's fix is to bind the host's /dev/net/tun into the container and allow character device 10:200 in /etc/pve/lxc/<id>.conf, then restart the container.

On plain Linux or Docker the fallback is the same shape: check ls -l /dev/net/tun, and if it is missing create it with sudo mkdir -p /dev/net && sudo mknod /dev/net/tun c 10 200 && sudo chmod 0755 /dev/net/tun — and for Docker containers add the matching --device /dev/net/tun flag so the container can see it.

NetBird vs Tailscale — which should a beginner pick?

The honest draw-the-line answer: Tailscale is the managed lane — you trade control for zero operational burden. NetBird is the self-hostable lane — you keep the control plane on your own hardware at the cost of running it. Both are WireGuard-based mesh VPNs, both enroll peers in minutes, and for a homelabber whose goal is simply reaching a home server from anywhere, either works on day one.

What are the beginner mistakes to avoid?

Every NetBird beginner thread repeats the same handful of mistakes — most of them are setup-key hygiene and the two one-liner gotchas above.

Sources

Version, stars, and license verified at write time on 2026-11-01: NetBird v0.82.0 was released on 2026-10-29 per the GitHub releases API, the netbirdio/netbird repository held about 30,500 stars and 1,800 forks per the GitHub repo API, and the LICENSE file on the main branch shows BSD-3-Clause for most of the repo with AGPLv3 for the management, signal, relay, and combined directories. Cloud onboarding, the app.netbird.io dashboard, the onboarding Default Policy, setup-key types and the 7-day pre-filled expiry, ALLOW-only access policies with source-to-destination groups, protocols and ports, and the no-inbound-ports client model come from the official NetBird documentation (get-started, setup keys, access-control, zero-trust use cases, networks, and FAQ pages). The self-hosted quickstart — getting-started.sh, the 1 vCPU / 2 GB RAM / domain / TCP 80+443 / UDP 3478 requirements, the Traefik-first prompts, the docker-compose.yml + setup.env + configure.sh files, the 3-container default stack with embedded STUN and embedded single-account IdP, the --management-url peer enrollment flag, and the anonymous-metrics defaults and opt-out (12-hour interval, --disable-anonymous-metrics / NETBIRD_DISABLE_ANONYMOUS_METRICS, NETBIRD_METRICS_INTERVAL_IN_SECONDS) — come from the official self-hosting quickstart and environment-variables docs, corroborated by a self-host guide verified against v0.80.0. Client commands, the 100.64.0.0/10 overlay, the wt0 interface, the Connected (Relayed) vs Connected (P2P) states, and the /dev/net/tun manual-creation fallback come from an independent Linux install guide; the Proxmox LXC TUN binding fix comes from NetBird's own Proxmox documentation. The setup-key revocation limitation and SSH-over-mesh port-22 hardening come from a 2026 mesh-VPN comparison. Homelab arcs were cross-checked against independent tutorials on thefilibusterblog, maketecheasier, and dev.to. Pricing and free-tier peer limits were not verifiable from an official source at write time, so no claim is made about them.

Frequently Asked Questions

Is NetBird really free?

NetBird Cloud has a free tier for personal use and the self-hosted stack is open source, so running your own control plane costs you only the server it runs on. The exact free-tier peer limits were not published on an official page I could verify at write time, so check the current pricing page before planning around a number.

How is NetBird different from plain WireGuard?

Plain WireGuard is a protocol: you hand-write every peer's config and keys. NetBird is the management layer on top of it — identity-based enrollment, setup keys, groups, ALLOW-only access policies, NAT traversal, and relay fallback — so you never touch a WireGuard config file by hand.

Can I self-host NetBird for free?

Yes. The getting-started.sh quickstart deploys management, signal, relay, and dashboard in three containers on any Linux VM with 1 vCPU and 2 GB of RAM, a public domain, and TCP 80/443 plus UDP 3478 reachable. The embedded IdP runs in single-account mode, and Traefik handles automatic Let's Encrypt TLS.

What happens if I lose my setup key?

Nothing urgent: a setup key alone cannot remove anything, and revoking or expiring it only stops new machines from enrolling. Rotate the key, create a short-lived replacement, and remove any peers you do not recognize in the dashboard — remember that revoking the key does not disconnect machines that already joined.

Does NetBird collect telemetry?

The self-hosted management service collects anonymous usage metrics by default — peer counts, account and feature counts, the IdP manager type, and a per-installation ID, pushed every 12 hours. You opt out with the --disable-anonymous-metrics=true startup flag or NETBIRD_DISABLE_ANONYMOUS_METRICS=true in setup.env, then re-run ./configure.sh.