Headroom压缩工具

1 — Install

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

Install

uv tool install --python 3.13 "headroom-ai[all]"  # CLI, isolated app env
pip install "headroom-ai[all]"                    # Python, everything — includes the CLI
npm install headroom-ai                           # TypeScript SDK (library only)
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+.

[all] covers the core stack but not the framework adapters. Install those separately: pip install "headroom-ai[langchain]", and likewise [agno], [strands], [anyllm], [bedrock].

Pick Python 3.13 if you want the dollar figure. The dashboard's Proxy $ Saved tile prices compression with LiteLLM, which cannot be installed on Python 3.14+. Token savings still track on 3.14, but the dollar figure stays $0.00. To switch: pipx reinstall headroom-ai --python python3.13, then restart the proxy.

→ Installation guide — Docker tags, persistent service, PowerShell, devcontainers.

<details> <summary><b>uv, pipx, and MCP clients that don't inherit your PATH</b></summary>

Prefer uv tool install for the CLI 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 3.13 is not already available
uv tool install --python 3.13 "headroom-ai[all]"
uv tool update-shell      # if ~/.local/bin is not on PATH
headroom --version

Codex and other MCP clients often cannot inherit an interactive shell PATH. Configure the absolute path returned by command -v headroom:

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

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

With pipx, choose the interpreter explicitly:

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

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

CPU requirement (x86/x86_64). The ONNX-backed features — Magika content detection and embedding relevance — use a precompiled ONNX Runtime that needs AVX2. On x86 hosts without AVX2 (some Docker/QEMU setups, older cloud VMs) Headroom falls back to its non-ONNX paths — BM25 relevance, heuristic detection — rather than crashing. arm64 and Apple Silicon need no AVX2.

</details>

<details> <summary><b>Updating</b></summary>

headroom update          # detects pip / pipx / uv tool and upgrades in place
headroom update --check  # report the latest release without upgrading
headroom update --pre    # include pre-releases

headroom update works out how Headroom was installed (pip/venv, pip --user, pipx, uv tool) and runs the matching upgrade on macOS, Linux and Windows. For git checkouts, editable installs, Docker images and externally-managed system Pythons (PEP 668) it prints the correct manual step instead of guessing.

The proxy also prints a one-line "update available" notice at startup. It checks PyPI at most once a day, in the background, and never blocks. Opt out with HEADROOM_UPDATE_CHECK=off; it is also skipped in --stateless mode and CI.

</details>

<details> <summary><b>Corporate networks and SSL inspection</b></summary>

If pip install "headroom-ai[all]" fails with CERTIFICATE_VERIFY_FAILED (unable to get local issuer certificate), your network runs SSL inspection — a MITM proxy presenting a company CA. The build backend (maturin) downloads rustup over a connection your TLS stack does not trust. Install Rust first so the build never fetches it:

```bash

Compared to

Headroom runs locally, covers every content type, works with every major framework, and is reversible.

Headroom is the proxy, and it compresses everything flowing through it whatever sits upstream. Our recommended companion is Serena for semantic code navigation, installed by default when you wrap an agent, plus Ponytail if you want leaner model output. Everything else is your call — attach a code-memory MCP, Graphify, Caveman, or any other MCP server, and Headroom compresses downstream of all of it.