Claude Code on Azure AI Foundry

If your Claude models live on Azure AI Foundry, you can still get Headroom's prompt compression. Headroom sits between Claude Code and Azure: it shrinks the big stuff in each request (file reads, logs, tool output) and forwards the rest to Azure using your own Azure credentials. You keep your Azure setup; Headroom just makes each call cheaper.

What you get

• Fewer input tokens on every Claude Code request to Azure AI Foundry (often 30–60% on agent workloads), so you pay for less.
• Same answers — compression is reversible and content-aware.
• No new secrets — Headroom never holds your Azure credentials. Claude Code keeps authenticating to Azure AI Foundry with its own api-key or Entra Bearer token; Headroom passes it through.

Before you start

You should already have Claude Code working against Azure AI Foundry without Headroom. That means these are set in your shell (or your ~/.claude/settings.json env block):

export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=<your-azure-resource-name>
# e.g. ANTHROPIC_FOUNDRY_RESOURCE=my-org-claude

No ANTHROPIC_API_KEY is needed — Foundry mode uses your Azure credentials.

Run it (one command)

pip install headroom-ai
headroom wrap claude

That's it. Because CLAUDE_CODE_USE_FOUNDRY=1 is set, headroom wrap claude automatically:

1. derives your Azure AI Foundry endpoint from ANTHROPIC_FOUNDRY_RESOURCE,
2. starts the Headroom proxy with that endpoint as the upstream,
3. points Claude Code's Foundry endpoint at the proxy (ANTHROPIC_FOUNDRY_BASE_URL),
4. leaves your Azure resource, model, and credentials untouched.

You'll see a line like:

Foundry mode: ANTHROPIC_FOUNDRY_BASE_URL=http://127.0.0.1:8787/anthropic
  → upstream https://my-org-claude.services.ai.azure.com/anthropic

Use Claude Code exactly as you normally would.

How it works

Claude Code ──(Foundry request)──▶ Headroom ──(compressed)──▶ Azure AI Foundry (Claude)
   in Foundry mode                  compresses                 your resource
   (your api-key / Entra) ──────── passed through ───────────▶ authenticates you

Claude Code sends its Foundry request (Anthropic API format) to Headroom. Headroom compresses the messages, then forwards to your Azure AI Foundry resource endpoint — https://{ANTHROPIC_FOUNDRY_RESOURCE}.services.ai.azure.com/anthropic — with your auth headers passed through unchanged.

If you have ANTHROPIC_FOUNDRY_BASE_URL set explicitly

If your environment already has ANTHROPIC_FOUNDRY_BASE_URL set to the full Azure endpoint URL, Headroom uses it directly and ANTHROPIC_FOUNDRY_RESOURCE is not needed. Either configuration works.

Check that compression is working

1. Open the dashboard: http://localhost:8787/dashboard. "Tokens saved" should climb as you use Claude Code.
2. Or check response headers: x-headroom-tokens-before, x-headroom-tokens-after, x-headroom-tokens-saved.

Troubleshooting

Headroom says "ANTHROPIC_BASE_URL" instead of "Foundry mode"

CLAUDE_CODE_USE_FOUNDRY is not set in the shell where you ran headroom wrap claude. Make sure to export it before running, or set it in your shell profile.

Claude Code fails with a 401 / auth error

Your Azure credentials are not being forwarded correctly. Verify that Claude Code works against Azure AI Foundry directly (without Headroom) before wrapping. If it works direct but not through Headroom, open an issue with the proxy log.

"tokens saved" is always 0

Check the dashboard — if requests are flowing but savings are 0, content may be below the compression threshold or the Rust extension may not be installed (pip install "headroom-ai[proxy]" includes it).