Network Configuration¶

Three environments, one detector¶

The health coordinator is the single authority on which one you are in. It probes every 15 seconds; the launcher, the status line and the LLM proxy all read its answer rather than detecting independently.

Check where the system thinks you are¶

curl -s localhost:3034/health/state | jq .network

vpn and corporate mean the same thing¶

The coordinator says vpn, corporate or open. The LLM proxy says corporate or public. vpn and corporate are the same network — comparing the two vocabularies as raw strings is a real and recurring source of restart loops.

When calls fail on the corporate network¶

Routing can look perfect while every off-premises call fails. Check egress, not routing:

curl -s localhost:12435/health | jq '.egress, .networkMode'

A proxy pinned to a network you have since left produces exactly this. Restarting the proxy while on the network you are actually on re-pins it.

How the network is detected¶

Three signals, in priority order, first match wins:

The DNS probe deliberately shells out to dig rather than using Node's resolver. Node caches the system DNS servers at process start, so a coordinator that started on a hotspot and then moved onto the office LAN would keep querying the public resolvers, fail to resolve internal names, and report open indefinitely. Spawning dig reads the current OS configuration every time.

The launcher has its own one-time bootstrap check for the moment before the coordinator is up, also DNS-based — the previous version fetched a corporate URL, which required the proxy to already be configured, which required knowing the network. Once the coordinator is running, everything defers to it.

What each agent does on each network¶

Inside the corporate network the launcher auto-detects proxydetox and sets HTTP_PROXY and HTTPS_PROXY. Outside, it actively clears those variables — a stale proxy setting pointing at a proxy that is not there fails in a way that looks like an API outage.

The two network vocabularies¶

This is worth stating plainly because it has caused real restart loops: the coordinator speaks corporate | vpn | open, and the LLM proxy speaks corporate | public. vpn and corporate are the same network under two names. Any code comparing the two must map them first, and the flip detector must compare against the last settled classification rather than the last raw reading, or a single transitional sample triggers a restart.

The bug this describes is invisible on a public network, where both sides happen to spell it the same way. Diagnose it on the VPN specifically.

Egress can fail while routing is perfect¶

Distinguish two questions that look identical from the outside: where was this call routed, and could the process reach the internet at all. On the corporate network with direct egress, every off-premises provider fails with a bare connection error while the routing decision was entirely correct.

curl -s localhost:12435/health | jq '.egress, .networkMode'

The tell is one on-premises provider succeeding while everything else fails. Fallback depth does not help — every hop in a chain shares the same egress pin, so a stale pin fails all of them identically.

Diagnosing¶

curl -s localhost:3034/health/state | jq .network       # what the coordinator sees
curl -s localhost:12435/health | jq '.networkMode'      # what the proxy believes

If those two disagree after mapping vpn to corporate, the proxy is holding a stale reading; kickstarting it while on your current network re-pins it.

How the Coding launcher handles corporate VPN, proxy detection, and agent-specific API routing.

Overview¶

The Coding system operates in three network environments:

• VPN — connected to corporate network via VPN tunnel; proxy (proxydetox on 127.0.0.1:3128) is running and required for external API calls
• Corporate Network (CN) — physically on the corporate network (e.g. office ethernet/Wi-Fi); proxy is running and required for external API calls
• Home / Public Network — direct internet access, no proxy needed

The health coordinator is the single source of truth for network state. It probes every 15 seconds and exposes the result via GET /health/state → network. The launcher, status line, and LLM proxy all consume this endpoint — there is no independent detection elsewhere.

Connectivity Matrix¶

Detection Flow¶

Unified Detection (Health Coordinator)¶

The coordinator (scripts/health-coordinator.js) is the single authority for network location. It probes every 15 seconds using three independent signals — evaluated in order, first match wins:

Launcher Bootstrap (detect-network.sh)¶

The startup script runs a one-time DNS-based check before the coordinator is available:

# DNS-based — works without proxy (no chicken-and-egg)
dig +short muc.proxy-pac.bmwgroup.net +timeout=2
dig +short cc-github.bmwgroup.net +timeout=2

If either resolves to a corporate IP → INSIDE_CN=true. This replaced the previous curl https://cc-github.bmwgroup.net approach, which required the proxy to already be configured (circular dependency on CN).

Once the coordinator is running, the launcher defers to GET http://localhost:3034/health/state for all subsequent network state.

Startup Sequence¶

Proxy Management¶

The px Toggle¶

The px shell alias is the only way to toggle the proxy. It performs three actions atomically:

1. Toggles the proxydetox daemon via launchctl unload/launchctl load of the plist — this truly stops/starts the daemon and closes/opens port 3128 (previous implementations used launchctl stop which was ineffective due to launchd socket activation respawning the process immediately)
2. Invalidates status line caches — deletes all per-pane cache files so the next tmux render reflects the new state
3. Notifies the health coordinator — POST /health/refresh triggers an immediate network re-probe (bypasses the 15s poll interval)

px          # Toggle: if proxy running → stop; if stopped → start

Update Propagation After px¶

The status line reflects the new P: state within ≤5 seconds (one tmux refresh cycle):

LLM Proxy Dynamic Routing¶

The LLM proxy (rapid-llm-proxy, port 12435) dynamically adapts to proxy availability without restart:

• On each outbound request, smartFetch() TCP-probes port 3128 (with 5s cache)
• If proxydetox is up → routes via undici.ProxyAgent (corporate proxy)
• If proxydetox is down → routes via native fetch (direct internet)

This means px off on a hotspot (direct internet) works immediately — the LLM proxy stops trying to route through the dead proxy within 5 seconds.

Proxy Auto-Heal¶

When the coordinator judges the LLM proxy unhealthy it can dispatch launchctl kickstart. Three rules constrain that, each added after an incident where the previous behaviour made things worse.

A failed probe is not a failed service¶

probeHttpHealth/probeTcpPort used to map every failure onto stopped, collapsing two facts that are not the same:

lib/network/probe-result-semantics.mjs softens a timed-out probe to unknown rather than stopped. unknown rather than the previous value, because a failed probe must never assert health — and asserting death on no evidence is the same mistake pointed the other way.

Observed twice before it was generalised: on 2026-08-09 the prompt hook reported "service obs_api stopped" about a service that never stopped, and on 2026-08-30 a two-minute host network outage produced llm_cli_proxy stopped, obs_api stopped, db degraded while all three were provably fine. Three simultaneous false negatives from one transient is a property of the probe semantics, not of any one service.

A proxy that cannot parse its config is not one a restart fixes¶

A config file that will not parse aborts proxy boot by design. Restarting it produces an identical failure, so the coordinator distinguishes this cause and does not spend a kickstart on it.

One incident spends one kickstart, not three¶

From the coordinator's own log on 2026-08-31:

07:02:52.046  proxy auto-heal: dispatching restart (consecutive_failures=1, kickstart_count=1)
07:02:52.063  proxy auto-heal: dispatching restart (consecutive_failures=2, kickstart_count=2)
07:02:52.114  proxy strong-probe escalation: dispatching restart  (kickstart_count=3)
07:04:34      proxy auto-heal cooldown engaged — 3 kickstarts in last 300s

One underlying failure, three restarts in 68 ms, and the whole budget spent before the first restart had finished — a genuine fault arriving in the next five minutes would have found no remediation left. At 07:04:33 a kickstart errored outright because the service was still mid-restart.

Two distinct faults produced that, and a debounce alone fixes only one:

1. The cheap-probe FSM counted invocations, not probe outcomes. It is called from three places, one of them every tick from /health/refresh. Every call while semantic_ok was false incremented the counter and, past the 60 s sustained gate, dispatched — two of the three restarts above are one FSM firing twice, 17 ms apart, off a single probe result. isFreshProbeOutcome() supplies the missing edge detection, keyed on last_probe_end: a caller arriving with the same stamp as last time is re-reading one conclusion, not observing a second failure.
2. Five independent paths could each dispatch without knowing another just had (cheap FSM, strong-probe escalation, passthrough frozen-502, networkMode flip, location mismatch). They shared a count cap and no time gate, so "3 in 5 minutes" was satisfiable in 68 ms. decideKickstart() is the shared gate.

lib/network/kickstart-gate.mjs holds both, as pure functions:

A restart takes 3–8 s to come back and a probe cycle to prove anything, so a second dispatch inside that window cannot be acting on evidence about the new process — it is responding to the old one, or to the gap the restart itself created.

Both modules are pure (every input an argument; no env, no I/O, no clock) and live outside health-coordinator.js, which binds ports on import and therefore cannot be imported by a test. Covered by tests/network/kickstart-gate.test.mjs, which replays the 2026-08-31 cascade, and tests/network/probe-result-semantics.test.mjs.

Inside VPN / Corporate Network¶

The corporate proxy (proxydetox) runs on 127.0.0.1:3128. The launcher:

1. Checks if HTTP_PROXY is already set in the environment
2. If not, probes 127.0.0.1:3128 and auto-configures:

export HTTP_PROXY="http://127.0.0.1:3128"
export HTTPS_PROXY="http://127.0.0.1:3128"
export NO_PROXY="localhost,127.0.0.1,.bmwgroup.net"

All external API calls (Anthropic, GitHub, OpenAI) require this proxy when inside VPN/CN. Direct connections time out.

Outside VPN (Public Network)¶

The launcher clears any proxy env vars inherited from shell profiles:

unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy

This prevents opencode/claude from trying to route through a non-existent proxy.

Agent API Endpoints¶

Each agent validates its required API endpoint before launch:

If validation fails, the launcher logs a warning but does not block startup (the agent may still work via cached tokens or fallback mechanisms).

Testing & Debugging¶

Dry Run¶

Test network detection without launching an agent:

coding --opencode --dry-run
coding --claude --dry-run

Output includes:

[OpenCode] 🏢 Inside Corporate Network (cc-github.bmwgroup.net reachable)
[OpenCode] Proxy active: http://127.0.0.1:3128/
[OpenCode] ✅ External access working (via proxy)
[OpenCode] DRY-RUN: Network: CN=true, Proxy=true, Required=true
[OpenCode] 🏢 VPN → GitHub Copilot Enterprise (claude-opus-4.6)
[OpenCode] ✅ GitHub API reachable (for Copilot provider)

Force Network Mode¶

Override detection for testing:

# Simulate outside VPN
CODING_FORCE_CN=false coding --opencode --dry-run

# Simulate inside VPN
CODING_FORCE_CN=true coding --opencode --dry-run

Troubleshooting¶

Environment Variables¶

Health Coordinator Network State¶

The coordinator exposes live network state at GET http://localhost:3034/health/state → network:

{
  "network": {
    "internet_reachable": true,
    "proxy_running": true,
    "proxy_functional": true,
    "proxy_port_listening": true,
    "location": "vpn",
    "last_check": "2026-05-29T07:48:52.982Z",
    "last_probe_end": "2026-05-29T07:48:52.980Z"
  }
}

The POST /health/refresh endpoint triggers an immediate network re-probe (resets the rate-limiter so the probe runs on the next tick, regardless of the 15s interval).

The dashboard's LLM Proxy Health card and the statusline's [N:xx] / [P:xx] badges both consume this state. N reflects location; P reflects proxy_port_listening (binary ON/OFF — there is no ERR state).