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

常见问题

Q: NetBird 和 Tailscale 怎么选？ A: Tailscale 的 SaaS 体验更成熟，免费层有 100 设备限制。NetBird 完全开源，可以自托管且无设备限制。如果你在意数据主权和开源，选 NetBird。如果想要零运维体验，选 Tailscale。

Q: NetBird 和 Headscale 有什么区别？ A: Headscale 兼容 Tailscale 客户端（使用官方 iOS/Android 应用）。NetBird 使用自己的完整客户端栈。NetBird 的 Web UI 更完善，适合团队管理。Headscale 更适合个人使用。

Q: 性能如何？ A: 基于 WireGuard，性能接近原生网络。直接 P2P 连接时带宽可达本地网络的 90%+。只有在 NAT 穿透失败时才会通过 relay（TURN）服务器中转。

来源与致谢

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