Files
headroom/examples/README.md
brcebnandJD Davis 9624d40d5e docs(claude): keep Remote Control behind Headroom via an HTTPS_PROXY route (#1779) (#4575)
## Description

Claude Code v2.1.196+ disables Remote Control (`/remote-control`, `/rc`:
a local session mirrored to claude.ai/code and the Claude mobile apps)
whenever `ANTHROPIC_BASE_URL` names a host other than
`api.anthropic.com`. The check is client-side and compares the host
only, so every standard Headroom setup
(`ANTHROPIC_BASE_URL=http://127.0.0.1:8787`) loses Remote Control, and
the only documented fix so far is "run Claude without Headroom for those
sessions".

The troubleshooting page already named the route that remains: leave
`ANTHROPIC_BASE_URL` unset and reach Headroom through an `HTTPS_PROXY`
front end with a local CA trusted through `NODE_EXTRA_CA_CERTS` (the
enterprise proxy path Claude Code supports). It was left as an open item
on #1779. This PR ships that route, tested end to end with a real Claude
Code session steered from the Claude iOS app while every request went
through Headroom.

How it works:

```text
Claude Code --HTTPS_PROXY--> mitmdump 127.0.0.1:8790
    api.anthropic.com  /v1/messages*  -> Headroom 127.0.0.1:8787 -> api.anthropic.com
    api.anthropic.com  other paths    -> api.anthropic.com (unchanged)
    any other host (claude.ai, OAuth) -> raw CONNECT tunnel, never decrypted
```

- `ANTHROPIC_BASE_URL` is unset, so the gate passes and subscription
auth is untouched.
- mitmproxy decrypts `api.anthropic.com` only (`--allow-hosts`). The
Remote Control bridge (`claude.ai`) is never decrypted.
- Only the Messages API goes to Headroom. Feature flags, telemetry and
the rest of the API keep going straight to Anthropic.

One trap found while setting it up, and handled here: the Headroom proxy
is often started by the `headroom init hook ensure` hook, so it inherits
Claude Code's environment (the running proxy had `CLAUDECODE=1`). Its
httpx client honours `HTTPS_PROXY`, so its upstream calls would come
back through mitmproxy and loop. The docs tell users to prefix the hook
with `env -u HTTPS_PROXY -u HTTP_PROXY -u NODE_EXTRA_CA_CERTS`. As a
second guard, the addon marks the requests it redirects
(`x-rc-proxy-hop`) and sends a marked request straight to Anthropic. The
marker deliberately avoids the `x-headroom-` prefix: Headroom strips
those headers before forwarding upstream (`_strip_internal_headers`),
which would erase the marker. My first local version used
`x-headroom-rc` and the new test catches exactly that.

Refs #1779

## Type of Change

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

## Changes Made

- `examples/claude_code_remote_control/route_to_headroom.py`: the
mitmproxy addon (redirect `/v1/messages*` to Headroom, loop guard, SSE
streaming, `HEADROOM_RC_UPSTREAM` override). mitmproxy is imported only
for type checking, so it is not a Headroom dependency.
- `examples/claude_code_remote_control/README.md`: setup (macOS /
Linux), Claude Code settings, starting Headroom without the proxy
variables, verification, caveats, rollback.
- `docs/content/docs/troubleshooting.mdx`: the Remote Control section
offers this route next to "launch Claude without Headroom", and the
"What remains" paragraph now points to it.
- `examples/README.md`: index entry.
- `tests/test_issue_1779_https_proxy_route.py`: routing rules pinned
with stand-in flow objects.

No Headroom runtime code changes, no new dependency.

## Testing

- [x] Unit tests pass (`pytest`) — the new file plus the existing #1779
gate tests
- [x] Linting passes (`ruff check .`) — on the changed Python files,
ruff 0.17.0 (the pinned version)
- [ ] Type checking passes (`mypy headroom`) — N/A, no change under
`headroom/`
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ python -m pytest -q tests/test_issue_1779_https_proxy_route.py tests/test_issue_1779_remote_control_gate.py
64 passed in 0.77s

# Loop-guard test with the marker renamed to x-headroom-rc (proves it catches the trap):
FAILED tests/test_issue_1779_https_proxy_route.py::test_hop_marker_survives_headroom_header_stripping
1 failed, 9 passed

$ ruff check <changed files> && ruff format --check <changed files>
All checks passed!
```

Smoke test of the addon in a real `mitmdump` (12.3.1) with Headroom
running on 8787:

```text
POST https://api.anthropic.com/v1/messages  -> "server connect 127.0.0.1:8787", "Streaming response from 127.0.0.1"
GET  https://api.anthropic.com/v1/models    -> "server connect api.anthropic.com:443" (not redirected)
GET  https://claude.ai/ (no custom CA given) -> TLS handshake succeeds, i.e. tunnelled, not intercepted
```

## Real Behavior Proof

- Environment: macOS (Darwin 27), Claude Code 2.1.312 (native install,
claude.ai Max subscription), Headroom 0.37.0 (`headroom proxy --mode
token --backend anthropic`, started by the `headroom init hook ensure`
hooks), mitmproxy 12.3.1 run as a LaunchAgent.
- Exact command / steps: `~/.claude/settings.json` `env` =
`HTTPS_PROXY=http://127.0.0.1:8790`, `NO_PROXY=localhost,127.0.0.1,::1`,
`NODE_EXTRA_CA_CERTS=~/.mitmproxy/mitmproxy-ca-cert.pem`,
`ANTHROPIC_BASE_URL` removed, `remoteControlAtStartup: true`, both
headroom hook commands prefixed with `env -u HTTPS_PROXY -u HTTP_PROXY
-u NODE_EXTRA_CA_CERTS`. Started a new `claude` session.
- Observed result: `/status` shows the proxy; answers stream normally;
the mitmdump log shows one `127.0.0.1:8787` request per turn and no
repeats; the session shows up in the Claude iOS app (Code tab) and
answers messages sent from the phone; Headroom's savings keep counting
those requests.
- Not tested: Linux and Windows (the README gives the Linux equivalent
but it was not run), the VS Code extension and Claude Desktop sessions,
`headroom wrap claude` (which sets `ANTHROPIC_BASE_URL` itself, so it is
not compatible with this route).

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: N/A
- Stable/default behavior changed: no, opt-in recipe; nothing changes
for existing users
- Kill switch / disable path: restore `ANTHROPIC_BASE_URL`, remove the
three variables, stop mitmdump
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert the commit (docs, example and test only)

## Review Readiness

- [x] I performed a self-review
- [ ] 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, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md`

## Additional Notes

- Possible follow-up, not in this PR: `remote_control_gate_message` /
`remote_control_gate_short_message` still only suggest running Claude
without Headroom. They could link to this section. I left them untouched
to keep this PR docs-only and avoid changing strings the #1779 / #3426
tests pin.
- Security trade-off, stated in the README: the user trusts a locally
generated CA for `api.anthropic.com` only; the CA key stays on the
machine (`~/.mitmproxy`). Everything else is tunnelled.


### Maintainer current-main requalification

Exact head `b9d7a8a9e72a87ebdc69e1cbcb9e00df3265a22a`, upstream main
`e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`.

Mechanically updated from current upstream main. The addon, host/path
selection, hop-loop guard, header handling and streaming behavior are
unchanged. The maintainer documentation fix addresses the new Devin
note: remove ANTHROPIC_BASE_URL from all active settings scopes,
explicitly including project .claude/settings.json and
.claude/settings.local.json, while retaining other entries/hooks. Source
inspection confirms project-scoped headroom init claude writes the
variable to settings.local.json, so removing only the user/shell setting
is insufficient. The setup and caveat now cover that case.

Both issue-1779 suites pass (64 tests), plus ten shared Gemini fixture
cases after the test-only repair for independently verified main
failures. Changed Python Ruff/format and whitespace checks pass. No new
runtime dependency or contributor routing logic was introduced. The
author's existing macOS/native Claude/Remote Control/mitmproxy
end-to-end evidence and exclusions were read; these independent Windows
checks cover routing contracts and documentation accuracy, not a live
macOS/Linux/Windows Remote Control session or a fresh native build.
Author readiness attestations remain unchanged; nothing merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.


### Maintainer current-main requalification

Exact head `c5e1ea2afcbd7e4c91a75869706c6f68f08f7e3a`, upstream main
`c01cf07d943d816cfd9d97e6838ed4e38f1ff9a4`.

Final main synchronization with upstream
c01cf07d94 after all six Dependabot
merges. The example addon and routing/gate test inputs are unchanged
from the previously approved branch; reviewed the additive
troubleshooting documentation overlap. Actual isolated Click8.5.0 and
the fresh combined native DLL:20 HTTPS-proxy-route/Gemini tests plus57
Remote Control gate tests pass; Ruff and whitespace pass. Initial gate
setup errors were caused by C: temp-drive exhaustion; isolated workspace
temp on G: passes with no source workaround or weakened assertion.
Existing scoped macOS/native Claude Remote Control proof remains
applicable to the unchanged addon; no fresh Windows
live-Remote-Control/provider claim. No contributor settings policy
rewritten or readiness attestations changed. No new source finding;
final approval awaits exact-head hosted qualification. Nothing merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.


### Maintainer current-main requalification

Exact head `5400c2c4fd86922f8e2f76d2752c9a5e1bdbe6f3`, upstream main
`2b0315b2d4b0d54947050bbdad2de9e89df06378`.

Requalified against upstream main
2b0315b2d4. All 71 integration patches
match the main delta after diff-location normalization. The HTTPS-proxy
addon and Remote Control route/gate inputs are byte-identical to the
preceding reviewed head. The docs explicitly cover user, project and
project-local settings, preserving other environment entries and hooks;
this addresses the prior Devin project-scope finding.

All 208 HTTPS-route, Remote Control gate, Gemini and doctor tests pass
using isolated temporary storage on G:. Ruff lint/format passes for all
33 changed Python files; offline lock and whitespace checks pass. The
existing native DLL matches its recorded build inputs and checksum; no
fresh build is claimed. Earlier scoped macOS/native Claude Remote
Control evidence remains applicable to the unchanged addon. No fresh
Windows live Remote Control, cloud/provider or mobile-client
qualification is claimed. Current author and Devin discussion
considered; no new blocker found. Exact-head hosted qualification is
pending before approval. Maintainers handle CI; nothing merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-11-11 09:54:43 -06:00

229 lines
5.5 KiB
Markdown

# Headroom Examples
This directory contains examples demonstrating Headroom's capabilities.
## Quick Start Examples
### basic_usage.py
Basic integration with OpenAI client:
```bash
export OPENAI_API_KEY='your-key'
python examples/basic_usage.py
```
### anthropic_example.py
Integration with Anthropic Claude:
```bash
export ANTHROPIC_API_KEY='your-key'
python examples/anthropic_example.py
```
### streaming_example.py
Streaming responses with optimization:
```bash
export OPENAI_API_KEY='your-key'
python examples/streaming_example.py
```
### tabular_compression_demo.py
Tabular + spreadsheet compression on generated sample data (no API key needed).
Shows where CSV/markdown tables and `.xlsx` workbooks compress and where compact,
all-unique data correctly passes through:
```bash
python examples/tabular_compression_demo.py # run all scenarios
python examples/tabular_compression_demo.py --write DIR # also save the sample files
```
## Evaluation Examples
### smart_vs_naive_eval.py
Compare SmartCrusher against naive truncation:
```bash
export OPENAI_API_KEY='your-key'
python examples/smart_vs_naive_eval.py
```
### real_world_eval.py
Comprehensive evaluation with Anthropic models:
```bash
export ANTHROPIC_API_KEY='your-key'
python examples/real_world_eval.py
```
### real_world_openai_eval.py
Comprehensive evaluation with OpenAI models:
```bash
export OPENAI_API_KEY='your-key'
python examples/real_world_openai_eval.py
```
## Demo Directories
### langchain_demo/
Full LangChain agent integration demo:
```bash
# No API key needed for compression demo
PYTHONPATH=. python -m examples.langchain_demo.show_compression
# Full comparison (requires API key)
export OPENAI_API_KEY='your-key'
PYTHONPATH=. python -m examples.langchain_demo.run_comparison
```
See [langchain_demo/README.md](langchain_demo/README.md) for details.
### claude_code_remote_control/
Keep Claude Code's Remote Control while routing through Headroom: `ANTHROPIC_BASE_URL`
stays unset and a local mitmproxy addon hands `/v1/messages` to Headroom via `HTTPS_PROXY`:
```bash
mitmdump --listen-host 127.0.0.1 --listen-port 8790 \
--allow-hosts '^api\.anthropic\.com(:443)?$' \
-s examples/claude_code_remote_control/route_to_headroom.py
```
See [claude_code_remote_control/README.md](claude_code_remote_control/README.md) for the Claude Code settings.
### mcp_demo/
MCP (Model Context Protocol) integration demo:
```bash
export OPENAI_API_KEY='your-key'
PYTHONPATH=. python -m examples.mcp_demo.run_agent_eval
```
### vertex_gemini_benchmark/
Gemini 3.8 Flash on Google Cloud Vertex AI (Gemini Enterprise Agent Platform) benchmark:
```bash
# Ensure Google Cloud ADC is active
gcloud auth application-default login
export GCP_PROJECT_ID="your-project-id"
# Run comparative benchmark (Direct vs Headroom Proxied)
python examples/vertex_gemini_benchmark/benchmark.py --model gemini-3.8-flash
```
See [vertex_gemini_benchmark/README.md](vertex_gemini_benchmark/README.md) for full benchmark scenarios and methodology.
### strands_bedrock_demo.py
AWS Strands Agents + Bedrock integration demo. Showcases two Headroom integration patterns:
1. **HeadroomHookProvider** - Compresses tool outputs in real-time
2. **HeadroomStrandsModel** - Optimizes entire conversation context
```bash
# Configure AWS credentials
export AWS_ACCESS_KEY_ID='your-access-key'
export AWS_SECRET_ACCESS_KEY='your-secret-key'
export AWS_DEFAULT_REGION='us-west-2' # Optional, defaults to us-west-2
# Or use AWS profile
export AWS_PROFILE='your-profile-name'
# Run the full demo (both integration patterns)
python examples/strands_bedrock_demo.py
# Run only the hook provider demo
python examples/strands_bedrock_demo.py --hook
# Run only the model wrapper demo
python examples/strands_bedrock_demo.py --model
# Specify a different AWS region
python examples/strands_bedrock_demo.py --region us-east-1
```
The demo uses Claude 3 Haiku via Bedrock for cost efficiency. It creates agents with
4 tools that return verbose JSON output (search results, logs, database records, metrics)
and displays compression statistics with visual comparisons.
**Requirements:**
- AWS account with Bedrock enabled
- Claude 3 Haiku model access in your region
- `pip install strands-agents headroom-ai[strands]`
## Running Examples
All examples can be run from the repository root:
```bash
# Install dependencies
pip install -e ".[dev]"
# Run any example
python examples/<example_name>.py
```
## Expected Results
| Example | Token Savings | Notes |
|---------|---------------|-------|
| basic_usage | 50-70% | Simple tool output compression |
| langchain_demo | 70-85% | Real agent with multiple tools |
| mcp_demo | 60-80% | MCP tool outputs |
| strands_bedrock_demo | 60-85% | Strands + Bedrock with verbose tools |
| real_world_eval | 50-90% | Varies by scenario |
## Troubleshooting
**ModuleNotFoundError: No module named 'headroom'**
Run from the repository root with PYTHONPATH:
```bash
PYTHONPATH=. python examples/basic_usage.py
```
Or install in development mode:
```bash
pip install -e .
```
**API Key Errors**
Ensure your API keys are set:
```bash
export OPENAI_API_KEY='sk-...'
export ANTHROPIC_API_KEY='sk-ant-...'
```
**AWS Credentials Errors (for Strands demo)**
Ensure AWS credentials are configured:
```bash
# Option 1: Environment variables
export AWS_ACCESS_KEY_ID='your-access-key'
export AWS_SECRET_ACCESS_KEY='your-secret-key'
# Option 2: AWS profile
export AWS_PROFILE='your-profile-name'
# Option 3: AWS credentials file (~/.aws/credentials)
```
Also ensure Bedrock and the Claude 3 Haiku model are enabled in your AWS account.