AnonBird is a NetBird fork focused on anonymous private mesh networking over Tor and I2P.
Start with the leak map, I2P operations guide, and release hardening notes.

AnonBird keeps the familiar WireGuard mesh, management, signal, relay, ACL and dashboard model, but adds anonymous transports and hardens the fork so anonymous deployments do not silently call upstream package, metrics, update, debug-upload, geolocation or cloud endpoints.

Tor mode. tor-relay-only forces management, signal and relay traffic through a SOCKS5 Tor path, disables STUN/ICE/direct UDP, and uses userspace WireGuard over relay streams.

I2P mode. i2p-datagram uses I2P SAM for control and peer data transport, exchanges public I2P destinations through management, and keeps private destination keys local to the client profile.

AnonBird UX. The CLI command is anonbird, the dashboard uses anonymous-aware install flows, and release packages install into AnonBird paths such as /etc/anonbird, /var/lib/anonbird, /var/log/anonbird and /var/run/anonbird.

Brand assets. Current raster assets are checked in for the README, proxy web, dashboard, favicon and desktop UI. Visual identity can be replaced without changing the anonymous transport design.

Key features

Anonymous transport	Management	Security	Operations	Platforms
✓ Tor SOCKS5 control plane	✓ Anonymous-aware dashboard	✓ STUN/ICE/direct UDP kill-switch	✓ Fork release images and packages	✓ Linux
✓ Tor relay data plane	✓ Setup-key bootstrap	✓ IP/location/serial redaction	✓ Self-host scripts	✓ macOS
✓ Tor stream multipath	✓ Internal DNS and ACLs	✓ Debug/upload/geolite fail-closed defaults	✓ Systemd units	✓ Windows
✓ I2P SAM STREAM control plane	✓ Device approval support	✓ Anonymous update checks disabled by default	✓ Docker/Compose templates	✓ Containers
✓ I2P SAM DATAGRAM peer transport	✓ Setup invite tokens	✓ Runtime anonymous checks	✓ Release hardening audit commands	✓ FreeBSD package helper

One-command self-host quickstart

AnonBird is self-hosted-first. The recommended open-source quickstart starts a single-host deployment with the dashboard, embedded IdP, management, signal and relay combined server, and Traefik TLS routing.

• A Linux VM with at least 1 CPU and 2 GB of memory.
• Docker with the Compose plugin.
• A DNS name pointing to the VM.
• Open inbound 80/tcp and 443/tcp.
• Clients can start from a clean OS install. In anonymous mode AnonBird first uses an already-running local Tor SOCKS5 or I2P SAM bridge if present, then tries to install tor/i2pd with the local package manager and start a managed local runtime when needed.

Recommended DNS records:

Type	Name	Content	Cloudflare proxy status
A	anonbird	YOUR.SERVER.IP.ADDRESS	DNS only
AAAA	anonbird	YOUR.SERVER.IPV6.ADDRESS	DNS only, optional
CNAME	*.anonbird	anonbird.example.com	DNS only, only when AnonBird Proxy wildcard services are enabled

For a standard management/dashboard deployment, the single A record is enough. Do not enable Cloudflare proxying for the AnonBird domain: use DNS only so Let's Encrypt, gRPC and WebSocket relay paths can work directly. Open 80/tcp and 443/tcp; keep 3478/udp closed unless you explicitly enable legacy clearnet STUN, and open 51820/udp only when using AnonBird Proxy.

curl -fsSL https://github.com/Cr0me1ve/anonbird/releases/latest/download/getting-started.sh | bash

The script asks for the domain, anonymous peer management transport, reverse proxy mode, Let's Encrypt email and optional AnonBird Proxy settings. It creates /opt/anonbird, renders docker-compose.yml, dashboard.env and config.yaml there, starts a managed Tor onion service by default, writes the generated endpoint back to the dashboard/server environment, and starts the stack from that directory. When it finishes, open:

https://anonbird.your-domain.com

The one-command installer uses the built-in Traefik mode by default and checks that the required AnonBird Docker images are available before it starts the stack. Anonymous-safe server defaults are used: management version checks, geolocation downloads, anonymous metrics and STUN/UDP are disabled unless you explicitly opt in.

Use --anonymous-transport i2p to create a managed I2P .b32.i2p server tunnel instead of Tor, or --anonymous-transport both to create both sidecars and keep Tor as the default copied peer endpoint. The generated endpoints are saved in /opt/anonbird/anonymous-endpoints.env. Use --peer-management-endpoint http://...onion only when you already operate an external Tor/I2P service yourself.

After startup, check the deployment from the server:

cd /opt/anonbird
docker compose ps
curl -fsS https://anonbird.your-domain.com/oauth2/.well-known/openid-configuration >/dev/null
curl -ksS -o /dev/null -w '%{http_code}\n' https://anonbird.your-domain.com/api/users

The unauthenticated API check should return 401.

For unattended installs, pass the same values as flags:

curl -fsSL https://github.com/Cr0me1ve/anonbird/releases/latest/download/getting-started.sh \
  | bash -s -- --domain anonbird.your-domain.com --email admin@your-domain.com \
      --yes

To bootstrap an unattended setup key for anonymous clients:

cd /opt/anonbird
docker compose exec -T anonbird-server \
  /go/bin/anonbird-server setup-key bootstrap --config /etc/anonbird/config.yaml

Save the printed setup key once. Then enroll clients with the dashboard command or a join URL that points at your onion/I2P management address.

For a dry configuration render without starting containers:

curl -fsSL https://github.com/Cr0me1ve/anonbird/releases/latest/download/getting-started.sh \
  | bash -s -- --domain anonbird.your-domain.com --email admin@your-domain.com --yes --render-only

The rendered files are written to /opt/anonbird.

To check release image availability without writing files or starting containers:

curl -fsSL https://github.com/Cr0me1ve/anonbird/releases/latest/download/getting-started.sh \
  | bash -s -- --domain anonbird.your-domain.com --email admin@your-domain.com --yes --preflight-only

Release-candidate and private registry tests can override images without editing the script:

export ANONBIRD_DASHBOARD_IMAGE=registry.example.com/anonbird-dashboard:rc
export ANONBIRD_SERVER_IMAGE=registry.example.com/anonbird-server:rc
export ANONBIRD_PROXY_IMAGE=registry.example.com/anonbird-reverse-proxy:rc

curl -fsSL https://github.com/Cr0me1ve/anonbird/releases/latest/download/getting-started.sh \
  | bash -s -- --domain anonbird.your-domain.com --email admin@your-domain.com --yes

The NETBIRD_* environment names are still accepted in deployment scripts for compatibility with the inherited configuration contract. New generated artifacts use AnonBird images, commands and filesystem paths.

If you deliberately need legacy clearnet/STUN behavior for a compatibility test, make that choice explicit:

curl -fsSL https://github.com/Cr0me1ve/anonbird/releases/latest/download/getting-started.sh \
  | bash -s -- --domain anonbird.your-domain.com --email admin@your-domain.com --yes --enable-clearnet-stun

Do not use that mode for anonymous clients unless you have accepted the real-IP exposure risk.

Linux client install

The release installer places the anonbird command in PATH, installs anonbird.service, and uses /etc/anonbird, /var/lib/anonbird, /var/log/anonbird and /var/run/anonbird.sock.

curl -fsSL https://github.com/Cr0me1ve/anonbird/releases/latest/download/install.sh \
  | sudo bash -s --

After a fresh install the daemon can be active while still waiting for enrollment:

sudo systemctl status anonbird
anonbird status
anonbird debug anonymous-check

Before enrollment, anonymous-check should report pending enrollment, Default connection policy: anonymous tor-relay-only, and Result: OK. After enrollment it should report the actual Tor or I2P management/signal/relay transports.

For migration dry-runs where old scripts still call netbird, add a temporary compatibility symlink without making it the canonical command:

curl -fsSL https://github.com/Cr0me1ve/anonbird/releases/latest/download/install.sh \
  | sudo bash -s -- --compat-symlink --no-start

Dashboard and anonymous peer URLs

The admin dashboard can be exposed on clearnet, a private network, or an onion service. Anonymous peer privacy depends on the management/signal/relay URL used by clients, not on where the administrator opens the dashboard.

Common split deployment:

Admin browser:
  https://admin.example.com

AnonBird peers:
  http://managementxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.onion

The one-command installer writes this split automatically after creating the managed Tor/I2P sidecar. For manual deployments, set the dashboard runtime configuration so browser API calls use the admin API origin, while generated peer setup commands use the onion/I2P management origin:

NETBIRD_MGMT_API_ENDPOINT=https://admin.example.com
NETBIRD_MGMT_GRPC_API_ENDPOINT=https://admin.example.com
ANONBIRD_PEER_MANAGEMENT_ENDPOINT=http://managementxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.onion

With that split, the administrator's browser and dashboard API can use clearnet, while copied peer setup commands still join through Tor/I2P and do not publish real endpoint candidates.

After setup, the endpoint can also be changed in Settings → Anonymous Network. Changing it affects future install commands and can require rejoining peers that were configured with the old address.

Anonymous Client Examples

The dashboard-generated anonbird://join?... link is the recommended client UX. It sets anonymous mode, management URL, setup key and transport in one step:

anonbird join "anonbird://join?server=http%3A%2F%2Fexamplehiddenservice.onion&setup_key=NB-SETUP-xxxx&transport=tor-relay-only"

On a clean Linux/macOS/FreeBSD system, AnonBird checks the local loopback proxy first. If Tor or i2pd is missing, it attempts to install the package with a supported package manager (apt-get, dnf, yum, zypper, apk, pacman, brew or pkg) and then starts a managed local runtime before dialing management. Anonymous management URLs still fail fast unless they are .onion or .b32.i2p, so a pasted clearnet URL will not be used accidentally.

Tor relay-only:

anonbird up \
  --management-url http://examplehiddenservice.onion \
  --setup-key "$SETUP_KEY" \
  --anonymous-transport tor-relay-only \
  --tor-socks5 127.0.0.1:9050

I2P datagram:

anonbird up \
  --management-url http://example.b32.i2p \
  --setup-key "$SETUP_KEY" \
  --anonymous-transport i2p-datagram \
  --i2p-sam 127.0.0.1:7656

For Tor, --tor-socks5 must point to loopback, for example 127.0.0.1:9050. Remote SOCKS5 proxies are rejected in anonymous mode to avoid clearnet proxy leaks. For I2P, --i2p-daemon-mode auto is the default: AnonBird uses an existing SAM bridge when available, otherwise it installs/starts managed i2pd. Use --i2p-daemon-mode external only when you deliberately manage i2pd.service yourself.

Anonymous mode is enabled by default for new CLI connections. Non-anonymous clearnet mode is intentionally hard to invoke: it prints a real-IP leak warning and requires an explicit override.

anonbird up \
  --no-anonymous-mode \
  --allow-unsafe-clearnet \
  --yes-i-understand-this-may-leak-my-ip

Run the local safety audit any time:

anonbird debug anonymous-check

Expected anonymous output includes:

Anonymous mode: enabled
STUN: disabled
ICE: disabled
Direct UDP: disabled
Clearnet fallback: disabled
Published endpoints: none
Result: OK

Migration From NetBird

Migration defaults to dry-run mode and prints the exact file/service actions before changing anything.

Client migration:

anonbird migrate client --dry-run
sudo anonbird migrate client --apply --rejoin "anonbird://join?server=http%3A%2F%2Fexample.onion&setup_key=..."

If a legacy NetBird config contains a non-anonymous management URL, apply mode refuses to start AnonBird unless you provide --rejoin or explicitly accept an unsafe clearnet migration:

sudo anonbird migrate client --apply \
  --allow-unsafe-clearnet \
  --yes-i-understand-this-may-leak-my-ip

With --rejoin, migrated config files are rewritten to anonymous mode before the service starts, so the old clearnet profile does not connect during migration. After a successful anonymous join, auto-connect is enabled again so future service restarts reconnect through the anonymous transport.

Self-hosted server migration uses the packaged AnonBird migration script for the legacy Docker Compose stack:

anonbird migrate server --install-dir /opt/netbird --dry-run
sudo anonbird migrate server --install-dir /opt/netbird --apply --yes

Rollback for client filesystem migration:

sudo anonbird migrate rollback --backup-dir /var/backups/anonbird/migration-YYYYMMDD-HHMMSS --apply

Production-readiness status

The current release line has passed the production-readiness gates tracked in anonbird_netbird_fork_plan.md: one-command self-host, published release artifacts, NetBird migration, anonymous client update/install flows, Tor/I2P remote smoke, Marton overlay traffic, and focused leak sweeps. Review the v0.72.2 release report or the Russian release report for the exact tag, checksums, test matrix, known limitations and verdict.

The release gate covers:

• one-command server/dashboard install from published images;
• Linux package install, upgrade, uninstall/reinstall and rollback from release artifacts;
• migration from ordinary self-hosted NetBird for the server and at least two clients;
• Tor and I2P remote smoke tests on the fixed release testbed;
• a real application test over the overlay, currently Marton master+edge subscription flow;
• focused leak and secret sweeps over logs, git tree and artifacts;
• an explicit verdict on whether a test project can replace NetBird with AnonBird without manual patches.

Internals

• Every machine runs the AnonBird agent, which manages userspace WireGuard in anonymous mode.
• Every agent connects to the Management Service and Signal Service through the configured anonymous transport.
• Tor mode uses relay WebSockets over SOCKS5 and disables direct candidate discovery.
• I2P mode uses SAM STREAM for control and SAM DATAGRAM for direct peer transport when possible.
• The Relay Service remains encrypted transport infrastructure, not a trust anchor.

Acknowledgements

AnonBird builds on the NetBird codebase and open-source technologies like WireGuard®, Pion ICE, I2P SAM, Tor, and Rosenpass.

Legal

This repository is licensed under the BSD-3-Clause license, which applies to all parts of the repository except for the directories management/, signal/ and relay/. Those directories are licensed under the GNU Affero General Public License version 3.0 (AGPLv3). See the respective LICENSE files inside each directory.

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