1 — Install

uv tool install --python 3.13 "headroom-ai[all]" # CLI as a global tool in a self-contained virtual env pip install "headroom-ai[all]" # Python — ships the headroom CLI npm install headroom-ai # TypeScript SDK only — no headroom CLI

2 — Pick your mode (the headroom commands below come from the uv or pip install)

headroom deploy # turnkey local deployment + agent config headroom wrap claude # wrap a coding agent headroom proxy --port 8787 # drop-in proxy, zero code changes

Codex / global install

If Codex or another MCP client cannot inherit a shell PATH reliably, install Headroom as a persistent uv tool and point the client at the absolute binary path:

uv tool install "headroom-ai[all]"
command -v headroom

Then use the returned path in MCP config:

[mcp_servers.headroom]
command = "/absolute/path/from/command-v/headroom"
args = ["mcp", "serve"]

command = "headroom" only works when the client starts with a PATH that already includes the uv tool directory.

GitHub Copilot CLI subscription mode

Headroom can route GitHub Copilot CLI subscription traffic through the local proxy:

headroom copilot-auth login
headroom wrap copilot --subscription -- --model gpt-4o

This lets Headroom intercept OpenAI-compatible Copilot CLI requests and apply the same proxy compression pipeline before forwarding to GitHub Copilot's hosted API. The wrapper exchanges Headroom's reusable GitHub OAuth token for Copilot's short-lived API token and prints the upstream endpoint as COPILOT_PROVIDER_API_URL=... during launch.

headroom copilot-auth login stores a Headroom-specific Copilot OAuth token. This avoids relying on generic GitHub or Copilot CLI tokens that can read Copilot account metadata but may still be rejected by Copilot's token-exchange endpoint.

For GitHub Enterprise Server or custom-domain Copilot deployments, set one of these before launching:

export GITHUB_COPILOT_ENTERPRISE_DOMAIN=ghe.example.com

---

## Install

```bash
uv tool install --python 3.13 "headroom-ai[all]"  # CLI, isolated app env
pip install "headroom-ai[all]"                    # Python, everything — includes the `headroom` CLI
npm install headroom-ai                           # TypeScript SDK (library only — no `headroom` CLI)
docker pull ghcr.io/headroomlabs-ai/headroom:latest

Granular extras: [proxy], [mcp], [ml] (Kompress-v2-base), [code], [memory], [vector] (optional HNSW backend — needs a C++ toolchain, not in [all]), [relevance], [image], [agno], [langchain], [evals], [pytorch-mps] (Apple-GPU memory-embedder offload — set HEADROOM_EMBEDDER_RUNTIME=pytorch_mps). Requires Python 3.10+.

Note: [all] covers the core stack but excludes framework adapters. Install them separately: pip install "headroom-ai[langchain]" (also [agno], [strands], [anyllm], [bedrock]).

Using uv for the headroom CLI? Prefer uv tool install so the command lives in an isolated app environment. On macOS, pass --python 3.13 if your default python3 is newer than the current wheel set:

brew install python@3.13  # if Python 3.13 is not already available
uv tool install --python 3.13 "headroom-ai[all]"
uv tool update-shell      # if ~/.local/bin is not already on PATH
headroom --version

For MCP clients such as Codex that do not inherit your interactive shell PATH, configure the absolute executable path returned by command -v headroom:

[mcp_servers.headroom]
command = "/Users/you/.local/bin/headroom"
args = ["mcp", "serve"]

Current native wheels cover macOS Apple Silicon and Linux. On Intel macOS, use Docker-native install until native wheel support lands.

Using pipx? Choose a supported interpreter explicitly:

pipx install --python python3.13 "headroom-ai[all]"

**Pick 3.13 if you want d