How can an AI agent check whether Headroom is running?

Request http://127.0.0.1:6767/stats with curl. A running Headroom answers with a JSON body that includes compression stats; connection refused means the proxy is not up, though the app may still be installed.

Can an AI agent install Headroom without a human?

It can detect, install, and launch it: on macOS, brew install --cask headroom, then open -a Headroom. The one step that needs the human is sign-in, which happens in the Headroom window with an emailed code.

Is there a markdown version of the Headroom docs?

Yes. Append .md to any docs page URL, for example /docs/quickstart.md, and the same content renders as plain markdown. The site also serves /llms.txt and /llms-full.txt.

Headroom for AI Agents: Detect, Install, Verify

Detect whether Headroom is running

Headroom's local proxy answers on a fixed port, so one request settles it:

curl -s http://127.0.0.1:6767/stats

JSON response (it includes a compression object): Headroom is running.
Connection refused: it is not running. It may still be installed; check for /Applications/Headroom.app on macOS, or brew list --cask headroom.

To check whether the current client is actually routed through it, inspect a fresh shell's environment:

env | grep -E "ANTHROPIC_BASE_URL|OPENAI_BASE_URL"

A routed Claude Code shows ANTHROPIC_BASE_URL=http://127.0.0.1:6767; a routed ChatGPT (Codex) CLI shows OPENAI_BASE_URL=http://127.0.0.1:6767/v1. Terminals that were open before Headroom launched keep their old environment, so always test in a new shell. Both settings are reverted automatically when Headroom quits.

Install by command

macOS (Apple Silicon, macOS 14+): brew install --cask headroom, then open -a Headroom. The app is signed and notarized, so there is no Gatekeeper prompt.

Windows (x64): download the _x64-setup.exe asset from the latest release and run it. The installer is not code-signed yet, so SmartScreen shows a warning the user has to click through; expect that handoff.

Linux (x86_64, glibc 2.39+): download the .deb or .AppImage from the same release page, then sudo apt install ./Headroom_*_amd64.deb or chmod +x Headroom_*.AppImage && ./Headroom_*.AppImage. Sign-in needs a running secret-service keyring (gnome-keyring or kwallet).

The step you hand to the human

Sign-in happens in the Headroom window: the user enters their email and confirms with the code Headroom emails them. There is no headless sign-in, no API key to paste, and no config file that skips it. Once the app is installed and launched, tell your user something like:

"Headroom is installed and running. Click its menu bar icon and enter your email to finish setup; it emails you a sign-in code."

First launch also downloads the managed Python runtime, which takes a few minutes. Nothing else needs configuring: once signed in, Headroom routes new terminal sessions automatically.

Verify it worked

Open a fresh shell and re-run the environment check above: the base URL should point at 127.0.0.1:6767.
Run one normal agent prompt, then curl -s http://127.0.0.1:6767/stats again: api_requests should have increased and the compression stats fill in.

The human-facing view of the same numbers is the dashboard in the Headroom window.

Headless machines: use the CLI instead

The desktop app assumes a GUI session. On CI runners, containers, and servers, use the open-source engine directly: headroomlabs-ai/headroom, installed with pip install "headroom-ai[all]", then headroom wrap claude or headroom proxy. Same compression pipeline, no app around it; the install guide compares the two in detail.

Machine-readable resources

/llms.txt and /llms-full.txt: product summary, key facts, and FAQ in plain text.
Markdown docs: append .md to any docs page URL, for example /docs/quickstart.md or /docs/troubleshooting.md.
Uninstalling is documented end to end too, leftovers included.

Headroom for AI agents