# NetBird — Open Source WireGuard Mesh VPN with Zero Trust

> NetBird connects devices into a secure WireGuard-based overlay network with SSO, MFA, and granular access controls. Modern zero-trust networking with beautiful management UI.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

### SaaS (Fastest)

```bash
# Install NetBird client on any device
curl -fsSL https://pkgs.netbird.io/install.sh | sh

# Connect
netbird up --setup-key your-setup-key
```

### Self-Hosted

```bash
curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started-with-zitadel.sh | bash
```

## Intro

**NetBird** is an open-source, WireGuard-based mesh VPN and zero-trust networking platform. It connects your devices (laptops, servers, mobile phones) into a secure overlay network with end-to-end encryption, SSO authentication, multi-factor authentication, and fine-grained access controls — all managed through a beautiful web dashboard.

With 24.2K+ GitHub stars and BSD-3-Clause license, NetBird is a modern alternative to Tailscale and ZeroTier, offering a fully open-source stack with enterprise-ready features like zero-trust networking and posture checks.

## 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

```bash
# 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

```yaml
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

```bash
# 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)

```bash
# 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

```yaml
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

```yaml
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

| Feature | NetBird | Tailscale | Headscale | ZeroTier |
|---------|---------|-----------|-----------|----------|
| Open Source | Yes (full stack) | Client only | Yes (BSD) | Yes (BSL) |
| Self-hosted | Yes | No (SaaS) | Yes | Yes |
| Web UI | Beautiful | Yes | Basic | Yes |
| SSO | Built-in | Enterprise | Limited | Limited |
| MFA | Yes | Yes | Via OIDC | Yes |
| Posture checks | Yes | Enterprise | No | No |
| Mobile apps | Native | Native | Via Tailscale | Native |
| Protocol | WireGuard | WireGuard | WireGuard | Custom |

## 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](https://github.com/netbirdio/netbird) — 24.2K+ ⭐ | BSD-3
- Website: [netbird.io](https://netbird.io)

---
Source: https://tokrepo.com/en/workflows/netbird-open-source-wireguard-mesh-vpn-zero-trust-d3796427
Author: AI Open Source