Headroom

https://extraheadroom.com/docs
Admin
Headroom is a local proxy application that reduces token usage and API costs for coding agents...
Tokens:10,818
Snippets:116
Trust Score:6.4
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install Headroom with Homebrew on macOS

Source: https://extraheadroom.com/docs/quickstart.md

Install the Headroom cask with Homebrew, then open the app. Requires macOS and Homebrew.

```bash
brew install --cask headroom
```

```bash
open -a Headroom
```

--------------------------------

### Pi models.json configuration for Headroom routing

Source: https://extraheadroom.com/docs/compatibility

Add these provider entries to ~/.pi/agent/models.json to route Pi's built-in providers through Headroom. The anthropic entry works with an Anthropic API key or Claude Pro/Max login; openai requires an OpenAI API key only; openai-codex is for ChatGPT Plus/Pro subscriptions and is the least tested. Restart Pi or reopen /model after editing. Headroom does not undo this manual setup, so Pi fails to connect while Headroom is not running; remove these lines before uninstalling Headroom.

```json
{
  "providers": {
    "anthropic": { "baseUrl": "http://127.0.0.1:6767" },
    "openai": { "baseUrl": "http://127.0.0.1:6767/v1" },
    "openai-codex": { "baseUrl": "http://127.0.0.1:6767/backend-api" }
  }
}
```

--------------------------------

### Verify build provenance with gh attestation verify

Source: https://extraheadroom.com/docs/security

Verifies the build provenance of a downloaded stable release file using the GitHub CLI. The command checks that the file was built by the release pipeline from the specified repository. Requires the GitHub CLI to be installed.

```shell
gh attestation verify <downloaded file> --repo gglucass/headroom-desktop
```

--------------------------------

### Update Headroom CLI with pip

Source: https://extraheadroom.com/docs/update

Run this command in the same Python environment where the CLI was installed to update it to the latest version. After updating, restart any running 'headroom proxy' or 'headroom wrap' sessions. If 'headroom' is not found, the pip scripts directory is not on your PATH.

```bash
pip install -U headroom-ai
```

--------------------------------

### Check Headroom connection on Windows with curl.exe

Source: https://extraheadroom.com/docs/troubleshooting

Run in Command Prompt on Windows. Sends a request to the local health endpoint and prints the HTTP status code. A 200 means the connection works; 000 means it was cut. Run it a few times because drops are intermittent.

```shell
curl.exe -s -m 5 -o NUL -w "%{http_code}\n" http://127.0.0.1:6767/readyz
```

--------------------------------

### Review Headroom routing guard in Codex CLI

Source: https://extraheadroom.com/docs/quickstart.md

Run inside a new coding-agent session in the Codex CLI to review and trust Headroom's routing guard. Repeat if the guard changes.

```bash
/hooks
```

--------------------------------

### Check port 6767 on macOS/Linux with lsof

Source: https://extraheadroom.com/docs/troubleshooting

Use this command on macOS or Linux to identify the process listening on port 6767, the default proxy port. The output shows the owning process, which you can then stop or reconfigure before relaunching Headroom.

```bash
lsof -nP -iTCP:6767 -sTCP:LISTEN
```

--------------------------------

### Check port 6767 on Windows PowerShell with Get-NetTCPConnection

Source: https://extraheadroom.com/docs/troubleshooting

Use this command in Windows PowerShell to identify the process listening on port 6767, the default proxy port. The output shows the owning process, which you can then stop or reconfigure before relaunching Headroom.

```powershell
Get-NetTCPConnection -LocalPort 6767 -State Listen
```

--------------------------------

### Check Headroom connection on macOS or Linux with curl

Source: https://extraheadroom.com/docs/troubleshooting

Run in a terminal on macOS or Linux. Sends a request to the local health endpoint and prints the HTTP status code. A 200 means the connection works; 000 means it was cut. Run it a few times because drops are intermittent.

```shell
curl -s -m 5 -o /dev/null -w "%{http_code}\n" http://127.0.0.1:6767/readyz
```
Tokens:
Raw