NetBird — Open Source WireGuard Mesh VPN with Zero Trust

What NetBird Does

• Mesh VPN: Direct peer-to-peer WireGuard connections between all devices
• SSO Integration: Login via Google, Microsoft, Auth0, Keycloak, Zitadel, Authentik
• MFA: Multi-factor authentication for network access
• Access Groups: Organize devices into groups with policy-based access
• Setup Keys: Pre-shared keys for headless device registration
• Network Routing: Route local network subnets through NetBird peers
• Exit Nodes: Route all traffic through a designated peer
• Posture Checks: Verify device compliance (OS version, geo-location, etc.)
• Activity Monitoring: Real-time connection logs and audit trails
• Web Dashboard: Beautiful web UI for managing peers, groups, and policies

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ NetBird      │     │  Management  │     │ NetBird      │
│ Peer 1       │◀───▶│  Service     │◀───▶│ Peer 2       │
│ (Laptop)     │     │  + Signal    │     │ (Server)     │
└──────┬───────┘     │  + Relay     │     └──────┬───────┘
       │             └──────────────┘            │
       │                                          │
       │       Direct WireGuard P2P              │
       └──────────────────────────────────────────┘
         Encrypted mesh network (100x100)

Self-Hosting

All-in-One Installer

# Install with Zitadel (identity provider included)
curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started-with-zitadel.sh | bash

# Follow prompts for:
# - Domain name
# - Email for Let's Encrypt
# - Admin credentials

This sets up:

• NetBird Management Service
• Signal Server (for connection setup)
• Relay (TURN) server
• Zitadel (identity provider)
• Dashboard UI
• Caddy (HTTPS reverse proxy)

Docker Compose Components

services:
  management:
    image: netbirdio/management:latest
    ports:
      - "33073:33073"
    volumes:
      - ./config/management.json:/etc/netbird/management.json

  signal:
    image: netbirdio/signal:latest
    ports:
      - "10000:10000"

  dashboard:
    image: netbirdio/dashboard:latest
    environment:
      NETBIRD_MGMT_API_ENDPOINT: https://netbird.yourdomain.com

  coturn:
    image: coturn/coturn:latest
    network_mode: host
    volumes:
      - ./config/turnserver.conf:/etc/turnserver.conf

Client Installation

Linux / macOS / Windows

# Linux
curl -fsSL https://pkgs.netbird.io/install.sh | sh
netbird up

# macOS (Homebrew)
brew install netbirdio/tap/netbird
netbird up

# Windows
# Download MSI from GitHub releases, then:
netbird up

Mobile

• iOS: App Store → "NetBird"
• Android: Google Play → "NetBird"

Headless (Server)

# Generate setup key in dashboard first
netbird up --setup-key YOUR-SETUP-KEY 
  --management-url https://netbird.yourdomain.com

Key Features

Setup Keys

One-off key:
  Single-use, expires immediately after use
  For secure onboarding of individual devices

Reusable key:
  Multiple devices can register with same key
  Useful for fleet deployment

Ephemeral peers:
  Automatically deleted after disconnection
  Perfect for CI/CD ephemeral environments

Access Control Policies

Group: engineers
  Members: alice@company.com, bob@company.com
  Allowed networks: 10.0.0.0/24 (dev environment)

Group: admins
  Members: alice@company.com
  Allowed networks: 10.0.0.0/24, 10.1.0.0/24 (all environments)

Group: contractors
  Members: contractor@external.com
  Allowed networks: specific services only
  Posture checks: OS version ≥ Windows 11 / macOS 14

Network Routing

Route a subnet through a NetBird peer:

Office subnet: 192.168.100.0/24
Router peer: office-gateway

1. Install NetBird on office-gateway machine
2. Enable IP forwarding
3. In NetBird dashboard → Network Routes → Add route
4. Select peer, enter network, assign to group

All peers in that group can now access 192.168.100.0/24

Posture Checks

Policy: Production Access
  Required conditions:
    - OS Version: Windows ≥ 11 OR macOS ≥ 14 OR Linux kernel ≥ 5.15
    - NetBird version: ≥ 0.26.0
    - Geographic location: Not in [CN, RU, KP]
    - Process running: antivirus-agent

Devices that don't meet conditions are denied access.

NetBird vs Alternatives

FAQ

Q: NetBird or Tailscale — which should I pick? A: Tailscale's SaaS experience is more mature, with a 100-device free tier limit. NetBird is fully open source, can be self-hosted, and has no device limits. If you care about data sovereignty and open source, pick NetBird. If you want a zero-ops experience, pick Tailscale.

Q: What's the difference between NetBird and Headscale? A: Headscale is compatible with Tailscale clients (uses the official iOS/Android apps). NetBird uses its own complete client stack. NetBird's web UI is more polished and better for team management. Headscale is better suited for personal use.

Q: How's the performance? A: Built on WireGuard, performance is close to native networking. Direct P2P connections deliver 90%+ of local network bandwidth. Traffic only relays through a TURN server when NAT traversal fails.

Sources & Credits

• GitHub: netbirdio/netbird — 24.2K+ ⭐ | BSD-3
• Website: netbird.io