NetBird is a peer-to-peer VPN built on top of WireGuard that uses WebRTC ICE for NAT traversal and automatic peer discovery. The architecture is designed to establish direct, encrypted connections between peers whenever possible, falling back to relay servers when necessary.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/netbirdio/netbird/llms.txt
Use this file to discover all available pages before exploring further.
Design Philosophy
NetBird’s architecture is built on several core principles:Zero Configuration
Peers automatically discover each other and establish connections without manual configuration of ports, firewall rules, or VPN gateways. The system handles:- Automatic IP address assignment
- Peer discovery through the management service
- NAT traversal using STUN/TURN servers
- Dynamic network topology updates
Peer-to-Peer First
Direct peer-to-peer connections are always preferred over relay connections for optimal performance:- WebRTC ICE is used to discover connection candidates and establish direct paths
- STUN servers help peers discover their public endpoints
- Relay servers (TURN) are used only when direct connection fails
- WireGuard provides the actual encrypted tunnel once a path is established
Centralized Control, Distributed Data
While the Management Service maintains network state and access policies, actual data flows directly between peers:- Management Service: Centralized control plane for authentication, authorization, and network configuration
- Signal Service: Facilitates WebRTC signaling for peer connection negotiation
- Data Plane: Fully distributed peer-to-peer WireGuard tunnels
High-Level Architecture
1. NetBird Client (Agent)
Runs on each machine in the network. Key responsibilities:- Manages local WireGuard interface
- Connects to Management and Signal services
- Performs ICE candidate discovery via STUN servers
- Establishes and maintains peer connections
- Applies network policies (ACLs, routes, DNS)
2. Management Service
The control plane that orchestrates the network:- Authenticates peers using SSO or setup keys
- Maintains the network map (which peers can connect to each other)
- Distributes peer configurations and network updates
- Manages access control policies and routing rules
- Stores network state and configuration
3. Signal Service
Facilitates the WebRTC signaling process:- Relays encrypted connection offer/answer messages between peers
- Exchanges ICE candidates for NAT traversal
- Does not see or store actual peer data
- Lightweight, stateless message forwarder
4. Relay Servers (TURN)
Provide fallback connectivity when direct connection fails:- Used when peers are behind strict NATs or firewalls
- Relay encrypted WireGuard traffic between peers
- Only see encrypted packets (end-to-end encryption maintained)
- NetBird uses Coturn for STUN/TURN functionality
Connection Flow
Network Map Distribution
The Management Service maintains a “network map” for each account, which defines:- Peers: All machines in the network with their public keys and metadata
- Access Policies: Which peers are allowed to connect to each other
- Routes: Network routes that should be applied
- DNS Configuration: Custom DNS zones and nameservers
- Firewall Rules: Traffic filtering rules
Security Architecture
Multiple Layers of Encryption
- WireGuard Encryption: All peer-to-peer traffic is encrypted using WireGuard’s Noise protocol
- Signaling Encryption: WebRTC offers/answers are encrypted before being sent through Signal service
- TLS: All connections to Management and Signal services use TLS
Zero-Trust Model
- Each peer has its own WireGuard key pair
- Peer authentication happens through SSO or setup keys
- Access control policies are enforced at the peer level
- No implicit trust between peers
Optional Quantum Resistance
NetBird supports Rosenpass for post-quantum secure key exchange:- Provides quantum-resistant pre-shared keys for WireGuard
- Can run in permissive mode (fallback to WireGuard-only) or strict mode
- Enhances security for long-term protection
Scalability Considerations
Horizontal Scaling
- Management and Signal services can be scaled horizontally
- Relay servers can be distributed geographically
- Network state can be stored in distributed databases
Efficient Updates
- Only affected peers receive updates when network topology changes
- Incremental updates reduce bandwidth and processing overhead
- Serial numbers prevent processing outdated configurations
Resource Efficiency
- Kernel WireGuard implementation minimizes CPU overhead
- Direct peer connections eliminate relay server load when possible
- eBPF-based packet filtering reduces kernel overhead
Platform Support
NetBird runs on:- Desktop: Linux, macOS, Windows
- Mobile: iOS, Android
- Embedded: OpenWRT, serverless environments
- Containers: Docker with host or container networking modes
Next Steps
How It Works
Detailed connection flow and NAT traversal process
Components
Deep dive into each architectural component