Troubleshooting

The dashboard shows zero savings

Nine times out of ten, your agent simply isn't routing through the proxy yet. Headroom configures your shell when you connect a client, but terminals that were already open keep their old environment, so the first fix is: close the terminal, open a new one, start a fresh session. To verify routing, run echo $ANTHROPIC_BASE_URL (or $OPENAI_BASE_URL for Codex) in the terminal where your agent runs; it should point at 127.0.0.1:6767.

Two known exceptions: the Claude desktop app's built-in Claude Code pins its own host and can't be routed through any proxy (terminal and VS Code sessions work fine), and a paused Headroom keeps routing but deliberately stops optimizing until you resume it from the menu bar.

First launch seems stuck

On first run Headroom downloads its isolated Python runtime and a local compression model, roughly two gigabytes. On slow connections that takes a while, and the app can look idle while it works. Leave it running; every launch after the first is seconds. If it genuinely never finishes, check that your network allows large downloads (corporate proxies and VPNs are the usual culprits) and relaunch the app.

Learnings stay at zero

Almost never a bug: a pattern must be confirmed five times before Headroom saves it, so the first learnings take a few sessions to appear. The Optimize view shows how many patterns are currently under observation. The full mechanics are in how auto-learning works.

Claude Code's Remote Control option disappeared

Recent Claude Code versions hide /remote-control whenever a custom base URL is set; that's Claude Code's own gate, not a proxy failure. Workaround for a session where you need it: launch with the override unset, e.g. ANTHROPIC_BASE_URL= claude, and that session talks to Anthropic directly while everything else keeps routing through Headroom.

"Port already in use" at startup

Headroom listens on port 6767 (and runs its optimization backend on 6768). If another proxy tool (or a leftover Headroom process from a crashed session) holds the port, startup fails. Find the culprit with lsof -i :6767, quit it, and relaunch Headroom. Two copies of Headroom can't run at once.

Still stuck?

Pausing and resuming from the menu bar resets the routing cleanly, and uninstalling reverts everything if you want a from-scratch start. And we actually read [email protected]. Include what you saw and roughly when, and we'll take it from there.