Installation

Install options

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

pip - you're writing Python, or you need the CLI, 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. Release wheels are built for CPython 3.10 through 3.13 on Linux (manylinux_2_28 x86_64 / aarch64), macOS (Apple Silicon and Intel), and Windows x86_64. The Rust extension uses the CPython stable ABI, so those wheels are forward-compatible with newer supported CPython versions; optional dependencies may impose their own Python/platform limits. Platforms outside that matrix fall back to the source distribution and need a Rust/native toolchain.

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

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

[all] is the full built-in runtime bundle, not every integration or optional backend. The rows marked “not in [all]” must be requested explicitly.

You can combine extras:

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

Source builds and unsupported targets

Windows x86_64, Intel/Apple Silicon macOS, and Linux x86_64/aarch64 have release wheels. If pip selects the source distribution on another target (or because a matching wheel is unavailable), the build needs Rust plus the platform C/C++ toolchain. On Windows without MSVC on PATH, for example, 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 a source build, use a supported interpreter/platform or run Headroom through Docker — see the Docker section below.

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, replace <version> with the version you require:

pipx install --python python3.13 "headroom-ai[all]==<version>"

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