# How to Configure the Headroom Proxy for Zero-Code-Change Integration into Existing Applications

> Configure the Headroom proxy for zero-code-change integration into your LLM workflows. Set environment variables to point to the proxy, making integration seamless.

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

---

**You can integrate Headroom into any existing LLM workflow by setting environment variables like `OPENAI_BASE_URL` or `ANTHROPIC_BASE_URL` to point at the proxy address, requiring zero modifications to your application code.**

Headroom's proxy provides a transparent, drop-in HTTP server that intercepts LLM requests for compression and optimization. As implemented in `chopratejas/headroom`, this FastAPI-based service preserves the exact API contracts of OpenAI, Anthropic, and other providers, allowing you to route existing clients through the proxy using only environment-variable or command-line changes.

## Architecture Overview

The proxy architecture centers on [`headroom/proxy/server.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/server.py), which implements a FastAPI/Uvicorn service that receives standard LLM requests and processes them through the **IntelligentContextManager** pipeline. This includes the **SmartCrusher** and **ContentRouter** components before forwarding compressed payloads to the configured backend.

The [`headroom/proxy/runtime_env.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/runtime_env.py) module parses environment variables to determine routing targets, enabling the proxy to support multiple backends—including Anthropic, OpenAI, AWS Bedrock, Google Vertex AI, Azure OpenAI, and OpenRouter—without code changes in the client application.

## Installation and Basic Startup

Install the proxy component using pip with the proxy extra:

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

```

Start the server with default settings binding to `127.0.0.1:8787`:

```bash
headroom proxy

```

## Zero-Code Configuration Methods

The proxy enables integration through environment variable overrides that existing LLM clients already support.

### Environment Variable Overrides

Standard client libraries read base URL variables that you can redirect to the proxy:

- `OPENAI_BASE_URL` for OpenAI-compatible clients
- `ANTHROPIC_BASE_URL` for Anthropic clients  
- `BEDROCK_REGION` for AWS Bedrock routing

Example configuration for an existing OpenAI application:

```bash
export OPENAI_BASE_URL=http://localhost:8787/v1
export OPENAI_API_KEY=sk-your-key

# Run your existing application unchanged

python my_app.py

```

The app continues to use the standard `openai` Python SDK; the proxy intercepts `/v1/chat/completions` and compresses the payload transparently.

### CLI Tool Integration

Popular AI coding assistants support the same base URL environment variables. For Claude Code:

```bash
export ANTHROPIC_BASE_URL=http://localhost:8787
headroom proxy --backend anthropic

# In another terminal:

ANTHROPIC_BASE_URL=http://localhost:8787 claude

```

Claude Code communicates with the proxy as if it were the real Anthropic endpoint, allowing you to benefit from Headroom's compression without altering the tool's behavior.

### Docker Deployment

Deploy the proxy as a sidecar container using the configuration documented in [`wiki/proxy.md`](https://github.com/chopratejas/headroom/blob/main/wiki/proxy.md):

```bash
docker run -p 8787:8787 -e HEADROOM_BUDGET=100.0 python:3.11-slim \
  headroom proxy --host 0.0.0.0 --port 8787 --backend bedrock --region us-east-1

```

Your containerized application only needs to set its base URL to `http://localhost:8787` to route through the proxy.

## Backend Selection and Routing

The proxy determines the target provider through CLI flags or environment variables parsed in [`headroom/proxy/runtime_env.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/runtime_env.py). Use the `--backend` flag to specify the provider:

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

```

Available backends include `bedrock`, `vertex_ai`, `azure`, `openrouter`, and the default OpenAI/Anthropic endpoints. The proxy implements the same API surfaces as each provider, ensuring full compatibility with existing client libraries.

## Advanced Configuration Options

Tune proxy behavior using flags defined in [`headroom/proxy/modes.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/modes.py) and related modules:

- **Caching**: Control the semantic cache layer via `--no-cache` or enable it with `HEADROOM_CACHE_ENABLED`
- **Budgets**: Set token budgets with `--budget 50.0` to limit context window usage
- **Observability**: Enable OTEL metrics through `HEADROOM_OTEL_*` environment variables, exposing Prometheus-compatible metrics at `/metrics`
- **Modes**: Select `token` vs `cache` run modes using the `--mode` flag defined in [`headroom/proxy/modes.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/modes.py)

## Language-Specific Integration Patterns

### Python Applications

For Python scripts using the OpenAI SDK, redirect the base URL as shown in the environment variable section. The SDK continues to function unchanged while the proxy intercepts requests and applies compression via the **IntelligentContextManager**.

### Node.js and TypeScript

The TypeScript SDK provides a `compress()` function that communicates with the proxy's `POST /v1/compress` endpoint. Install via npm:

```bash
npm install headroom-ai

```

```typescript
import { compress } from "headroom-ai";

const msgs = [{ role: "user", content: "Large JSON payload..." }];
const { messages } = await compress(msgs, { model: "gpt-4o" });
// Use compressed messages with your existing OpenAI client

```

The SDK handles the HTTP call to the proxy, allowing your existing OpenAI client code to remain untouched.

### ASGI Middleware

For Python ASGI servers, mount the `CompressionMiddleware` to auto-compress incoming `/v1/*` requests as documented in [`wiki/integration-guide.md`](https://github.com/chopratejas/headroom/blob/main/wiki/integration-guide.md):

```python
from headroom.middleware import CompressionMiddleware

app.add_middleware(CompressionMiddleware)

```

This approach intercepts requests at the server level, requiring no changes to individual API client calls.

## Summary

- Headroom acts as a transparent proxy between your application and LLM providers, implemented in [`headroom/proxy/server.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/server.py)
- Configure integration using standard environment variables (`OPENAI_BASE_URL`, `ANTHROPIC_BASE_URL`) without code changes
- The proxy preserves exact API contracts while adding compression via the **IntelligentContextManager** pipeline
- Support multiple backends (Bedrock, Vertex AI, Azure) via the `--backend` flag and [`headroom/proxy/runtime_env.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/runtime_env.py) configuration
- Deploy using Docker or process managers like Gunicorn (`gunicorn headroom.proxy.server:app --workers 4`) for production workloads

## Frequently Asked Questions

### Does Headroom require modifying my existing LLM client code?

No. Headroom implements the same API surfaces as Anthropic, OpenAI, and other providers in [`headroom/proxy/server.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/server.py). You only need to change environment variables or base URL configurations that your client library already supports, such as `OPENAI_BASE_URL` or `ANTHROPIC_BASE_URL`.

### Which environment variables does the proxy recognize?

The proxy parses variables including `OPENAI_BASE_URL`, `ANTHROPIC_BASE_URL`, `BEDROCK_REGION`, `HEADROOM_HOST`, `HEADROOM_PORT`, and `HEADROOM_OTEL_*` for observability, as defined in [`headroom/proxy/runtime_env.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/runtime_env.py). These enable zero-code configuration across Python, Node.js, and CLI tools.

### Can I use Headroom with AWS Bedrock or Google Vertex AI?

Yes. Use the `--backend bedrock` or `--backend vertex_ai` flags when starting the proxy, along with region-specific options like `--region us-east-1` or `--region us-central1`. The proxy handles the translation to these proprietary APIs while presenting the standard OpenAI-compatible interface to your application.

### How does the compression middleware work with existing ASGI servers?

The `CompressionMiddleware` can be mounted in any Python ASGI application to automatically process `/v1/*` requests through Headroom's compression pipeline. This enables zero-code integration for web frameworks like FastAPI or Starlette, compressing requests before they reach your LLM client logic.