How to Configure Headroom for OpenAI API: Complete Setup Guide

To configure Headroom for OpenAI API, instantiate a HeadroomClient with an OpenAI() client and OpenAIProvider(), set the OPENAI_API_KEY environment variable, and select between audit (observe) or optimize (transform) mode to enable intelligent caching and compression.

Headroom wraps the OpenAI SDK to add compression, intelligent context management, and provider-specific optimizations. Configuring this integration requires setting up credentials, instantiating the correct provider classes from headroom/providers/openai.py, and optionally tuning model-specific limits. This guide covers the exact configuration steps using the chopratejas/headroom source code.

Prerequisites: OpenAI API Key Authentication

Headroom never stores API keys in the repository. Instead, it relies on the underlying openai library to read credentials from the environment. Export your key before initializing any client.

export OPENAI_API_KEY=sk-...

The SDK and proxy will automatically detect this variable when making requests to OpenAI's endpoints.

Configure Headroom SDK for OpenAI (Python)

Instantiate HeadroomClient with OpenAIProvider

Create an OpenAI-enabled client by passing an OpenAI() instance as the original_client and an OpenAIProvider() to unlock provider-specific features. According to the implementation in headroom/providers/openai.py, the provider handles token counting, model limit resolution, and OpenAI-specific flags like prefix caching.

from headroom import HeadroomClient, OpenAIProvider
from openai import OpenAI

client = HeadroomClient(
    original_client=OpenAI(),
    provider=OpenAIProvider(),
    default_mode="optimize"  # Use "audit" to observe without transforms

)

# Make a request with automatic compression and caching

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Explain quantum tunneling in simple terms."}]
)
print(response.choices[0].message.content)

Enable OpenAI Prefix Caching

Set enable_cache_optimizer=True when constructing OpenAIProvider to leverage OpenAI's prefix caching feature. This optimization reuses system prompts across calls, significantly reducing token costs for repetitive contexts.

provider = OpenAIProvider(enable_cache_optimizer=True)

Customize Model Context Limits

Headroom respects OpenAI's default limits (e.g., gpt-4o: 128000 tokens), but you can override these via three methods. The resolution order is documented in lines 80-90 of headroom/providers/openai.py:

1. Pass a context_limits dictionary to the OpenAIProvider constructor
2. Set the HEADROOM_MODEL_LIMITS environment variable (JSON string or path to a file)
3. Add entries to ~/.headroom/models.json

# Override via constructor

provider = OpenAIProvider(
    context_limits={"gpt-4o-mini": 128000, "custom-model": 32000}
)

Configure Headroom Proxy for OpenAI

If running the Headroom proxy instead of embedding the SDK, pass --provider openai (or rely on the default) and optionally specify a custom endpoint with --openai-api-url.

headroom proxy \
  --port 8787 \
  --host 0.0.0.0 \
  --provider openai \
  --openai-api-url https://api.openai.com

The proxy intercepts requests, applies transforms based on your configured mode, and forwards them to OpenAI's API.

TypeScript SDK Configuration

The TypeScript client connects through the Headroom proxy or directly by reading environment variables. Set HEADROOM_BASE_URL and HEADROOM_API_KEY before importing the client.

process.env.HEADROOM_BASE_URL = "http://localhost:8787";
process.env.HEADROOM_API_KEY = "your-headroom-key";

import { HeadroomClient } from "headroom-ai";

const client = new HeadroomClient();

await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content": "What is the speed of light?" }]
});

Summary

• Authentication: Set OPENAI_API_KEY as an environment variable; Headroom never stores keys in source files.
• Python SDK: Combine HeadroomClient with OpenAIProvider from headroom/providers/openai.py to enable provider-specific transforms.
• Optimization: Enable enable_cache_optimizer for OpenAI prefix caching and override model limits via the constructor, HEADROOM_MODEL_LIMITS environment variable, or ~/.headroom/models.json.
• Proxy Mode: Use CLI flags --provider openai and --openai-api-url to route traffic through Headroom's HTTP proxy.
• Operation Modes: Choose audit to observe token usage without changes, or optimize (default) to apply compression and intelligent caching.

Frequently Asked Questions

How does Headroom handle OpenAI API credentials?

Headroom delegates credential management to the official openai library. Set the OPENAI_API_KEY environment variable before runtime. The key is read dynamically and never committed to the repository or stored in Headroom's configuration objects.

What is the difference between audit and optimize mode?

audit mode logs requests and analyzes token usage without modifying traffic, useful for evaluating costs before enabling transforms. optimize mode activates Headroom's full feature set including request compression, context window management, and prefix caching to minimize API spend.

Where are model context limits resolved in the source code?

Model limit resolution logic resides in headroom/providers/openai.py between lines 80-90. The provider checks for overrides in this priority order: constructor context_limits parameter, HEADROOM_MODEL_LIMITS environment variable, and ~/.headroom/models.json, falling back to built-in defaults for known OpenAI models.

Can I use a custom OpenAI API endpoint or reverse proxy?

Yes. When running the Headroom proxy, pass --openai-api-url https://your-endpoint.com to override the default https://api.openai.com base URL. For the Python SDK, instantiate the underlying OpenAI client with a custom base_url before passing it to HeadroomClient.

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