Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(dashboard): serve per-request metadata to trusted-gateway peers (#1766)

Kenneth Wong560319cef4e3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 699768211..6a9b3b8aa 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## Unreleased
+### Fixed
+- The dashboard's per-request metadata (the `recent_requests` / `request_logs`
+ tail and the `config` block with upstream URLs) is gated to loopback callers
+ via `_request_is_loopback`. When Headroom runs in a bridge-network container
+ (Docker/podman, or Apple Containerization / mocker), a browser on the host
+ reaches the proxy through the container gateway, so `request.client.host` is
+ the gateway IP rather than `127.0.0.1` — the sensitive block was stripped and
+ the "Recent Requests" table rendered empty even though the operator is local.
+ A peer inside an operator-configured trusted-gateway CIDR
+ (`HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS`, already used to sanitize
+ `X-Forwarded-*`) is now treated as loopback-equivalent, while the loopback
+ `Host`-header gate is retained as the DNS-rebinding defence. Opt-in and empty
+ by default, so there is no behavior change unless the gateway CIDR is
+ allow-listed.
+- Non-finite values (`NaN`, `Infinity`) in `proxy_savings.json` or in upstream
+ cost/token metadata no longer crash the proxy or corrupt the savings
+ dashboard. `SavingsTracker`'s numeric coercion caught only `TypeError` and
+ `ValueError`, so `int(float('inf'))` raised an uncaught `OverflowError` while
+ loading persisted state (`SavingsTracker.__init__` failed and the proxy would
+ not start), and `float('nan')`/`float('inf')` passed straight through, then
+ serialized to `NaN`/`Infinity` literals that the dashboard's `JSON.parse`
+ rejects. `json.loads` accepts those literals, so one bad write poisoned every
+ later start. Both coercion helpers now also catch `OverflowError` and reject
+ non-finite floats, failing open to safe defaults.
+- `headroom learn` now honors `CLAUDE_CONFIG_DIR`. It resolved the Claude
+ config directory as `~/.claude` and wrote global memory to
+ `~/.claude/CLAUDE.md`, so users who relocate their Claude config via that
+ env var had `learn` scan the wrong directory and detect no projects. The
+ scanner and memory writer now read/write the configured directory
+ ([#1630](https://github.com/headroomlabs-ai/headroom/issues/1630)).
+- `--backend bedrock` now fails fast with an actionable error when temporary
+ AWS credentials (`AWS_SESSION_TOKEN`) are used but botocore is not installed
+ (e.g. the slim default Docker image). litellm's session-token auth path
+ imports botocore, so the missing dependency previously surfaced only at
+ request time as a misleading `authentication_error: No module named
+ 'botocore'`. The proxy now tells the user to install the `bedrock` extra up
+ front ([#1551](https://github.com/headroomlabs-ai/headroom/issues/1551)).
+- Content detection no longer crashes the proxy on text containing an
+ orphaned `+++ ` target line with no preceding `--- ` source line (common in
+ `set -x` xtrace output and partial diffs). The bundled `unidiff` 0.4.0 parser
+ panics on that input instead of returning an error; the Rust diff detector now
+ contains the panic and treats the fragment as plain text, so the request is
+ compressed and forwarded normally instead of returning HTTP 500
+ ([#1547](https://github.com/headroomlabs-ai/headroom/issues/1547)).
+- Proactive expansion blocks injected into user turns are now wrapped in
+ `<headroom_proactive_expansion>` XML tags, giving downstream consumers
+ (LLMs, loggers, attribution parsers) a machine-readable provenance
+ boundary and preventing misattribution in multi-agent threads.
+- **cli:** the startup banner no longer advertises
+ `HEADROOM_COMPRESSION_STABLE_AFTER_TURN` and
+ `HEADROOM_STALE_READ_COMPRESS_AFTER_TURNS` as tuning knobs. Both were read
+ only to render the `Performance Tuning` banner section and were never wired
+ into the compression path, so setting them changed the banner but had no
+ effect on behavior. The banner now surfaces only the embedding sidecar,
+ which is a real, consumed setting.
+- **memory/embedder:** cap CPU thread oversubscription in the local
+ torch/sentence-transformers embedder. Concurrent encodes previously each
+ fanned out to ~`os.cpu_count()` BLAS/OpenMP threads, so under load the memory
+ path starved the asyncio event loop and spiked `/livez` latency to several
+ seconds. CPU encodes now run on a dedicated, size-limited executor whose
+ workers each pin their thread pool, bounding total embedding threads to
+ `HEADROOM_EMBED_CONCURRENCY` × `HEADROOM_EMBED_NUM_THREADS` (defaults
+ `min(4, cpu)` × 1). The ONNX embedder already capped its threads; this brings
+ the torch path to parity
+ ([#198](https://github.com/headroomlabs-ai/headroom/issues/198)).
+
### Changed
* **telemetry:** anonymous usage telemetry is now **opt-in** (off by default) instead of opt-out. Nothing is collected or sent unless you set `HEADROOM_TELEMETRY=on` or pass `--telemetry` to `headroom proxy` / `headroom install apply`. `is_telemetry_enabled()` is fail-closed — only explicit on-values (`on`/`true`/`1`/`yes`/`enable`/`enabled`) enable it; unset, empty, or unrecognized values stay disabled. The existing `--no-telemetry` flag and `HEADROOM_TELEMETRY=off` remain accepted for back-compat, and install manifests now write the `HEADROOM_TELEMETRY` value explicitly so generated deployments are unambiguous.
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index ce7e8a163..d69225862 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -2005,7 +2005,29 @@ def _request_is_loopback(request: Request) -> bool:
host_header = request.headers.get("host")
except AttributeError:
host_header = None
- return is_loopback_host(client_host) and is_loopback_host_header(host_header)
+
+ # The Host-header gate is the DNS-rebinding defence and always applies.
+ if not is_loopback_host_header(host_header):
+ return False
+
+ # Genuine loopback peer (native run, or curl inside the container).
+ if is_loopback_host(client_host):
+ return True
+
+ # Containerized dashboards: when Headroom runs in a bridge-network
+ # container, a browser on the host reaches it via the container's
+ # gateway, so ``request.client.host`` is the gateway IP, not 127.0.0.1
+ # — and the per-request logs / upstream URLs get stripped even though
+ # the operator is local. Treat a peer inside an operator-configured
+ # trusted-gateway CIDR as loopback-equivalent. Opt-in and empty by
+ # default (HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS), so this is a no-op
+ # unless the operator explicitly allow-lists their container gateway.
+ from headroom.proxy.forwarded_headers import (
+ load_trusted_gateway_cidrs,
+ peer_is_trusted_gateway,
+ )
+
+ return peer_is_trusted_gateway(client_host, load_trusted_gateway_cidrs())
_is_known_websocket_callback_failure = is_known_websocket_callback_failure
diff --git a/tests/test_proxy_loopback_gating.py b/tests/test_proxy_loopback_gating.py
index 8386ed93d..73b0fb73b 100644
--- a/tests/test_proxy_loopback_gating.py
+++ b/tests/test_proxy_loopback_gating.py
@@ -150,3 +150,38 @@ def test_stats_per_request_metadata_is_loopback_only() -> None:
local = _client(loopback=True).get("/stats").json()
assert "recent_requests" in local
assert "config" in local
+
+
+def test_stats_metadata_served_to_trusted_gateway_peer(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Containerized dashboards: a browser on the host reaches a bridge-network
+ container via the gateway IP, so the peer isn't 127.0.0.1 and per-request
+ metadata gets stripped. When the operator allow-lists the gateway CIDR via
+ HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS, the peer is treated as
+ loopback-equivalent and the metadata is served again."""
+ gateway_ip = "172.18.0.1" # typical docker/mocker bridge gateway
+ app = _make_app()
+
+ def _gateway_client() -> TestClient:
+ # Loopback Host header (the operator browses http://127.0.0.1:8787) but
+ # the peer IP is the container gateway, not loopback.
+ return TestClient(app, base_url="http://127.0.0.1", client=(gateway_ip, 54321))
+
+ # Without the allow-list, the gateway peer is untrusted → metadata stripped.
+ monkeypatch.delenv("HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS", raising=False)
+ stripped = _gateway_client().get("/stats").json()
+ assert "recent_requests" not in stripped
+ assert "config" not in stripped
+
+ # Allow-list the gateway CIDR → peer trusted → metadata served.
+ monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS", "172.18.0.0/16")
+ served = _gateway_client().get("/stats").json()
+ assert "recent_requests" in served
+ assert "config" in served
+
+ # DNS-rebinding defence still applies even for a trusted gateway peer: a
+ # non-loopback Host header must be rejected.
+ rebind = TestClient(app, base_url="http://attacker.example", client=(gateway_ip, 54321))
+ payload = rebind.get("/stats").json()
+ assert "recent_requests" not in payload