# netbirdio/netbird architecture

> Architecture diagram of the GitHub repository netbirdio/netbird, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/netbirdio/netbird
- Repository: https://github.com/netbirdio/netbird

## Overview

NetBird is a cross-platform WireGuard overlay-network agent paired with a centralized management and access-control platform. A user starts or configures the client through its CLI or platform SDK; the daemon authenticates and receives network configuration, then brings up the encrypted tunnel, discovers peers, and applies routes, DNS, and firewall policy. The README also documents relay fallback, SSH, and reverse-proxy capabilities. The tree and sampled excerpts support the client-side architecture; management, signal, and relay interactions are based on README documentation, not inspected server source.

Main entry points: [`client/internal/engine.go`](https://github.com/netbirdio/netbird/blob/main/client/internal/engine.go) (Client engine), [`client/internal/peer/conn.go`](https://github.com/netbirdio/netbird/blob/main/client/internal/peer/conn.go) (Peer negotiation), [`client/cmd/service_controller.go`](https://github.com/netbirdio/netbird/blob/main/client/cmd/service_controller.go) (Daemon service), [`client/cmd/root.go`](https://github.com/netbirdio/netbird/blob/main/client/cmd/root.go) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Client entry points"]
  node_cli["CLI commands<br/>[root.go]"]
  node_sdk["Platform SDKs<br/>[profile_manager.go]"]
  node_daemon["Daemon service"]
end

subgraph group_control["Control and configuration"]
  node_engine["Client engine<br/>[engine.go]"]
  node_auth["Authentication<br/>[auth.go]"]
  node_profiles["Profile management<br/>[profilemanager.go]"]
  node_state[("Local state<br/>[state.go]")]
end

subgraph group_connectivity["Peer connectivity"]
  node_wg["WireGuard interface<br/>[interface.go]"]
  node_peer["Peer negotiation<br/>[conn.go]"]
  node_ice["ICE discovery<br/>[agent.go]"]
end

subgraph group_network["Network policy"]
  node_acl["Access policies<br/>[manager.go]"]
  node_firewall["Host firewall<br/>[firewall.go]"]
  node_routes["Route manager<br/>[manager.go]"]
  node_dns["Private DNS<br/>[server.go]"]
end

subgraph group_access["Access features"]
  node_ssh["Policy-based SSH<br/>[engine_ssh.go]"]
  node_expose["Reverse proxy<br/>[manager.go]"]
  node_forward["Port forwarding<br/>[manager.go]"]
end

node_user(("User"))
node_management["Management service"]
node_signal["Signal service"]
node_relay["Relay service"]

node_user -->|"runs commands"| node_cli
node_user -->|"uses app"| node_sdk
node_cli -->|"controls daemon"| node_daemon
node_sdk -->|"controls daemon"| node_daemon
node_daemon -->|"hosts engine"| node_engine
node_engine -->|"authenticates"| node_auth
node_auth -->|"requests identity"| node_management
node_engine -->|"syncs configuration"| node_management
node_engine -->|"manages profiles"| node_profiles
node_profiles -->|"persists settings"| node_state
node_engine -->|"stores state"| node_state
node_engine -->|"applies policy"| node_acl
node_acl -->|"installs rules"| node_firewall
node_engine -->|"configures routes"| node_routes
node_engine -->|"configures DNS"| node_dns
node_engine -->|"configures tunnel"| node_wg
node_engine -->|"manages peers"| node_peer
node_peer -->|"discovers candidates"| node_ice
node_peer -->|"negotiates peers"| node_signal
node_ice -->|"establishes direct path"| node_wg
node_peer -.->|"relays fallback traffic"| node_relay
node_engine -->|"manages SSH"| node_ssh
node_engine -->|"manages proxy"| node_expose
node_engine -->|"manages forwarding"| node_forward

click node_cli "https://github.com/netbirdio/netbird/blob/main/client/cmd/root.go"
click node_sdk "https://github.com/netbirdio/netbird/blob/main/client/mobile/profile_manager.go"
click node_daemon "https://github.com/netbirdio/netbird/blob/main/client/cmd/service_controller.go"
click node_engine "https://github.com/netbirdio/netbird/blob/main/client/internal/engine.go"
click node_auth "https://github.com/netbirdio/netbird/blob/main/client/internal/auth/auth.go"
click node_profiles "https://github.com/netbirdio/netbird/blob/main/client/internal/profilemanager/profilemanager.go"
click node_management "https://github.com/netbirdio/netbird/tree/main/management"
click node_signal "https://github.com/netbirdio/netbird/tree/main/signal"
click node_wg "https://github.com/netbirdio/netbird/blob/main/client/iface/device/interface.go"
click node_peer "https://github.com/netbirdio/netbird/blob/main/client/internal/peer/conn.go"
click node_ice "https://github.com/netbirdio/netbird/blob/main/client/internal/peer/ice/agent.go"
click node_relay "https://github.com/netbirdio/netbird/tree/main/relay"
click node_acl "https://github.com/netbirdio/netbird/blob/main/client/internal/acl/manager.go"
click node_firewall "https://github.com/netbirdio/netbird/blob/main/client/firewall/manager/firewall.go"
click node_routes "https://github.com/netbirdio/netbird/blob/main/client/internal/routemanager/manager.go"
click node_dns "https://github.com/netbirdio/netbird/blob/main/client/internal/dns/server.go"
click node_ssh "https://github.com/netbirdio/netbird/blob/main/client/internal/engine_ssh.go"
click node_expose "https://github.com/netbirdio/netbird/blob/main/client/internal/expose/manager.go"
click node_forward "https://github.com/netbirdio/netbird/blob/main/client/internal/portforward/manager.go"
click node_state "https://github.com/netbirdio/netbird/blob/main/client/internal/state.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_sdk,node_daemon,node_user toneBlue
class node_engine,node_auth,node_profiles,node_state toneAmber
class node_wg,node_peer,node_ice toneMint
class node_acl,node_firewall,node_routes,node_dns toneRose
class node_ssh,node_expose,node_forward toneIndigo
class node_management,node_signal,node_relay toneTeal
```

## Components

### Client entry points

- [CLI commands](https://github.com/netbirdio/netbird/blob/main/client/cmd/root.go): `client/cmd/root.go`
- [Platform SDKs](https://github.com/netbirdio/netbird/blob/main/client/mobile/profile_manager.go): `client/mobile/profile_manager.go`
- [Daemon service](https://github.com/netbirdio/netbird/blob/main/client/cmd/service_controller.go): `client/cmd/service_controller.go`

### Control and configuration

- [Client engine](https://github.com/netbirdio/netbird/blob/main/client/internal/engine.go): `client/internal/engine.go`
- [Authentication](https://github.com/netbirdio/netbird/blob/main/client/internal/auth/auth.go): `client/internal/auth/auth.go`
- [Profile management](https://github.com/netbirdio/netbird/blob/main/client/internal/profilemanager/profilemanager.go): `client/internal/profilemanager/profilemanager.go`
- [Local state](https://github.com/netbirdio/netbird/blob/main/client/internal/state.go): `client/internal/state.go`

### Peer connectivity

- [WireGuard interface](https://github.com/netbirdio/netbird/blob/main/client/iface/device/interface.go): `client/iface/device/interface.go`
- [Peer negotiation](https://github.com/netbirdio/netbird/blob/main/client/internal/peer/conn.go): `client/internal/peer/conn.go`
- [ICE discovery](https://github.com/netbirdio/netbird/blob/main/client/internal/peer/ice/agent.go): `client/internal/peer/ice/agent.go`

### Network policy

- [Access policies](https://github.com/netbirdio/netbird/blob/main/client/internal/acl/manager.go): `client/internal/acl/manager.go`
- [Host firewall](https://github.com/netbirdio/netbird/blob/main/client/firewall/manager/firewall.go): `client/firewall/manager/firewall.go`
- [Route manager](https://github.com/netbirdio/netbird/blob/main/client/internal/routemanager/manager.go): `client/internal/routemanager/manager.go`
- [Private DNS](https://github.com/netbirdio/netbird/blob/main/client/internal/dns/server.go): `client/internal/dns/server.go`

### Access features

- [Policy-based SSH](https://github.com/netbirdio/netbird/blob/main/client/internal/engine_ssh.go): `client/internal/engine_ssh.go`
- [Reverse proxy](https://github.com/netbirdio/netbird/blob/main/client/internal/expose/manager.go): `client/internal/expose/manager.go`
- [Port forwarding](https://github.com/netbirdio/netbird/blob/main/client/internal/portforward/manager.go): `client/internal/portforward/manager.go`

### Other components

- **User**
- [Management service](https://github.com/netbirdio/netbird/tree/main/management): `management`
- [Signal service](https://github.com/netbirdio/netbird/tree/main/signal): `signal`
- [Relay service](https://github.com/netbirdio/netbird/tree/main/relay): `relay`

## Connections

- User → CLI commands: runs commands
- User → Platform SDKs: uses app
- CLI commands → Daemon service: controls daemon
- Platform SDKs → Daemon service: controls daemon
- Daemon service → Client engine: hosts engine
- Client engine → Authentication: authenticates
- Authentication → Management service: requests identity
- Client engine → Management service: syncs configuration
- Client engine → Profile management: manages profiles
- Profile management → Local state: persists settings
- Client engine → Local state: stores state
- Client engine → Access policies: applies policy
- Access policies → Host firewall: installs rules
- Client engine → Route manager: configures routes
- Client engine → Private DNS: configures DNS
- Client engine → WireGuard interface: configures tunnel
- Client engine → Peer negotiation: manages peers
- Peer negotiation → ICE discovery: discovers candidates
- Peer negotiation → Signal service: negotiates peers
- ICE discovery → WireGuard interface: establishes direct path
- Peer negotiation → Relay service: relays fallback traffic
- Client engine → Policy-based SSH: manages SSH
- Client engine → Reverse proxy: manages proxy
- Client engine → Port forwarding: manages forwarding
