# How to Configure Proxy Mode for Zero-Code-Change Compression in Headroom > Configure Headroom proxy mode for zero-code-change compression by running the standalone proxy server and setting the HEADROOM_BASE_URL environment variable. Seamlessly route all traffic. - Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom) - Tags: how-to-guide - Published: 2026-06-14 --- **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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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: ```bash pip install "headroom-ai[proxy]" ``` 2. **Launch the proxy** in your preferred mode. By default, the server listens on `http://localhost:8787`: ```bash headroom proxy --mode token ``` 3. **Configure the environment variable** to point your Headroom-aware tools at the proxy: ```bash export HEADROOM_BASE_URL=http://localhost:8787 ``` The TypeScript SDK ([`wiki/typescript-sdk.md`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/utils.py), which handles runtime environment parsing for `HEADROOM_BASE_URL` and other settings. The server implementation in [`headroom/proxy/server.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/server.py) and [`headroom/utils.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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.