Status: LIVE — deployed 2026-07-15, §7 acceptance gate passed 2026-07-17
Repo: gitlab.homelab.vyanh.uk/andy/netbird-cloud-homelab (scripts, runbooks, test records)
Supersedes: VPN Decision — Headscale vs MikroTik WireGuard for day-to-day remote access. MikroTik WireGuard is retained as break-glass only.
homelab.vyanh.uk resolves via Technitium (192.168.88.11) through the tunnel; everything else uses the client's normal DNS.vpn.vyanh.uk:13231) stays configured on admin devices, verified working end-to-end 2026-07-16.Peer-to-peer WireGuard is attempted first; on CGNAT mobile data connections fall back to NetBird's relay (observed: sin1 Singapore relay, ~88 ms — fine for admin work).
nb-router-home-01| Item | Value |
|---|---|
| Host | pve2 (only node with ≥20% RAM headroom at deploy time) |
| VM | 110, Ubuntu 24.04, 1 vCPU / 1 GiB / 16 G local-zfs, cloned from template 9000 |
| LAN IP | 192.168.88.40 (static block .31–.49) |
| NetBird IP | 100.66.10.233 (nb-router-home-01.netbird.cloud) |
| Hardening | UFW SSH-from-LAN-only, andy user with clawdbot ed25519 key |
| Backup | vzdump backup-netbird-peer Sat 04:30 → synology-backup (rebuild-from-code preferred over restore) |
| Monitoring | vmagent scrapes .40:9100; vmalert NetBirdRoutingPeerDown (5m, critical); Uptime Kuma monitor 73 (ping) |
Configured via the NetBird REST API (api.netbird.io, PAT auth Authorization: Token nbp_…). The setup PAT claude-setup was deleted after completion — create a fresh short-lived PAT for any future API change.
Peer groups: peer-admin-clients (anh-macbook, anh-iphone) · peer-family-clients (empty, pending) · peer-routing-home (nb-router-home-01)
Network Home LAN (router = peer-routing-home, masquerade ON, metric 9999) with resources:
| Resource | Address | Group |
|---|---|---|
| Home LAN admin | 192.168.88.0/24 |
resource-home-lan-admin |
| Internal DNS | 192.168.88.11/32 |
resource-internal-dns |
| Immich | immich.homelab.vyanh.uk (domain) |
resource-family-services |
Policies (Default all-to-all DISABLED — id d9b6q02fadhs738jvuj0):
| Policy | Source → Destination | Protocol/Ports |
|---|---|---|
| Administrators to Home LAN | admin → home-lan-admin | all |
| Administrators to Routing Peer — SSH | admin → peer-routing-home | TCP 22 |
| Administrators to Routing Peer — ICMP | admin → peer-routing-home | ICMP |
| Clients to Internal DNS — UDP / TCP | admin + family → internal-dns | UDP 53 / TCP 53 |
| Family to Approved Applications | family → family-services | TCP 443 |
Nameserver group technitium-homelab: match domain homelab.vyanh.uk → 192.168.88.11:53 UDP, not primary, distributed to admin + family groups. Only homelab lookups traverse the tunnel; public DNS stays on the client's own resolver (no exit-node behavior, verified: public IP on mobile data = carrier IP).
macOS detail: the client installs a scoped resolver via a local stub (100.66.255.254). Plain dig name does not use scoped resolvers — test with dscacheutil -q host -a name immich.homelab.vyanh.uk or dig @192.168.88.11.
brew install --cask netbird-ui / pkgs.netbird.io) → SSO login.peer-family-clients only.Full run order in repo docs/mobile-test-session.md; executed from mobile data 2026-07-16/17:
| Test | Result |
|---|---|
| Admin access (ping .1/.19, Proxmox UI, SSH .40) | ✅ |
| No exit-node leak (public IP = carrier) | ✅ |
| Split DNS (immich → 192.168.88.12 internally) | ✅ (initial "failure" was a macOS test artifact — see repo doc) |
| WireGuard break-glass end-to-end | ✅ |
| Post-Default-disable re-test on scoped policies | ✅ |
Pending: family device onboarding + negative test (approved 443 apps reachable; admin UIs, SSH, and arbitrary LAN hosts blocked).
Default policy (dashboard toggle or API PUT /api/policies/d9b6q02fadhs738jvuj0 with enabled: true). WireGuard break-glass is independent of NetBird entirely.null (not []) when empty; PUT /policies/{id} needs the full body with rule sources/destinations flattened to group-ID arrays; group IDs look alike — always match groups by name, not by remembered ID.make capacity in the repo (pve1 and pve3 lacked RAM headroom at deploy time).apt upgrade netbird (installed 0.74.x).WireGuard (wireguard1, 192.168.100.0/24, UDP 13231) is unchanged and kept as the out-of-band emergency path — it depends only on the router, not on the NetBird cloud, the routing peer VM, or Proxmox. Keep the WG profile installed on admin devices. NordVPN Meshnet on VM100 remains a second out-of-band path.