Network Configuration¶

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.

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).