Installation

Install options

uv tool - you want the headroom CLI (proxy, wrap, mcp, learn, perf) installed once on your machine in an isolated app environment.

pip - you're writing Python, or you need the CLI (headroom proxy, wrap, mcp, learn, perf), regardless of what language your app is in.

npm - you're writing TypeScript/Node and want inline compress(), SDK wrapping (withHeadroom), or Vercel AI SDK middleware.

Python

Headroom requires Python 3.10+ and is published as headroom-ai on PyPI. Current release wheels are built for Python 3.10 through 3.13 on Linux (manylinux_2_28 x86_64 / aarch64) and macOS (Apple Silicon). Other targets — Windows and Intel macOS — fall back to building the Rust extension from the sdist and need a working native toolchain. If your installer is using a newer Python, force a supported interpreter.

CLI install with uv

For a host-level headroom command on macOS Apple Silicon or Linux, prefer uv tool install. It keeps Headroom in a dedicated app environment instead of tying it to the current project or shell Python.

uv tool install --python 3.13 "headroom-ai[all]"
headroom --version

On macOS with Homebrew, python3 may point at a newer interpreter than the current Headroom wheel set. Passing --python 3.13 keeps installation on a wheel-supported interpreter. If Python 3.13 is missing, install it with Homebrew or let uv download a managed interpreter:

brew install python@3.13
uv tool install --python 3.13 "headroom-ai[all]"

If headroom is installed but your shell cannot find it, add uv's tool directory to PATH:

uv tool update-shell

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"]

Native Intel macOS installs are currently tracked in headroomlabs-ai/headroom#525. Use Docker-Native Install on Intel Macs until native wheel support lands.

Core package

pip install headroom-ai

The core package includes the compress() function, SmartCrusher, CacheAligner, and live-zone ContentRouter compression. No heavy dependencies.

Note: IntelligentContext / RollingWindow (score-based history dropping) were retired in PR-B1. Headroom compresses fresh tool output and new turns only — it does not drop conversation history.

Extras

Install only what you need, or grab everything with [all]:

pip install "headroom-ai[all]"

You can combine extras:

pip install "headroom-ai[proxy,langchain,ml]"

Windows

There are no prebuilt Windows wheels yet, so pip install headroom-ai (and uv tool install, pipx install, …) will fall back to building the Rust extension from the sdist. The build needs the MSVC toolchain on PATH. Without it you'll see:

error: linker `link.exe` not found
note: please ensure that Visual Studio 2017 or later, or Build Tools for
Visual Studio were installed with the Visual C++ option

To install the prerequisites:

1. MSVC toolchain — install Build Tools for Visual Studio and select the "Desktop development with C++" workload (this gives you link.exe). VS Code on its own is not enough.

2. Rust — install via rustup. Choose the stable-x86_64-pc-windows-msvc toolchain so Cargo uses the MSVC linker you just installed.

3. Open a fresh PowerShell so the installer's PATH updates take effect, then run the install:

   uv tool install --python 3.13 "headroom-ai[all]"
   # or
   pip install "headroom-ai[all]"

If you'd rather avoid the native toolchain entirely, run Headroom through Docker — see the Docker section below. Native Windows wheels are tracked in #636.

pipx

pipx creates one virtual environment per app. If that environment uses an unsupported Python version, pipx may resolve an older compatible Headroom release instead of the newest one.

Use Python 3.13 explicitly. If you already use uv, prefer the uv tool path above.

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

For a pinned release:

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

Check which Python an existing pipx environment uses:

pipx list

Verify the install

python -c "import headroom; print(headroom.__version__)"

TypeScript / Node.js

The TypeScript SDK is published as headroom-ai on npm. It requires Node.js 18+. It is a library you import — it does not install the headroom CLI (headroom wrap, headroom proxy, etc.), which ships only with the Python package above.

npm install headroom-ai

Or with other package managers:

pnpm add headroom-ai
yarn add headroom-ai

pip install "headroom-ai[proxy]"
headroom proxy --port 8787

import { compress } from 'headroom-ai';

const result = await compress(messages, {
  baseUrl: 'http://localhost:8787',
});

Verify the install

node -e "const h = require('headroom-ai'); console.log('headroom-ai loaded')"

Docker

Pre-built images are published to GitHub Container Registry on every release.

docker pull ghcr.io/headroomlabs-ai/headroom:latest
docker run -p 8787:8787 ghcr.io/headroomlabs-ai/headroom:latest

Image tags

Build from source

Use Docker Bake for multi-variant builds:

# List all targets
docker buildx bake --list targets

# Build the default runtime image
docker buildx bake runtime-default

# Build a specific variant with custom registry
docker buildx bake runtime-code-slim-nonroot \
  --set '*.tags=my-registry/headroom:code-slim-nonroot'

Environment variables

These variables configure Headroom at runtime. Set them in your shell, .env file, or container environment.

LLM provider keys

The Vertex AI backend also requires google-cloud-aiplatform>=1.38, which is not included in any extra or Docker image — see Google Vertex AI for setup details.

Proxy configuration

TypeScript SDK

Troubleshooting

These are common issues faced during initial setup and how to resolve them.

Python version error

This project requires Python 3.10+.

Check your version:

python3 --version

If needed (Mac with Homebrew):

brew install python@3.13

Editable install fails (pip install -e)

Upgrade pip to the latest version:

python3 -m pip install --upgrade pip

Missing cargo (Rust error)

Some tests require Rust tooling.

The recommended way to install rust is using rustup. You can find the official installation instructions here.

Dashboard

Headroom serves a live savings dashboard while the proxy is running. Open it with:

headroom dashboard            # opens http://localhost:8787/dashboard in your browser
headroom dashboard --no-open  # just print the URL

Or browse to http://localhost:8787/dashboard directly (use --port / HEADROOM_PORT if you run the proxy on a different port).

Next steps