How to Use Headroom Proxy for Zero-Code-Change Compression

You can enable Headroom compression without modifying application code by running headroom proxy and setting the HEADROOM_BASE_URL environment variable to route requests through the standalone proxy server.

The Headroom proxy server provides a standalone HTTP service that executes the full compression pipeline—including SmartCrusher, ContentRouter, and CacheAligner—on incoming requests. By deploying this proxy from the chopratejas/headroom repository, you can implement advanced context compression across existing Headroom-aware tools simply by adjusting environment variables and endpoint URLs.

How Headroom Proxy Enables Zero-Code-Change Compression

The Proxy Server Architecture

The headroom proxy command launches a standalone HTTP service implemented in headroom/proxy/server.py using FastAPI/Gunicorn. This server exposes the compression pipeline as a network service, allowing any client that can make HTTP requests to benefit from token reduction without importing the Headroom library directly.

When running, the proxy listens on http://localhost:8787 by default and exposes the /v1/compress endpoint. All compression logic executes server-side; clients only need to POST their context to this endpoint and receive the optimized payload.

Available Compression Modes

The proxy supports two distinct operational modes selected via the --mode flag or the HEADROOM_MODE environment variable:

• token – Maximizes token reduction by dropping the lowest-scoring messages first. This mode provides the strongest compression and is ideal for reducing API costs in high-volume applications.
• cache – Freezes prior conversation turns and only adds new context, preserving historical messages while optimizing new additions.

According to wiki/proxy.md, you can configure this at runtime without touching configuration files or source code.

Step-by-Step Configuration Guide

Follow these steps to activate zero-code-change compression in your environment:

1. Install the proxy extra

   pip install "headroom-ai[proxy]"

   This command, documented in wiki/quickstart.md, installs both the Headroom CLI and the proxy server dependencies required to run the standalone service.

2. Start the proxy server

   headroom proxy --mode token

   Alternatively, set the environment variable before launching:

   export HEADROOM_MODE=token
   headroom proxy

   The token mode delivers the strongest compression results according to the proxy mode documentation.

3. Expose the proxy URL

   The default address is http://localhost:8787. If you configure a different host or port in headroom/proxy/server.py, note the custom address for the next step.

4. Configure client environment variables

   export HEADROOM_BASE_URL=http://localhost:8787
   export HEADROOM_MODE=token  # Optional: enforces token mode for downstream tools
   

   As implemented in headroom/utils.py, the SDKs and CLI wrappers read HEADROOM_BASE_URL to determine where to send compression requests. The TypeScript SDK documentation in wiki/typescript-sdk.md confirms this variable controls the endpoint resolution.

5. Run your existing application

   Execute your standard commands or scripts without modification. All Headroom-aware tools—including CLI wrappers (headroom wrap), the TypeScript SDK, and the Python SDK—automatically route traffic to the proxy's /v1/compress endpoint.

Why This Approach Requires No Code Changes

The Headroom proxy achieves zero-code-change integration through three architectural decisions:

• Process isolation – The proxy runs as a separate service, leaving your original application binary and source code untouched.
• Environment variable routing – The HEADROOM_BASE_URL variable acts as the sole integration point, universally supported by Headroom CLI wrappers and both official SDKs.
• Server-side processing – All compression occurs within the proxy; clients never invoke LLM compression logic directly, they simply POST to the compression-only endpoint.

This design means you can enable powerful token-saving compression across any Headroom-compatible client without writing a single line of application code.

Key Implementation Files

Understanding these source files helps troubleshoot advanced configurations:

File	Purpose
wiki/proxy.md	Complete reference for proxy flags, including --mode specifications and the /v1/compress endpoint documentation.
wiki/quickstart.md	Installation instructions for the proxy extra and quick-start examples.
wiki/typescript-sdk.md	Details on how the TypeScript SDK resolves HEADROOM_BASE_URL and falls back to proxy defaults.
headroom/proxy/server.py	FastAPI/Gunicorn server implementation that parses CLI arguments and environment variables, then forwards requests to the compression pipeline.
headroom/utils.py	Utility functions that resolve HEADROOM_BASE_URL and other runtime configuration variables.

Summary

• Headroom proxy provides standalone HTTP compression via headroom proxy, eliminating the need to import Headroom libraries into your application code.
• Zero-code-change integration relies on setting HEADROOM_BASE_URL to point clients at the proxy endpoint (http://localhost:8787 by default).
• Two compression modes are available: token for maximum token reduction and cache for preserving historical context.
• Installation requires only pip install "headroom-ai[proxy]" to access the proxy functionality.
• Configuration happens entirely through environment variables (HEADROOM_MODE, HEADROOM_BASE_URL) and CLI flags, with no source file modifications required.

Frequently Asked Questions

What is the default proxy URL for Headroom?

The Headroom proxy defaults to http://localhost:8787 when launched with headroom proxy. You can configure a custom address through server settings, but must update the HEADROOM_BASE_URL environment variable accordingly to ensure clients connect to the correct endpoint.

Which Headroom SDKs support the HEADROOM_BASE_URL environment variable?

Both the TypeScript SDK and Python SDK support HEADROOM_BASE_URL, as documented in wiki/typescript-sdk.md and implemented in headroom/utils.py. Additionally, the Headroom CLI wrappers (headroom wrap commands) automatically read this variable to determine compression endpoints.

What is the difference between token and cache modes in Headroom proxy?

Token mode drops the lowest-scoring messages first to maximize token reduction, providing the strongest compression for cost-sensitive applications. Cache mode freezes previous conversation turns and only compresses new context additions, preserving historical message integrity while optimizing new content. Select modes using the --mode CLI flag or HEADROOM_MODE environment variable.

Does the Headroom proxy require modifying my LLM client code?

No. The Headroom proxy operates as a standalone service that accepts HTTP requests at /v1/compress. Any client that can target a different API endpoint via environment variables—like those reading HEADROOM_BASE_URL—can use the proxy without code changes. The compression pipeline runs entirely server-side, so your existing application logic remains unchanged.

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