Headroom for AI agents

Install and finish setup

• macOS: macOS 14 or later, Apple Silicon or Intel. Run brew install --cask headroom, then open -a Headroom, or use the downloaded installer.
• Windows: run the x64 setup executable from the download page.
• Linux: use the x86_64 .deb or AppImage. The build requires glibc 2.39 or newer and a running secret-service keyring for sign-in.

The user signs in to Headroom with an email verification code. Allow the runtime downloads to finish and enable the intended connector. Installing Headroom does not install or sign in to the coding-agent CLI for the user.

For the Codex CLI, review and trust Headroom's routing guard through /hooks, including after the guard changes.

Inspect the agent's routing

• Claude Code: Headroom sets ANTHROPIC_BASE_URL in ~/.claude/settings.json and adds a managed shell export where possible.
• Codex: Headroom registers a managed provider in ~/.codex/config.toml and adds an OPENAI_BASE_URL shell export where possible. The CLI, desktop app, and IDE extension share the config file.

Any host that launches these CLIs as a subprocess under the same home directory inherits the routing, including IDE extensions and agent runners. A tool that calls the provider API with its own HTTP client does not. See the FAQ entry on IDEs and agent runners.

The default proxy URLs are http://127.0.0.1:6767 for Claude Code and http://127.0.0.1:6767/v1 for Codex. An empty shell variable does not establish a routing failure: inspect the agent configuration and verify requests.

Claude Code inside the Claude desktop app does not use these routing settings and cannot be optimized by Headroom.

Verify requests reach Headroom

1. Run curl -fsS http://127.0.0.1:6767/stats. In Windows PowerShell, type curl.exe instead of curl: plain curl there is an alias for Invoke-WebRequest and rejects these flags. A successful Headroom response contains JSON metrics. Connection refused means the local listener is unavailable, not necessarily that the app is uninstalled.
2. Note requests.total in the JSON response.
3. Start a fresh agent session and send a prompt that reads a project file or runs a command.
4. Read the endpoint again and check whether requests.total increased. Keep other agent sessions idle during the check to avoid attributing their requests to this session.

This checks traffic independently of savings. A request can pass through without producing a compression record. Activity shows recorded events; it is not a complete request log.

Stop routing or uninstall

For a temporary direct-connection test, quit Headroom normally and restart the agent and terminal. This restores the managed connection settings but retains Headroom's data.

For removal, use Settings > Uninstall Headroom in the app and review its confirmation dialog. Do not substitute deleting the app or unsetting shell variables for that cleanup. See the uninstall guide.

Other resources

• Troubleshooting: setup, add-ons, learnings, and port conflicts.
• Desktop app vs CLI: options for machines without a graphical session.
• Markdown articles: append .md, for example /docs/quickstart.md.
• /llms.txt and /llms-full.txt: product summaries and documentation links.