How to Configure Proxy Mode for Zero-Code-Change Compression in Headroom

Run Headroom's standalone proxy server with --mode token or --mode cache and set the HEADROOM_BASE_URL environment variable to route all compression traffic through the proxy without modifying your application code.

Headroom's proxy architecture enables full-pipeline context compression for any Headroom-compatible client without requiring source code modifications. By deploying the standalone proxy and configuring runtime environment variables, you can achieve zero-code-change compression across Python applications, TypeScript services, and CLI workflows in the chopratejas/headroom repository.

Understanding Headroom's Proxy Architecture

The proxy operates as a standalone HTTP service that executes the complete compression pipeline externally, keeping your application binary untouched.

The Standalone Proxy Server

The headroom proxy command launches a FastAPI server (implemented in headroom/proxy/server.py) that intercepts compression requests and processes them through the SmartCrusher, ContentRouter, and CacheAligner components. Because the proxy runs as a separate process, your original application remains unmodified while still benefiting from advanced token reduction strategies.

Compression Pipeline Execution

When running in proxy mode, the server handles POST /v1/compress requests (documented in wiki/proxy.md at line 277) and returns compressed payloads. The client never invokes an LLM directly; instead, it communicates with the proxy endpoint, which performs all compression server-side.

Configuring Proxy Mode Settings

Headroom supports two distinct operational modes selected via the --mode flag or HEADROOM_MODE environment variable (see wiki/proxy.md line 71).

Token Mode vs Cache Mode

Token mode (--mode token) maximizes token reduction by dropping the lowest-scoring messages first, making it ideal for aggressive context optimization.

Cache mode (--mode cache) freezes prior conversation turns and only adds new context, preserving historical message structure while managing growth.

Environment Variables vs Command-Line Flags

You can configure the mode using either method:

• Command-line: headroom proxy --mode token
• Environment variable: export HEADROOM_MODE=token

Zero-Code-Change Integration Steps

Follow these steps to enable compression without touching application source code.

1. Install the proxy extra to obtain the CLI and server dependencies:

pip install "headroom-ai[proxy]"

2. Launch the proxy in your preferred mode. By default, the server listens on http://localhost:8787:

headroom proxy --mode token

3. Configure the environment variable to point your Headroom-aware tools at the proxy:

export HEADROOM_BASE_URL=http://localhost:8787

The TypeScript SDK (wiki/typescript-sdk.md line 58), Python SDK, and CLI wrappers automatically read this variable to determine request routing.

4. Run your application normally. All compression traffic now routes through the proxy's /v1/compress endpoint without requiring code changes.

Technical Implementation Details

The configuration resolution logic resides in headroom/utils.py, which handles runtime environment parsing for HEADROOM_BASE_URL and other settings. The server implementation in headroom/proxy/server.py parses the --mode argument and environment variables, then forwards requests to the appropriate compression pipeline.

Summary

• Headroom's proxy mode enables zero-code-change compression by running as a standalone HTTP service.
• Select between token mode (aggressive reduction) and cache mode (context preservation) using --mode or HEADROOM_MODE.
• Set HEADROOM_BASE_URL to http://localhost:8787 (or your custom proxy address) to route clients through the compression pipeline.
• Install via pip install "headroom-ai[proxy]" and launch with headroom proxy.
• Source files headroom/proxy/server.py and headroom/utils.py handle the server logic and configuration resolution.

Frequently Asked Questions

What is the default port for the Headroom proxy server?

The proxy server defaults to port 8787, accessible at http://localhost:8787. You can configure a different address by setting the appropriate host and port flags when launching the proxy.

Do I need to modify my application's import statements to use proxy mode?

No. Zero-code-change compression works through environment variables alone. As long as your Headroom-aware clients read HEADROOM_BASE_URL (which the TypeScript SDK, Python SDK, and CLI wrappers do automatically), they will route requests to the proxy without requiring import modifications or code changes.

Can I switch between token and cache mode without restarting the proxy?

No. The mode is determined at startup through the --mode flag or HEADROOM_MODE environment variable parsed in headroom/proxy/server.py. To change modes, you must restart the proxy process with the new configuration.

Does the proxy mode support compression-only endpoints?

Yes. The proxy exposes POST /v1/compress as a compression-only endpoint that processes requests through the full pipeline (SmartCrusher, ContentRouter, CacheAligner) without invoking external LLMs, making it suitable for pure compression workflows.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}