Security

Report a vulnerability

Please do not open a public issue. Report it privately through GitHub's vulnerability reporting, or email support@extraheadroom.com with "Security" in the subject. Include what you found, how to reproduce it and your Headroom version. We support the latest stable release and the current beta.

What leaves your computer

• Your prompts, code and files go from your computer to the provider your tool already uses: Anthropic for Claude Code, OpenAI for Codex. They never pass through our servers.
• Your Claude and Codex sign-in tokens are only ever sent to Anthropic or OpenAI.
• What the app does send us, and to our analytics and crash-reporting services, is listed in the privacy policy.

On your computer

• The proxy listens only on 127.0.0.1 (ports 6767 and 6768), so other machines on your network cannot reach it.
• It refuses requests that come from a web page, so a website you visit cannot send requests through it.
• Headroom's own sign-in is stored in the macOS Keychain or your operating system's credential store.
• The in-app uninstall (Settings, Uninstall Headroom) reverts every change Headroom made to your other tools. See uninstall.

Signed releases and updates

• macOS builds are Developer ID-signed and notarized by Apple.
• Windows installers are Authenticode-signed.
• Linux packages are not signed yet.
• Updates carry a separate signature, and the app refuses to install an update whose signature does not match.

Verify a download

Each stable release from v0.9.27 on has a GitHub build-provenance attestation for its macOS, Windows and Linux downloads. It shows that the file was built by our release pipeline from the public repository. With the GitHub CLI installed, run:

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

Builds are not reproducible yet, so you cannot rebuild a release yourself and compare it byte for byte.

What Headroom installs

On first launch Headroom downloads its own Python runtime, the open-source headroom-ai compression engine and a few bundled tools.

• Each download is checked against a SHA-256 hash built into the app, and a mismatch stops the install. From version 0.9.29 that includes installing the engine from PyPI when its direct download fails.
• Every core Python dependency is installed from a hash-locked list, as prebuilt packages only, so no package build scripts run on your machine.
• Our CI checks the Rust, JavaScript and Python dependencies against known-vulnerability databases on every change, and a release cannot publish until those checks pass.
• The build pipeline's GitHub Actions are pinned to exact commits.

What Headroom does not protect against

• There has been no independent security audit, penetration test or third-party code review.
• Headroom runs as your user and is not sandboxed. As a proxy it handles your prompts and your provider credentials, the same trust you give Claude Code, Codex or any tool you install. If Headroom or something it depends on were compromised, nothing at the operating-system level would stop it reading your files. For stronger isolation, run your agent and Headroom in a virtual machine or dev container.
• Rolling back to the previous engine version after a failed update installs it from PyPI without a hash check. Before version 0.9.29, the fallback used when the engine download failed was not hash-checked either.
• Optional add-ons (MarkItDown, Serena) and the compression models the engine downloads are not pinned to a hash.

The desktop app is open source under the MIT licence: github.com/gglucass/headroom-desktop.