Markdown version of https://extraheadroom.com/docs/for-agents

# Headroom for AI agents

Install Headroom, inspect its routing, and verify requests. The desktop app requires a graphical session and user sign-in.

## Quick answer

On macOS, install with `brew install --cask headroom` and launch with `open -a Headroom`. Have the user complete sign-in and connector setup. Check the local proxy with `curl -fsS http://127.0.0.1:6767/stats`.

## 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](/faq#does-headroom-work-with-my-ide-or-agent-runner).

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](/docs/uninstall).

## Other resources

- [Troubleshooting](/docs/troubleshooting): setup, add-ons, learnings, and port conflicts.
- [Desktop app vs CLI](/headroom-desktop-vs-cli): options for machines without a graphical session.
- Markdown articles: append `.md`, for example [/docs/quickstart.md](/docs/quickstart.md).
- [/llms.txt](/llms.txt) and [/llms-full.txt](/llms-full.txt): product summaries and documentation links.