boma/docs/runbooks/netbird-client.md

Runbook — Enrolling a NetBird client (road-warrior device)

Joins a client/road-warrior device (laptop, desktop, phone) to the boma NetBird mesh so it can reach ubongo and other peers from anywhere. The self-hosted coordinator is on askari (ADR-016, M4b); enrollment lands a device on the 100.64.0.0/10 overlay.

Hosts vs clients. Managed Linux hosts join via the base role's mesh concern (base__mesh_enabled: true + the reusable key in vault.netbird.setup_key) — see ADR-016 / the base README, not this runbook. This runbook is for user devices NetBird doesn't manage with Ansible.

verified: NetBird client install + self-hosted --management-url flow · docs.netbird.io (/get-started/install/windows, /get-started/cli) · 2026-06-17

Prerequisites

• The coordinator's first-boot /setup admin exists and you can log in at https://netbird.askari.wingu.me.
• Auth, pick one:
  • SSO (recommended for a personal device) — your dashboard account; no secret to copy.
  • Setup key — dashboard → Settings → Setup Keys → a reusable key (mint a client-specific one for clean ACL grouping, or reuse the existing reusable key).
• Local admin rights on the device (the client installs a service).
• Coordinator facts: management URL https://netbird.askari.wingu.me; ubongo = 100.99.146.14 (ubongo.netbird.selfhosted); askari = 100.99.226.39.

---

Part A — Windows 11

1. Install: download + run the MSI https://pkgs.netbird.io/windows/msi/x64 (official x64 client; installs the tray app + the netbird service).
2. Connect from an elevated Windows Terminal / PowerShell ("Run as administrator"):

   netbird up --management-url https://netbird.askari.wingu.me
   

   A browser opens — sign in with your dashboard account. (SSO won't open a browser? use a key: netbird up --setup-key <KEY> --management-url https://netbird.askari.wingu.me.)
3. Proceed to Part C (verify).

---

Part B — Other platforms (same management URL)

• macOS / Linux desktop: install the client (macOS: NetBird app / Homebrew; Linux: pkgs.netbird.io per the distro — same apt/rpm flow as base's mesh concern), then netbird up --management-url https://netbird.askari.wingu.me (Linux: prefix sudo).
• Android / iOS: install the NetBird app, then in Settings → Advanced / Server set the management server to https://netbird.askari.wingu.me before logging in; connect and complete the SSO login. (Setup keys are supported in-app too.)

---

Part C — Verify + use

netbird status        # expect: Management: Connected, Signal: Connected, a 100.x NetBird IP
netbird status -d     # peer detail — ubongo (100.99.146.14) + askari (100.99.226.39) listed

Reach ubongo over the mesh:

ssh sjat@100.99.146.14        # or: ssh sjat@ubongo.netbird.selfhosted

SSH auth is separate from the mesh: ubongo is key-only (passwords disabled), so the device needs an SSH key authorised for sjat@ubongo. The mesh provides the network path; the SSH key provides auth.

---

Notes

• Split-tunnel: NetBird routes only the 100.x overlay by default — normal/work networking is unaffected.
• Persistence: the service auto-starts on boot and reconnects; the tray app has Connect/Disconnect; CLI netbird down / netbird up (no flags after first setup).
• Troubleshooting — "failed while getting Management Service public key" / won't register: confirm https://netbird.askari.wingu.me loads in a browser from the device (DNS + TLS + the gRPC routing through Caddy are reachable), the URL is exact, and the terminal is elevated. If a peer shows Disconnected, NAT traversal is falling back to the relay (over 443) — usually transient.
• Removing a device: netbird down then uninstall; revoke its peer in the dashboard (and the setup key if one-off).