Files
headroom/docs/claude-code-bedrock-headroom.md
Devanshi Vyas 12c157966f fix(proxy): preserve Claude Code auto-mode protocol (#3784)
## Description

Fix Claude Code server-side auto-mode compatibility when requests pass
through
Headroom’s native Anthropic Messages endpoint.

Previously, auto-mode capability headers, safeguard payloads, query
parameters,
unknown response fields, or opaque SSE frames could be rewritten or lost
while
proxying and handling CCR continuations. This could trigger Claude
Code’s
client-side classifier fallback and its associated warning.

This change adds a request-local Anthropic wire envelope, preserves
client-owned
capability data and opaque response attachments, prevents classifier
payloads
from entering Headroom-owned observations, and documents that
schema-translating
Bedrock, Vertex, and LiteLLM routes do not currently support the
server-side
auto-mode protocol.


Closes #

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Preserve native Anthropic request paths and raw query parameters.
- Preserve client-owned `anthropic-version`, `anthropic-beta`, and
safeguard data.
- Avoid sticky-beta, memory, or turn-hook rewrites on classifier-bearing
turns.
- Preserve unknown Anthropic response fields across CCR continuations.
- Preserve opaque SSE frames through request-local parse/render
envelopes.
- Reject unknown or malformed deltas during strict buffered
reconstruction.
- Redact safeguard payloads from diagnostics and pipeline observations.
- Consolidate Anthropic SSE parsing and rendering into the wire module.
- Document auto-mode limitations for Bedrock, Vertex, and LiteLLM
translation paths.
- Add request, response, streaming, CCR, malformed-byte, and passthrough
regression tests.

## Testing

<!-- Check what you actually ran, then paste the real command output
below. -->

- [ ] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [ ] Manual testing performed

### Test Output


```text
$ python -m pytest -p no:cacheprovider \
    tests/test_anthropic_auto_mode_passthrough.py \
    tests/test_anthropic_buffered_sse.py \
    tests/test_ccr_response_handler_extra.py \
    tests/test_ccr_buffered_stream_signed_thinking.py \
    tests/test_proxy/test_anthropic_streaming_ccr_retrieve.py \
    tests/test_buffered_ccr_salvage.py \
    tests/test_buffered_ccr_accept_header.py \
    tests/test_proxy/test_anthropic_copilot_upstream_auth.py \
    tests/test_proxy_streaming_request_logger.py \
    tests/test_proxy_streaming_resilience.py -q

125 passed, 1 warning in 13.70s

$ ruff check --no-cache .
All checks passed!

$ ruff format --check --no-cache .
1559 files already formatted

$ python -m mypy \
    headroom/proxy/anthropic_wire.py \
    headroom/ccr/response_handler.py \
    headroom/proxy/handlers/anthropic.py \
    headroom/proxy/handlers/streaming.py

Success: no issues found in 4 source files

$ npx --no-install commitlint \
    --from origin/main --to HEAD \
    --config .commitlintrc.json

Exited successfully.
```

## Real Behavior Proof

- Environment: Pending. Record OS, Python version, Claude Code version,
provider/model, and Headroom revision.
- Exact command / steps: Pending. Start Headroom with `headroom proxy
--port 8787`, then run Claude Code with
`ANTHROPIC_BASE_URL=http://127.0.0.1:8787` and exercise server-side auto
mode.
- Observed result: Pending. Attach redacted output or logs showing the
request completed through Headroom and whether Claude Code used its
client-side fallback.
- Not tested: Live Claude Code auto mode against Anthropic; Bedrock,
Vertex, and LiteLLM translation routes.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: Native Anthropic safeguard-capable
requests.
- Kill switch / disable path: Set `CLAUDE_CODE_AUTO_MODE_SERVER=0` to
use Claude Code’s client-side fallback.
- Unsafe override required: No.
- Qualification impact: Live qualification is pending. Translation
routes remain documented as unsupported for server-side auto mode.
- Rollback path: Revert this PR or deploy the previous Headroom
revision.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code where needed
- [x] I have made corresponding documentation changes
- [x] No new warnings were observed in focused tests
- [x] I have added tests for the fix
- [ ] Full existing and new unit test suite passes locally
- [x] I did **not** edit `CHANGELOG.md`

## Screenshots (if applicable)

N/A. This change affects proxy wire behavior.
2026-09-25 09:53:27 -07:00

6.0 KiB

Claude Code + AWS Bedrock, with Headroom compression

Validated end-to-end on 2026-06-26 (Claude Code 2.1, Headroom 0.27.0, ap-southeast-2).

This is the working, tested way to run Claude Code against Claude models on AWS Bedrock with Headroom compressing the context in the middle.

TL;DR

Run Claude Code in normal Anthropic mode (NOT Bedrock mode) pointed at a local Headroom proxy, and let Headroom be the thing that talks to Bedrock:

Claude Code  ──ANTHROPIC_BASE_URL──▶  Headroom proxy  ──LiteLLM (bedrock)──▶  AWS Bedrock
 (normal mode)     (plain http)        (compresses)         (your AWS creds)      (Claude)

One non-obvious requirement makes the difference between "works" and "silently bypasses the proxy":

  1. CLAUDE_CODE_USE_BEDROCK=0 — Without this, Claude Code sees the CLAUDE_CODE_USE_BEDROCK=1 flag and calls Bedrock directly via the AWS SDK, completely bypassing ANTHROPIC_BASE_URL and the proxy.

Why not "just set CLAUDE_CODE_USE_BEDROCK=1"?

That approach does not work with Headroom. When CLAUDE_CODE_USE_BEDROCK=1 is set, Claude Code calls Bedrock directly using the AWS SDK — ANTHROPIC_BASE_URL is ignored entirely and the proxy never receives a byte. Use the Anthropic-mode path below.

Prerequisites

  • AWS credentials configured for your environment (env vars, ~/.aws/credentials, instance profile, or SSO via aws sso login). Confirm direct access works before involving Headroom:
    aws bedrock-runtime invoke-model \
      --region us-east-1 \
      --model-id anthropic.claude-3-haiku-20240307-v1:0 \
      --body '{"anthropic_version":"bedrock-2023-05-31","max_tokens":20,"messages":[{"role":"user","content":"hi"}]}' \
      /tmp/out.json
    
  • boto3 in the proxy's Python environment (for dynamic inference profile discovery):
    pip install boto3
    
  • IAM permissions for the models you intend to use — at minimum bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream. For application inference profiles, scope to the specific profile ARN:
    {
      "Effect": "Allow",
      "Action": ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"],
      "Resource": ["arn:aws:bedrock:<region>:<account>:application-inference-profile/<id>"]
    }
    

Terminal 1 — start the Headroom proxy (Bedrock backend)

headroom proxy --port 8787 \
  --backend bedrock \
  --region us-east-1

With a named AWS SSO profile:

headroom proxy --port 8787 \
  --backend bedrock \
  --region us-east-1 \
  --bedrock-profile my-sso-profile

On startup the proxy calls list_inference_profiles to build a model map. Confirm it is routing correctly by checking the LiteLLM log lines — you should see:

LiteLLM completion() model= converse/arn:aws:... provider = bedrock

Terminal 2 — run Claude Code (normal Anthropic mode) against the proxy

export CLAUDE_CODE_USE_BEDROCK=0               # REQUIRED — prevents Claude Code bypassing the proxy
export ANTHROPIC_BASE_URL=http://127.0.0.1:8787
export ANTHROPIC_API_KEY=headroom              # Claude Code needs *a* key to start; value is ignored
export ANTHROPIC_MODEL=claude-opus-4-6
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001

claude

Or via ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "0",
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8787",
    "ANTHROPIC_API_KEY": "headroom",
    "ANTHROPIC_MODEL": "claude-opus-4-6",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001"
  }
}

Claude Code now talks plain Anthropic /v1/messages to Headroom; Headroom compresses and forwards to Bedrock via LiteLLM, then translates the answer back.

This translating route is not currently compatible with Claude Code's server-side auto-mode classifier protocol. Ordinary model traffic remains fail-open, but classifier-bearing turns may use Claude Code's billable client-side fallback. Use native Anthropic transport for server-side auto mode, or set CLAUDE_CODE_AUTO_MODE_SERVER=0 when the fallback is intentional.

Application inference profiles (account-specific ARNs)

If your IAM policy only permits application inference profiles (account-specific ARNs) rather than system-defined cross-region profiles, pass the ARN directly as the model value in ANTHROPIC_DEFAULT_*_MODEL. The proxy detects arn:aws: prefixed model IDs and routes them via bedrock/converse/<arn> automatically — no extra configuration required.

Region prefix notes

AWS region Cross-region inference prefix
us-* us.
eu-* eu.
ap-* (except ap-southeast-2) apac.
ap-southeast-2 (Sydney) au.

The proxy uses the correct prefix automatically when constructing fallback model IDs.

Verify compression is happening

  • Dashboard: http://localhost:8787/dashboard — "tokens saved" climbs as you work.
  • curl -s localhost:8787/stats → tokens.saved and request_logs[].transforms_applied.

Troubleshooting

Symptom Cause Fix
Proxy receives no requests Claude Code is in Bedrock mode, bypassing proxy Set CLAUDE_CODE_USE_BEDROCK=0
400 The provided model identifier is invalid Bedrock rejected the model name format Use standard cross-region profile names (claude-sonnet-4-6) or a valid application inference profile ARN
403 AccessDeniedException on system-defined profiles IAM policy only permits application profiles Use --bedrock-profile with an authorized profile and pass application inference profile ARNs as model values
400 … Try calling via converse route Old proxy version routing ARNs to invoke path Upgrade to headroom ≥ 0.27.1
Model map empty at startup boto3 not installed or wrong AWS profile pip install boto3; check --bedrock-profile / AWS_PROFILE