Claude Code on Vertex AI

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

What you get

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

Before you start

You should already have Claude Code working against Vertex without Headroom. That means these are set in your shell:

export CLAUDE_CODE_USE_VERTEX=1
export ANTHROPIC_VERTEX_PROJECT_ID=<your-gcp-project>
export CLOUD_ML_REGION=us-east5          # your Vertex region (or "global")
gcloud auth application-default login    # or set GOOGLE_APPLICATION_CREDENTIALS

No ANTHROPIC_API_KEY is needed — Vertex mode uses your Google login.

Run it (one command)

pip install headroom-ai
headroom wrap claude

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

1. starts the Headroom proxy,
2. points Claude Code's Vertex endpoint at it (ANTHROPIC_VERTEX_BASE_URL),
3. leaves your project, region, and Google login untouched.

You'll see a line like:

Vertex mode: ANTHROPIC_VERTEX_BASE_URL=http://127.0.0.1:8787
  → compress, then forward to Vertex with your GCP ADC token

Use Claude Code exactly as you normally would.

How it works

Claude Code ──(Vertex request)──▶ Headroom ──(compressed)──▶ Vertex AI (Claude)
   in Vertex mode                  compresses                 your project + region
   (your ADC token) ───────────── passed through ───────────▶ authenticates you

Claude Code sends its normal Vertex …:rawPredict / :streamRawPredict request to Headroom. Headroom compresses the messages (keeping the Vertex request shape intact), then forwards to the correct regional Vertex host — derived from the request itself, so multi-region and global both work — using the Google token Claude Code already attached.

Check that compression is working

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

If "tokens saved" stays at 0 on large prompts, see Troubleshooting below.

Troubleshooting

• It still goes straight to Google (no savings). Make sure CLAUDE_CODE_USE_VERTEX=1 is exported in the same shell before headroom wrap claude. The wrapper only switches to Vertex mode when it sees that variable.
• Wrong region / 404 from Vertex. Confirm CLOUD_ML_REGION matches a region where your Claude model is enabled. global is supported and maps to the non-regional host.
• Auth errors. Headroom forwards your token as-is — if gcloud auth application-default login (or GOOGLE_APPLICATION_CREDENTIALS) works for Claude Code without Headroom, it works with it.

Alternative: let Headroom talk to Vertex for you

If you'd rather not run Claude Code in Vertex mode, you can have Headroom be the translator instead: Claude Code speaks plain Anthropic to Headroom, and Headroom calls Vertex on your behalf.

export HEADROOM_BACKEND=litellm-vertex_ai     # note the _ai suffix
export HEADROOM_REGION=us-east5
export VERTEXAI_PROJECT=<your-gcp-project>
export GOOGLE_APPLICATION_CREDENTIALS=/path/sa.json   # or gcloud ADC
export ANTHROPIC_API_KEY=placeholder          # Claude Code needs *a* key to start
headroom wrap claude --backend litellm-vertex_ai --region us-east5

The native Vertex-mode flow above is recommended — it keeps your existing GCP auth and has the smallest moving parts. Use this alternative only if you can't set CLAUDE_CODE_USE_VERTEX.

Notes

• Pick a Claude model that is enabled in your Vertex project/region (e.g. claude-sonnet-4-6, claude-haiku-4-5).
• Streaming, tool use, and prompt caching all work through Headroom.
• Want to point at a private Vertex gateway instead of Google's host? Start the proxy with --vertex-api-url https://your-gateway and Headroom will forward there.