Headroom

https://docs.headroomlabs.ai/docs
Admin
Headroom is a context optimization layer for LLM applications that compresses tool outputs, database...
Tokens:167,690
Snippets:1,430
Trust Score:6
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install OpenClaw plugin with headroom wrap

Source: https://docs.headroomlabs.ai/docs/openclaw

Recommended one-command setup that installs the plugin and configures the contextEngine slot.

```bash
headroom wrap openclaw
```

--------------------------------

### Install LangChain provider and integration packages

Source: https://docs.headroomlabs.ai/docs/langchain

Install the separate provider and integration packages required for the examples on this page.

```bash
pip install langchain-anthropic         # ChatAnthropic
pip install langchain                   # create_agent, init_chat_model
pip install langchain-classic           # ContextualCompressionRetriever
```

--------------------------------

### Install and start the Headroom proxy

Source: https://docs.headroomlabs.ai/docs/anthropic-sdk

Install the Headroom proxy and start it. The TypeScript SDK sends messages to the local proxy for compression, so start it before using the SDK.

```bash
pip install "headroom-ai[proxy]"
headroom proxy
```

--------------------------------

### Quick Start with SharedContext (TypeScript)

Source: https://docs.headroomlabs.ai/docs/shared-context

Quick start example for SharedContext in TypeScript. Shows storing large output with put(), retrieving compressed summary with get(), and getting full details with get(key, { full: true }).

```TypeScript
import { SharedContext } from "headroom-ai";

const ctx = new SharedContext();

// Agent A stores large output
const entry = await ctx.put("research", bigResearchOutput, {
  agent: "researcher",
});

// Agent B gets compressed version (~80% smaller)
const summary = ctx.get("research");

// Agent B needs full details on demand
const full = ctx.get("research", { full: true });
```

--------------------------------

### Install all extras with pip

Source: https://docs.headroomlabs.ai/docs/installation

Installs the full built-in runtime bundle, which includes proxy, code, ml, memory, relevance, image, reports, otel, evals, voice, html, mcp, and spreadsheet extras. This is the recommended way to get all core functionality.

```bash
pip install "headroom-ai[all]"
```

--------------------------------

### OpenAIProvider usage example

Source: https://docs.headroomlabs.ai/docs/api-reference

Shows how to instantiate OpenAIProvider, get a token counter for 'gpt-4o', count text, get context limit (128000), and estimate cost.

```python
from headroom import OpenAIProvider

provider = OpenAIProvider()

counter = provider.get_token_counter("gpt-4o")
tokens = counter.count_text("Hello, world!")
limit = provider.get_context_limit("gpt-4o")  # 128000
cost = provider.estimate_cost(input_tokens=1000, output_tokens=500, model="gpt-4o")
```

--------------------------------

### Install and run Headroom proxy

Source: https://docs.headroomlabs.ai/docs/claude-code-azure-foundry

One-command setup: installs the Headroom proxy with the `proxy` extra and wraps Claude Code. With `CLAUDE_CODE_USE_FOUNDRY=1`, it automatically derives the Azure endpoint, starts the proxy, and points Claude Code to it.

```bash
pip install "headroom-ai[proxy]"
headroom wrap claude
```

--------------------------------

### Start Headroom proxy with cloud provider backends

Source: https://docs.headroomlabs.ai/docs/proxy

Shows how to start the Headroom proxy with each supported cloud provider backend. The OpenRouter example requires setting the OPENROUTER_API_KEY environment variable.

```bash
# AWS Bedrock
headroom proxy --backend bedrock --region us-east-1

# Google Vertex AI
headroom proxy --backend vertex_ai --region us-central1

# Azure OpenAI
headroom proxy --backend azure

# OpenRouter (400+ models)
OPENROUTER_API_KEY=sk-or-... headroom proxy --backend openrouter
```

--------------------------------

### Start Headroom proxy with token, logging, and budget

Source: https://docs.headroomlabs.ai/docs/proxy

Start the Headroom proxy with basic usage, public access using the token protocol, or with logging and budget options. The public access example requires sending an Authorization or X-Headroom-Proxy-Token header from the caller.

```bash
# Basic usage
headroom proxy

# Deliberate public access, with the existing token protocol
HEADROOM_PROXY_TOKEN='replace-with-a-secret' headroom proxy --host 0.0.0.0 --port 8080
# Send `Authorization: Bearer replace-with-a-secret` or
# `X-Headroom-Proxy-Token: replace-with-a-secret` from the caller.

# With logging and budget
headroom proxy \
  --log-file /var/log/headroom.jsonl \
  --budget 100.0
```

--------------------------------

### Install and enable headroom-oauth2

Source: https://docs.headroomlabs.ai/docs/oauth2-upstream

Install the headroom-oauth2 extension and start the Headroom proxy with the OAuth2 extension enabled for an OpenAI-compatible backend.

```bash
pip install headroom-oauth2
headroom proxy --backend litellm-openai --proxy-extension oauth2
```

--------------------------------

### headroom install apply provider selection examples

Source: https://docs.headroomlabs.ai/docs/persistent-installs

Shows three invocations of `headroom install apply` with different provider selection options: `--providers auto`, `--providers all --scope user`, and `--providers manual --target claude --target copilot`. Use these to configure providers for persistent installs.

```bash
headroom install apply --providers auto
headroom install apply --providers all --scope user
headroom install apply --providers manual --target claude --target copilot
```

--------------------------------

### Quick start with HeadroomAgnoModel

Source: https://docs.headroomlabs.ai/docs/agno

Wrap an Agno model with HeadroomAgnoModel to automatically compress context. The example shows a sample savings summary output.

```python
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from headroom.integrations.agno import HeadroomAgnoModel

model = HeadroomAgnoModel(wrapped_model=OpenAIChat(id="gpt-4o"))
agent = Agent(model=model)

response = agent.run("What's the capital of France?")

print(f"Tokens saved: {model.total_tokens_saved}")
print(model.get_savings_summary())
# {'total_requests': 1, 'total_tokens_saved': 245, 'average_savings_percent': 12.3,
#  'total_tokens_before': 1990, 'total_tokens_after': 1745}
```

--------------------------------

### Headroom MCP CLI commands

Source: https://docs.headroomlabs.ai/docs/mcp

Install, check, uninstall, and run the Headroom MCP server. Use --proxy-url to point at a custom proxy, --force to overwrite an existing registration, and --debug for verbose output. The Streamable HTTP mode example starts the server on 127.0.0.1:8788 with the /mcp path.

```bash
# Install (registers with Claude Code)
headroom mcp install
headroom mcp install --proxy-url http://host:9000  # Custom proxy URL
headroom mcp install --force                        # Overwrite existing

# Check status
headroom mcp status

# Uninstall
headroom mcp uninstall

# Debug mode
headroom mcp serve --debug

# Streamable HTTP mode
headroom mcp serve --transport http --host 127.0.0.1 --port 8788 --path /mcp
```

--------------------------------

### Install and run Headroom proxy with remote access

Source: https://docs.headroomlabs.ai/docs/litellm

Installs the proxy extras and runs the Headroom proxy with remote access enabled. Without HEADROOM_COMPRESS_ALLOW_REMOTE=1, remote callers get a 404 (blocked, not missing). If HEADROOM_PROXY_TOKEN is set, send it as X-Headroom-Proxy-Token or you get 401.

```bash
pip install "headroom-ai[proxy]"

# Headroom is loopback-only by default and answers remote callers with 404.
HEADROOM_COMPRESS_ALLOW_REMOTE=1 headroom proxy
```

--------------------------------

### Install Headroom proxy with OTLP extra

Source: https://docs.headroomlabs.ai/docs/metrics

Install the 'otel' extra to enable OTLP metric export.

```bash
pip install "headroom-ai[proxy,otel]"
```

--------------------------------

### Install Headroom optional dependencies

Source: https://docs.headroomlabs.ai/docs/troubleshooting

Install Headroom with optional extras: proxy, relevance, code, or all.

```bash
# For proxy server
pip install "headroom-ai[proxy]"

# For embedding-based relevance scoring
pip install "headroom-ai[relevance]"

# For code compression (tree-sitter)
pip install "headroom-ai[code]"

# For everything
pip install "headroom-ai[all]"
```

--------------------------------

### Install headroom-ai and @anthropic-ai/sdk

Source: https://docs.headroomlabs.ai/docs/anthropic-sdk

Install the Headroom wrapper and the Anthropic TypeScript SDK.

```bash
npm install headroom-ai @anthropic-ai/sdk
```

--------------------------------

### Install headroom-ai and litellm

Source: https://docs.headroomlabs.ai/docs/litellm

Install the required packages for the Headroom LiteLLM integration.

```bash
pip install headroom-ai litellm
```

--------------------------------

### Install Headroom Agno integration

Source: https://docs.headroomlabs.ai/docs/agno

Install the Headroom Agno integration and the Agno library.

```bash
pip install "headroom-ai[agno]" agno
```

--------------------------------

### Manual install of OpenClaw plugin

Source: https://docs.headroomlabs.ai/docs/openclaw

Manual installation steps: install the headroom-ai[proxy] package and then install the plugin with --dangerously-force-unsafe-install, which is required because OpenClaw treats process-launching plugins as unsafe by default.

```bash
pip install "headroom-ai[proxy]"
openclaw plugins install --dangerously-force-unsafe-install headroom-ai/openclaw
```

--------------------------------

### Install Headroom MCP SDK

Source: https://docs.headroomlabs.ai/docs/mcp

Installs the MCP SDK for Headroom. Run this when you see the error "MCP SDK not installed".

```bash
pip install "headroom-ai[mcp]"
```

--------------------------------

### Install headroom-ai and openai

Source: https://docs.headroomlabs.ai/docs/openai-sdk

Install the headroom-ai package and the OpenAI SDK as dependencies.

```bash
npm install headroom-ai openai
```

--------------------------------

### Install Headroom on Linux

Source: https://docs.headroomlabs.ai/docs/docker-install

One-line installer for Linux. Requires Docker to be installed and available. Installs a headroom wrapper into ~/.local/bin or ~/bin and updates shell startup files to add the wrapper directory to PATH.

```bash
curl -fsSL https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/scripts/install.sh | bash
```

--------------------------------

### Install Headroom on macOS (bash 4.3+)

Source: https://docs.headroomlabs.ai/docs/docker-install

One-line installer for macOS with bash 4.3+. Stock /bin/bash on macOS is 3.2, so install a newer bash first (e.g., via Homebrew) and run the installer with that shell. The installed wrapper pins that same bash interpreter for later invocations.

```bash
curl -fsSL https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/scripts/install.sh | "$(brew --prefix bash)/bin/bash"
```

--------------------------------

### Install headroom-ai[code]

Source: https://docs.headroomlabs.ai/docs/code-compression

Installs the tree-sitter language pack required for code-aware compression.

```bash
# Install tree-sitter language pack
pip install "headroom-ai[code]"
```

--------------------------------

### Start proxy with HEADROOM_SAVINGS_PROFILE=agent-90

Source: https://docs.headroomlabs.ai/docs/proxy

Launches the proxy with the agent-90 savings profile, which targets ~90% token savings, pins a 0.10 keep-ratio, and forces Kompress. The profile is read at proxy startup and overrides the default coding profile.

```bash
# Aggressive ~90% token-savings profile
HEADROOM_SAVINGS_PROFILE=agent-90 headroom proxy --port 8787
```

--------------------------------

### Install act and actionlint

Source: https://docs.headroomlabs.ai/docs/releases

Installs act and actionlint on macOS via Homebrew or on Windows via winget.

```bash
# macOS
brew install act actionlint

# Windows
winget install act
winget install actionlint
```

--------------------------------

### Install headroom-ai and strands-agents

Source: https://docs.headroomlabs.ai/docs/strands

Install the Headroom integration for Strands Agents along with the Strands library.

```bash
pip install headroom-ai strands-agents
```

--------------------------------

### Install Vertex SDK for Vertex AI backend

Source: https://docs.headroomlabs.ai/docs/proxy

Installs the Headroom proxy extra along with the required Vertex SDK. Without google-cloud-aiplatform, the first Vertex request fails with litellm.BadRequestError mentioning 'No module named vertexai'.

```bash
pip install "headroom-ai[proxy]" "google-cloud-aiplatform>=1.38"
```

--------------------------------

### Set environment variables and start the proxy

Source: https://docs.headroomlabs.ai/docs/proxy

Configure the proxy for deliberate public access. Set the host, token, port, and budget, then optionally route OpenAI, Anthropic, and Bedrock passthrough traffic to custom endpoints. The final command starts the proxy.

```bash
export HEADROOM_HOST=0.0.0.0
export HEADROOM_PROXY_TOKEN='replace-with-a-secret'
export HEADROOM_PORT=8787
export HEADROOM_BUDGET=100.0

# Route OpenAI passthrough requests to a custom endpoint
export OPENAI_TARGET_API_URL=https://custom.openai.endpoint.com

# Route Anthropic passthrough requests to a custom endpoint
export ANTHROPIC_TARGET_API_URL=https://litellm.company.internal

# Compress Bedrock InvokeModel traffic, forwarding to a re-signing gateway
export BEDROCK_TARGET_API_URL=http://127.0.0.1:4000

headroom proxy
```

--------------------------------

### headroom proxy CLI examples with optional flags

Source: https://docs.headroomlabs.ai/docs/proxy

Example invocations of the headroom proxy CLI with optional features: enable persistent memory, enable live traffic learning with a custom minimum evidence threshold, enable Codex wire debugging, and enable compression passthrough via the HEADROOM_COMPRESS_PASSTHROUGH environment variable.

```bash
headroom proxy --memory
headroom proxy --learn --min-evidence 3
headroom proxy --codex-wire-debug
HEADROOM_COMPRESS_PASSTHROUGH=1 headroom proxy
```

--------------------------------

### headroom wrap commands for supported agents

Source: https://docs.headroomlabs.ai/docs/proxy

Launch supported CLI agents through the local proxy. Each command starts the proxy and configures the agent as noted in the comments.

```bash
# Claude Code
headroom wrap claude

# Claude Code extension in VS Code (configures settings, then starts the proxy)
headroom wrap vscode-claude

# OpenAI Codex
headroom wrap codex

# Aider
headroom wrap aider

# Cursor (starts the proxy and prints settings to paste into Cursor)
headroom wrap cursor

# Grok Build (updates ~/.grok/config.toml and starts the proxy)
headroom wrap grok-build
```

--------------------------------

### Dockerfile for headroom proxy image

Source: https://docs.headroomlabs.ai/docs/proxy

Dockerfile for the proxy image. Installs build-essential because headroom-ai includes hnswlib, a C++ extension compiled from source, then removes it to keep the image slim. Exposes port 8787 and runs the proxy command.

```dockerfile
FROM python:3.11-slim
RUN apt-get update && apt-get install -y --no-install-recommends build-essential \
    && pip install "headroom-ai[proxy]" \
    && apt-get purge -y build-essential && apt-get autoremove -y \
    && rm -rf /var/lib/apt/lists/*
EXPOSE 8787
CMD ["headroom", "proxy", "--host", "0.0.0.0", "--port", "8787"]
```

--------------------------------

### GET /stats

Source: https://docs.headroomlabs.ai/docs/proxy

Returns live session statistics plus durable persistent savings totals. Persistent savings are stored at `~/.headroom/proxy_savings.json` (override with `HEADROOM_SAVINGS_PATH`).

```APIDOC
## GET /stats

### Description
Returns live session statistics plus durable persistent savings totals. Persistent savings are stored at `~/.headroom/proxy_savings.json` (override with `HEADROOM_SAVINGS_PATH`).

### Method
GET

### Endpoint
/stats

### Response
#### Success Response (200)
- **persistent_savings** (object) - Durable lifetime savings totals.

#### Response Example
(No example provided in source.)
```

--------------------------------

### Set Vertex AI environment variables and start proxy

Source: https://docs.headroomlabs.ai/docs/proxy

Sets the LiteLLM-specific environment variables required by the Vertex AI backend. VERTEXAI_PROJECT and VERTEXAI_LOCATION are not the standard Google Cloud variables; if VERTEXAI_PROJECT is unset, requests may silently bill a different GCP project.

```bash
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json  # or use ADC
export VERTEXAI_PROJECT=<your-gcp-project>
export VERTEXAI_LOCATION=us-central1

headroom proxy --backend vertex_ai --region us-central1
```

--------------------------------

### Validate Setup with client.validate_setup()

Source: https://docs.headroomlabs.ai/docs/troubleshooting

Call validate_setup() on the client to check provider, storage, and config. The printed result shows common issues and their fixes, such as setting OPENAI_API_KEY, checking path permissions, or using only "audit" or "optimize" modes.

```python
result = client.validate_setup()
print(result)

# Common issues:
# {"provider": {"ok": False, "error": "No API key"}}
#   -> Set OPENAI_API_KEY or pass api_key to OpenAI()
#
# {"storage": {"ok": False, "error": "unable to open database"}}
#   -> Check path permissions, use :memory: for testing
#
# {"config": {"ok": False, "error": "Invalid mode"}}
#   -> Use "audit" or "optimize" only
```

--------------------------------

### GET /stats with curl

Source: https://docs.headroomlabs.ai/docs/proxy

Retrieve live session statistics plus durable persistent_savings totals. The durable data is stored at ~/.headroom/proxy_savings.json and can be overridden with the HEADROOM_SAVINGS_PATH environment variable.

```bash
curl http://localhost:8787/stats
```

--------------------------------

### GET /metrics with curl and Prometheus output

Source: https://docs.headroomlabs.ai/docs/proxy

Fetch Prometheus-format metrics. The output shows counters for requests, tokens saved, persistent savings, compression ratio buckets, latency buckets, and cache hits. headroom_tokens_saved_total is the runtime counter for the current proxy process, while headroom_persistent_savings_tokens_saved_total matches /stats.persistent_savings.

```bash
curl http://localhost:8787/metrics
```

```prometheus
headroom_requests_total{mode="optimize"} 1234
headroom_tokens_saved_total 5678900
headroom_persistent_savings_tokens_saved_total 5678900
headroom_compression_ratio_bucket{le="0.5"} 890
headroom_latency_seconds_bucket{le="0.01"} 800
headroom_cache_hits_total 456
```

--------------------------------

### GET /health

Source: https://docs.headroomlabs.ai/docs/proxy

Returns the health status of the proxy, including optimization mode and current statistics.

```APIDOC
## GET /health

### Description
Returns the health status of the proxy, including optimization mode and current statistics.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - Health status, e.g., "healthy".
- **optimize** (boolean) - Whether optimization is enabled.
- **stats** (object) - Current statistics.
  - **total_requests** (integer) - Total number of requests processed.
  - **tokens_saved** (integer) - Total tokens saved.
  - **savings_percent** (number) - Percentage of tokens saved.

#### Response Example
{
  "status": "healthy",
  "optimize": true,
  "stats": {
    "total_requests": 42,
    "tokens_saved": 15000,
    "savings_percent": 45.2
  }
}
```

--------------------------------

### GET /health with curl and JSON response

Source: https://docs.headroomlabs.ai/docs/proxy

Check the proxy health endpoint. The response includes the status, whether optimization is enabled, and current statistics such as total requests, tokens saved, and savings percentage.

```bash
curl http://localhost:8787/health
```

```json
{
  "status": "healthy",
  "optimize": true,
  "stats": {
    "total_requests": 42,
    "tokens_saved": 15000,
    "savings_percent": 45.2
  }
}
```

--------------------------------

### GET /stats-history with curl and CSV query

Source: https://docs.headroomlabs.ai/docs/proxy

Fetch durable history with hourly, daily, weekly, and monthly rollups. The second command requests CSV output for the weekly series. This endpoint powers the /dashboard view.

```bash
curl http://localhost:8787/stats-history
```

```bash
curl "http://localhost:8787/stats-history?format=csv&series=weekly"
```

--------------------------------

### validate_setup() (Python)

Source: https://docs.headroomlabs.ai/docs/api-reference

Validates client configuration. Returns a dict with 'valid' and per-component 'ok'/'error' statuses. Prints errors for components that are not ok.

```Python
result = client.validate_setup()
# Returns {"valid": bool, "provider": {...}, "storage": {...},
#          "config": {...}, "cache_optimizer": {...}}, each with "ok"/"error"
if not result["valid"]:
    for key in ("provider", "storage", "config", "cache_optimizer"):
        if not result[key]["ok"]:
            print(f"  - {key}: {result[key]['error']}")
```

--------------------------------

### GoogleProvider usage example

Source: https://docs.headroomlabs.ai/docs/api-reference

Shows how to instantiate GoogleProvider from the headroom.providers module.

```python
from headroom.providers import GoogleProvider

provider = GoogleProvider()
```

--------------------------------

### Install Headroom and Vercel AI SDK

Source: https://docs.headroomlabs.ai/docs/vercel-ai-sdk

Install the Headroom SDK, the Vercel AI SDK, and the OpenAI provider package.

```bash
npm install headroom-ai ai @ai-sdk/openai
```

--------------------------------

### Start OpenCode

Source: https://docs.headroomlabs.ai/docs/opencode-deepseek

Launches the OpenCode CLI. After starting, use /models to verify DeepSeek models appear under 'Headroom Proxy' and select one with /model deepseek-flash or /model deepseek-v4-pro.

```bash
opencode
```
Tokens:
Raw