openZro

Open-source zero-trust mesh networking — BSD-3, no AGPL strings, no artificial limits.

openZro is a WireGuard®-based zero-trust overlay network: every machine you put on it gets a flat, encrypted private LAN with SSO, MFA, posture checks, and granular access policies — no port-forwarding, no VPN gateways, no per-device manual config.

It is a fork of netbirdio/netbird@v0.52.2 (the last BSD-3 release before the upstream relicensed three core components to AGPLv3 in August 2025), continued under BSD-3-Clause for self-hosted deployments that want a freely-licensed, fully-featured baseline.

In production today. openZro is already running real production deployments — full control plane (management + signal + relay + dashboard) on Kubernetes, with peers signing in through Dex and the operator surface exercised daily.

Still being built. The codebase moves fast. Feature work and the near-term plan live in docs/ROADMAP.md and the open issues; chart values and config formats may shift between releases until the project stabilizes.

Documentation is catching up. A few pages still mirror the upstream NetBird wording verbatim and are being refreshed as the docs parity audit closes. Where the docs and the code disagree, the code is authoritative.

Try it and tell us what breaks. Open an issue or a discussion — every report from a real deployment helps shape what ships next.

The full reasoning is captured in ADR-0001.

┌──────────────┐         ┌─────────────────┐
│   client     │◄────────│ signal-server   │  WebRTC ICE candidate exchange
│ (WireGuard)  │         │ (HA-capable)    │
└──────┬───────┘         └─────────────────┘
       │
       ▼
┌──────────────┐         ┌─────────────────┐         ┌────────────────┐
│   client     │◄────────│ management      │◄───────►│ Postgres/MySQL │
│ (WireGuard)  │  gRPC   │ (HA-capable)    │   DB    │ (state of      │
└──────────────┘  Sync   └────────┬────────┘         │  truth)        │
                                  │                  └────────────────┘
                                  │ pub/sub + locks
                                  ▼
                          ┌───────────────┐
                          │ Valkey / NATS │  (only required for HA)
                          └───────────────┘

Activate by setting one of:

OPENZRO_REDIS_URL=valkey://broker:6379/0     # Valkey/Redis/Dragonfly
OPENZRO_NATS_URL=nats://broker:4222          # external NATS
OPENZRO_BROKER=embedded                      # embedded NATS
OPENZRO_CLUSTER_PEERS=nats://node2:6222,nats://node3:6222

The same broker selection drives both signal HA and management HA — one piece of stateful infra, two components served. See ADR-0001 §3.4.

openzro/
├── CLAUDE.md             Brand & engineering rules (read by Claude Code)
├── design-tokens.md      Colors / typography reference
├── brand/                Official brand assets (icon, etc.)
├── client/               WireGuard agent
├── management/           Control plane (gRPC + HTTP API)
├── signal/               WebRTC signaling
├── relay/                TURN-style relay
├── cluster/              Distributed coordinator (HA primitives)
├── dashboard/            Next.js web UI (with its own CLAUDE.md)
├── deploy/               Local docker-compose for dev/HA testing
└── docs/
    ├── FORK.md           Fork-point provenance
    ├── adr/              Architecture Decision Records
    └── security/         Security advisories tracking

Linux — distro-detecting one-liner (covers Debian/Ubuntu/RHEL/Fedora/SUSE via signed apt/yum/zypper repos, falls through to pacman/AUR for Arch/CachyOS, binary tarball otherwise):

curl -fsSL https://pkg.openzro.io/install.sh | sh

Manual repo setup (apt example):

curl -sSL https://pkg.openzro.io/openzro-archive-key.asc | \
  sudo gpg --dearmor -o /usr/share/keyrings/openzro-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/openzro-archive-keyring.gpg] \
  https://pkg.openzro.io/apt stable main' | \
  sudo tee /etc/apt/sources.list.d/openzro.list
sudo apt-get update && sudo apt-get install openzro

Windows — .msi installer + .zip for portable use:

• Installer: openzro_<version>_windows_amd64.msi
• Tray UI: extract openzro-ui_<version>_windows_amd64.zip, run openzro-ui.exe as administrator

The MSI is currently unsigned (Windows shows a SmartScreen warning on first run; click More info → Run anyway). EV signing via SignPath Foundation is tracked as issue #1.

macOS — universal .pkg installer or Homebrew tap:

# Homebrew (CLI)
brew install openzro/tap/openzro
sudo brew services start openzro

# Or .pkg installer from GH Releases
# https://github.com/openzro/openzro/releases/latest →
#   openzro_<version>_darwin_universal.pkg

The .pkg is unsigned; first run may need xattr -d com.apple.quarantine or right-click → Open. Apple Developer ID notarization is tracked as issue #2.

helm repo add openzro https://openzro.github.io/helms
helm repo update

# Control plane (management + signal + relay + dashboard + Dex)
helm install openzro openzro/openzro \
  --create-namespace -n openzro \
  -f my-values.yaml

# Optional: K8s operator (CRDs that reconcile peers/groups/policies)
helm install openzro-operator openzro/openzro-operator -n openzro

See docs/operator/k8s-deployment-guide.md for the full walk-through (values overrides, Gateway API instead of Ingress, operator Personal Access Token wiring, troubleshooting).

infrastructure_files/configure.sh generates the docker-compose stack (management + signal + relay + dashboard + Dex + mTLS PKI). See ADR-0006 for the IdP architecture.

# 1. Bring up Postgres + Valkey + NATS locally
make dev.deps.up

# 2. Build the Go core
make build

# 3. Run tests
make test

Single-instance dev:

export OPENZRO_STORE_ENGINE=postgres
export OPENZRO_STORE_ENGINE_POSTGRES_DSN=postgres://openzro:openzro@localhost:5432/openzro?sslmode=disable
./management/management management --datadir=/tmp/openzro

HA dev (one of):

# Valkey
export OPENZRO_REDIS_URL=valkey://localhost:6379/0

# external NATS
export OPENZRO_NATS_URL=nats://localhost:4222

# embedded NATS (no broker container needed)
export OPENZRO_BROKER=embedded
export OPENZRO_CLUSTER_PEERS=nats://localhost:6222

make help lists every available target.

Sibling repos:

1. No CLA. openZro accepts contributions under the inbound-equals-outbound BSD-3 rule. By submitting a PR you agree it will be released as BSD-3.
2. No AGPL ingestion ever. Do not paste, mirror, or translate code from netbirdio/netbird post-v0.53.0 (the AGPLv3 cut). Reimplementation from public CVE/CWE/protocol descriptions is fine and is how we backport security fixes — see the existing examples in docs/security/advisories.md.
3. TDD is the default. New code lands with tests written first. See CLAUDE.md §Engineering rules.

openZro inherits and credits prior work from netbirdio/netbird through v0.52.2 (BSD-3-Clause). The upstream LICENSE and AUTHORS files are preserved verbatim under the BSD-3 attribution clause. New contributors to openZro itself are added to AUTHORS separately.

WireGuard® and the WireGuard logo are registered trademarks of Jason A. Donenfeld.

BSD 3-Clause — forever, in every directory.