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

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, 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 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:

pip install "headroom-ai[proxy]"

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

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:

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:

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:

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. Use the --backend flag to specify the provider:

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 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

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:

npm install headroom-ai

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:

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
• 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 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. 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. 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.

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