Skip to content
BSWEN
Blog

How to Run Headroom as a Proxy for Zero-Code LLM Compression

Cowrie
Cowrie
Dev @ Bswen

Problem

I wanted token savings but could not afford to refactor our existing LLM integration. The codebase had dozens of places calling OpenAI directly. Changing all of them would take weeks and risk breaking something. I needed a drop-in solution that required zero code changes.

The Proxy Solution

Headroom’s proxy mode sits at the HTTP layer between your app and the LLM provider. You change one environment variable — the base URL — and everything else works exactly the same, but with compression applied automatically.

Installation

The proxy needs the optional proxy extra:

Install with proxy support
pip install "headroom-ai[proxy]"

If you skip the [proxy] extra, the headroom proxy command will not exist. I made this mistake once and got headroom: error: invalid choice: 'proxy'.

Starting the Proxy

Start proxy
headroom proxy --port 8787

This starts a local server on port 8787. It supports:

  • Anthropic /v1/messages
  • OpenAI /v1/chat/completions and /v1/responses
  • Google /v1internal:streamGenerateContent
  • Cloud backends: AWS Bedrock, Google Vertex AI, Azure OpenAI, OpenRouter

Pointing Your Client at the Proxy

Claude Code

Wrap Claude Code
headroom wrap claude

Or manually:

Manual Claude Code proxy
ANTHROPIC_BASE_URL=http://localhost:8787 claude

Cursor

Cursor proxy
OPENAI_BASE_URL=http://localhost:8787/v1 cursor

Codex or Aider

Wrap other agents
headroom wrap codex
headroom wrap aider

Custom Apps

Change your client’s base URL from https://api.openai.com to http://localhost:8787. Every request now flows through Headroom.

Monitoring

The proxy exposes useful endpoints:

Check live stats
curl http://localhost:8787/stats
# {"requests_total": 42, "tokens_saved_total": 125000, ...}
Prometheus metrics
curl http://localhost:8787/metrics

You also get budget controls:

Budget limit
headroom proxy --port 8787 --budget 10.00

This stops accepting requests after $10 of equivalent token spend.

Why This Matters

Teams can adopt Headroom in minutes without touching application code. The proxy also adds observability (/stats, /metrics) and budget controls that most apps lack. If your team uses Claude Code, Cursor, or any OpenAI-compatible client, this is the fastest path to production savings.

Summary

In this post, I showed how to run Headroom as a proxy for zero-code LLM compression. The key point is that one command and a base URL change gives automatic token optimization for any OpenAI-compatible client, with built-in stats and budget controls.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: