#14564: fix(gateway): crashes on startup when tailscale meets non-loopback bind (#14542)
gateway
stale
size: S
Cluster:
Gateway and macOS Improvements
#### Summary
When `gateway.tailscale.mode` is `serve` or `funnel` and `gateway.bind` is set to something other than `loopback` (e.g. `lan`), the gateway crashes on startup with "tailscale serve/funnel requires gateway bind=loopback (127.0.0.1)". This is easy to hit when migrating servers since the config may carry over with `bind: lan` while tailscale mode gets set separately.
The onboarding wizard and `configure gateway` command already auto-correct bind to loopback in this situation, but the gateway daemon startup didn't — it just threw. Now it matches the wizard behavior and silently corrects to loopback instead of crashing.
Closes #14542
lobster-biscuit
#### Repro Steps
1. Set `gateway.bind: lan` and `gateway.tailscale.mode: serve` in config
2. Start the gateway
3. Gateway crashes with "tailscale serve/funnel requires gateway bind=loopback"
#### Root Cause
`resolveGatewayRuntimeConfig` in `server-runtime-config.ts` threw an error when tailscale was active and bind wasn't loopback. The wizard (`configure.gateway.ts`, `onboarding.gateway-config.ts`) already had the auto-correct logic but the daemon startup path didn't.
#### Behavior Changes
- Before: gateway crashes on startup if `tailscale.mode != off` and `bind != loopback`
- After: gateway auto-corrects bind to `127.0.0.1` and starts normally
#### Tests
- [x] `server-runtime-config.test.ts`: 4 tests covering serve/funnel auto-correct, off mode passthrough, and already-loopback no-op
- [x] `pnpm build` ✅
- [x] `pnpm check` ✅
- [x] `pnpm vitest run src/gateway/` ✅ (45 test files, 271 tests passing)
**Sign-Off**
- Models used: N/A
- Submitter effort: found the mismatch between wizard and daemon startup paths, added the same auto-correct logic to `resolveGatewayRuntimeConfig`, wrote tests covering all tailscale mode combinations
- Agent notes: N/A
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR updates `resolveGatewayRuntimeConfig` to auto-correct `bindHost` to loopback (`127.0.0.1`) when Tailscale mode is `serve` or `funnel`, matching the behavior already present in the onboarding/configure flows. It also adds a focused Vitest suite covering serve/funnel auto-correction, off-mode passthrough, and the no-op case when bind is already loopback.
The change is localized to the gateway runtime config resolution path; it replaces a startup-time hard error with a deterministic bind override for Tailscale serve/funnel, while preserving existing auth validation (including the funnel→password requirement) and the existing “no-auth on non-loopback bind” safety check.
<h3>Confidence Score: 4/5</h3>
- This PR is safe to merge with minimal risk.
- The functional change is small and well-scoped: it only changes one conditional from throwing to forcing loopback when Tailscale serve/funnel is active, and added tests cover the intended behavior matrix. No other logic paths appear affected. I could not execute the test suite in this environment due to missing Node/pnpm, so confidence is slightly reduced despite the included tests.
- src/gateway/server-runtime-config.ts (bind override behavior); src/gateway/server-runtime-config.test.ts (new mocks/test coverage)
<!-- greptile_other_comments_section -->
<sub>(4/5) You can add custom instructions or style guidelines for the agent [here](https://app.greptile.com/review/github)!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#11455: fix(gateway): default gateway.mode to local when unset
by AnonO6 · 2026-02-07
84.1%
#19437: Gateway: respect custom bind host for local health/RPC target resol...
by frudas24 · 2026-02-17
82.6%
#16300: fix(tui): respect gateway bind mode in TUI connection
by cortexuvula · 2026-02-14
82.5%
#22056: fix(gateway): use loopback for self-connections regardless of bind ...
by usedhonda · 2026-02-20
82.3%
#22110: fix(tools): prefer loopback for internal tool-to-gateway RPC calls
by pierreeurope · 2026-02-20
81.7%
#19026: fix(gateway): use loopback for local CLI-to-gateway connections
by Phineas1500 · 2026-02-17
81.7%
#19937: fix(gateway): validate token/password auth modes and isolate gatewa...
by NewdlDewdl · 2026-02-18
80.7%
#4653: fix(gateway): improve crash resilience for mDNS and network errors
by AyedAlmudarra · 2026-01-30
79.6%
#21256: fix: treat ws:// to Tailscale addresses as secure when bind=tailnet
by jessewunderlich · 2026-02-19
79.2%
#21772: [Bug]: Allow ws:// to Tailscale CGNAT addresses
by AIflow-Labs · 2026-02-20
79.2%