#9988: feat(gateway): add overlay, zerotier, and wireguard bind modes
docs
app: macos
gateway
cli
commands
stale
Cluster:
Gateway and macOS Improvements
## Summary
- Add three new gateway bind modes: `zerotier`, `wireguard`, and `overlay` (generic auto-detect)
- Extract Tailscale-specific auth code from `auth.ts` into `auth-tailscale.ts` for cleaner boundaries
- New `pickOverlayIPv4()` detection module that identifies overlay network interfaces by name prefix (`zt*`, `wg*`, `nebula*`) or IP range (Tailscale CGNAT)
Four tiers of specificity:
```
--bind tailnet → Tailscale only (existing)
--bind zerotier → ZeroTier only (new)
--bind wireguard → WireGuard only (new)
--bind overlay → auto-detect any (new) — covers Tailscale, ZeroTier, WireGuard, Nebula
```
### New files
- `src/infra/overlay-net.ts` — overlay network detection (`pickOverlayIPv4`)
- `src/infra/overlay-net.test.ts` — 11 tests covering all detection strategies
- `src/gateway/auth-tailscale.ts` — extracted Tailscale auth functions
### Changes across
- Config types + zod schema (new bind modes + `overlayInterface` field)
- Gateway `net.ts` bind host resolution + local address detection
- CLI validation, doctor security, daemon status, onboarding, configure prompts
- macOS Swift `GatewayEndpointStore` (supported modes + host resolution)
- Docs: `gateway.md`, `configuration.md`, `network-model.md`
## Test plan
- [x] `tsc --noEmit` — no new type errors
- [x] `oxlint` — 0 warnings, 0 errors on all changed files
- [x] `oxfmt --check` — all formatted
- [x] `vitest run` — 11 new overlay-net tests pass, 7 auth tests pass, 225 total gateway/infra/config tests pass
🤖 Co-authored with [Claude Code](https://claude.com/claude-code) powered by an enormous lobster-biscuit.
## Existing Functionality Check
I searched the codebase for existing functionality before implementing this.
Most Similar PRs
#21256: fix: treat ws:// to Tailscale addresses as secure when bind=tailnet
by jessewunderlich · 2026-02-19
70.9%
#14564: fix(gateway): crashes on startup when tailscale meets non-loopback ...
by yinghaosang · 2026-02-12
69.8%
#11710: fix: security hardening — exec blocking, auth validation, timing-sa...
by zendizmo · 2026-02-08
69.4%
#23688: fix(gateway): accept raw IP addresses in gateway.bind for backward ...
by arosstale · 2026-02-22
67.8%
#16300: fix(tui): respect gateway bind mode in TUI connection
by cortexuvula · 2026-02-14
67.6%
#19937: fix(gateway): validate token/password auth modes and isolate gatewa...
by NewdlDewdl · 2026-02-18
67.5%
#18441: feat(gateway): add localNetworks config for subnet-scoped auto-pairing
by JayMishra-source · 2026-02-16
67.4%
#23355: Gateway: fail closed on untrusted proxy headers
by bmendonca3 · 2026-02-22
67.3%
#20782: feat(gateway): Cloudflare Tunnel & Access integration
by G4brym · 2026-02-19
67.1%
#11455: fix(gateway): default gateway.mode to local when unset
by AnonO6 · 2026-02-07
66.3%