Installation
Install Headroom via pip, npm, or Docker. Includes all Python extras, TypeScript setup, Docker image tags, and environment variables.
Python
Headroom requires Python 3.10+ and is published as headroom-ai on PyPI.
Core package
pip install headroom-aiThe core package includes the compress() function, SmartCrusher, CacheAligner, and IntelligentContext. No heavy dependencies.
Extras
Install only what you need, or grab everything with [all]:
pip install "headroom-ai[all]"| Extra | What it adds | Install command |
|---|---|---|
proxy | Proxy server, MCP tools, HTTP API | pip install "headroom-ai[proxy]" |
ml | Kompress (ModernBERT text compression, requires PyTorch) | pip install "headroom-ai[ml]" |
code | CodeCompressor (tree-sitter AST parsing) | pip install "headroom-ai[code]" |
mcp | MCP server tools (headroom_compress, headroom_retrieve, headroom_stats) | pip install "headroom-ai[mcp]" |
langchain | LangChain HeadroomChatModel wrapper | pip install "headroom-ai[langchain]" |
agno | Agno HeadroomAgnoModel wrapper | pip install "headroom-ai[agno]" |
evals | Evaluation framework (GSM8K, SQuAD, BFCL benchmarks) | pip install "headroom-ai[evals]" |
all | Everything above | pip install "headroom-ai[all]" |
You can combine extras:
pip install "headroom-ai[proxy,langchain,ml]"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+.
npm install headroom-aiOr with other package managers:
pnpm add headroom-ai
yarn add headroom-aiThe TS SDK needs a running proxy
The TypeScript SDK sends messages to the Headroom proxy over HTTP for compression. The proxy runs the full compression pipeline (Python). Start it before using the SDK:
pip install "headroom-ai[proxy]"
headroom proxy --port 8787Then point the SDK at it:
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/chopratejas/headroom:latest
docker run -p 8787:8787 ghcr.io/chopratejas/headroom:latestImage tags
| Tag | Extras | Base image | Description |
|---|---|---|---|
latest | proxy | Debian slim | Default image, runs the proxy |
<version> | proxy | Debian slim | Pinned version |
nonroot | proxy | Debian slim | Runs as non-root user |
code | proxy,code | Debian slim | Includes tree-sitter for code compression |
code-nonroot | proxy,code | Debian slim | Code compression, non-root |
slim | proxy | Distroless | Minimal image, no shell |
slim-nonroot | proxy | Distroless | Minimal, non-root |
code-slim | proxy,code | Distroless | Code compression, minimal |
code-slim-nonroot | proxy,code | Distroless | Code compression, minimal, non-root |
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
| Variable | Description |
|---|---|
OPENAI_API_KEY | OpenAI API key (used when proxying to OpenAI) |
ANTHROPIC_API_KEY | Anthropic API key (used when proxying to Anthropic) |
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY | AWS credentials for Bedrock backend |
GOOGLE_APPLICATION_CREDENTIALS | Google Cloud credentials for Vertex AI backend |
Proxy configuration
| Variable | Default | Description |
|---|---|---|
HEADROOM_PORT | 8787 | Port the proxy listens on |
HEADROOM_HOST | 0.0.0.0 | Host the proxy binds to |
HEADROOM_MODE | optimize | Default mode: optimize, audit, or passthrough |
HEADROOM_LOG_LEVEL | INFO | Logging level |
TypeScript SDK
| Variable | Default | Description |
|---|---|---|
HEADROOM_BASE_URL | http://localhost:8787 | Proxy URL for the TypeScript SDK |
HEADROOM_API_KEY | (none) | API key if the proxy requires auth |