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

> Effortlessly implement zero-code-change compression with Headroom proxy. Simply run headroom proxy and set the HEADROOM_BASE_URL environment variable to optimize your application's performance.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-18

---

**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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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**

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

   This command, documented in [`wiki/quickstart.md`](https://github.com/chopratejas/headroom/blob/main/wiki/quickstart.md), installs both the Headroom CLI and the proxy server dependencies required to run the standalone service.

2. **Start the proxy server**

   ```bash
   headroom proxy --mode token
   ```

   Alternatively, set the environment variable before launching:

   ```bash
   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`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/server.py), note the custom address for the next step.

4. **Configure client environment variables**

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

   ```

   As implemented in [`headroom/utils.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/wiki/proxy.md) | Complete reference for proxy flags, including `--mode` specifications and the `/v1/compress` endpoint documentation. |
| [`wiki/quickstart.md`](https://github.com/chopratejas/headroom/blob/main/wiki/quickstart.md) | Installation instructions for the proxy extra and quick-start examples. |
| [`wiki/typescript-sdk.md`](https://github.com/chopratejas/headroom/blob/main/wiki/typescript-sdk.md) | Details on how the TypeScript SDK resolves `HEADROOM_BASE_URL` and falls back to proxy defaults. |
| [`headroom/proxy/server.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/wiki/typescript-sdk.md) and implemented in [`headroom/utils.py`](https://github.com/chopratejas/headroom/blob/main/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.