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.

docs(security): sync security model with egress pollers, counts and beacon payload (#4539)

HetCreepee975d49c0b7
diff --git a/SECURITY.md b/SECURITY.md
index 8defcde14..114b6b8fd 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -113,8 +113,10 @@ host, and what the local admin surface does and does not allow. The summary:
are plaintext and are not encrypted at rest. Set `HEADROOM_CCR_BACKEND=memory` if your
deployment cannot accept disk persistence.
- **Anonymous session summaries are uploaded by default.** The `HEADROOM_BEACON` telemetry
- beacon is opt-*out*: it POSTs content-free session counters, a random per-install UUID,
- version, OS, and architecture to Headroom Labs. No prompts, completions, file contents,
+ beacon is opt-*out*: it POSTs content-free session counters and distributions, a random per-install
+ UUID, version, OS, and architecture to Headroom Labs, plus the values of 15 allow-listed
+ `HEADROOM_*` settings and a bucketed structural descriptor of tool outputs (field count,
+ depth, shape flags). `headroom telemetry --show` prints the exact payload. No prompts, completions, file contents,
or paths are included. Disable with `HEADROOM_BEACON=off`, `DO_NOT_TRACK=1`, or
`HEADROOM_OFFLINE=1`. This is separate from `HEADROOM_TELEMETRY`, which is opt-in and
stays on the machine.
diff --git a/docs/content/docs/architecture.mdx b/docs/content/docs/architecture.mdx
index 58439a26c..aff1613db 100644
--- a/docs/content/docs/architecture.mdx
+++ b/docs/content/docs/architecture.mdx
@@ -109,7 +109,7 @@ CCR is **on by default**. Disable the markers and the injected retrieval tool wi
TOIN learns which fields matter for a given tool over repeated calls — which items get retrieved, which fields carry signal — and feeds that back into SmartCrusher's importance scoring so compression gets sharper for the tools you actually use.
-TOIN is **local and observation-only**: it aggregates statistics on your own machine (or your own proxy instance). Nothing about your tools or traffic is shared across users or sent off the box. For a brand-new tool type it falls back to statistical heuristics and improves as it observes more calls.
+TOIN is **local and observation-only**: it aggregates statistics on your own machine (or your own proxy instance). The learned patterns stay on your machine and are not shared across users. When the anonymous session beacon is on (the default; see [Security model](/docs/security-model#the-beacon-is-on-by-default)), a content-free structural descriptor of each tool output (bucketed field count, nesting depth, shape flags) and token counts are included in it; the same switches turn that off. For a brand-new tool type it falls back to statistical heuristics and improves as it observes more calls.
## What Headroom does not rewrite
diff --git a/docs/content/docs/security-model.mdx b/docs/content/docs/security-model.mdx
index fecc9ea2c..2ece6dd33 100644
--- a/docs/content/docs/security-model.mdx
+++ b/docs/content/docs/security-model.mdx
@@ -97,7 +97,7 @@ and both the memory store and the Copilot token can be relocated independently.
| License cache | `<workspace>/license_cache.json` | Cached license envelope | Per envelope | No | Inherits umask |
| Settings store | `<workspace>/settings.json`, or `$HEADROOM_SETTINGS_PATH` | Dashboard-managed knob values — **including two header maps that carry credentials**, see [The settings store](#the-settings-store) | Until deleted | No | `0600`, inherited from `mkstemp` |
| Proxy log | `<workspace>/logs/proxy.log` + 5 rotations | INFO-level operational log, always on; carries the admin audit stream | 10 MB × 5 backups, then rotated out | No | Inherits umask |
-| Request log | Opt-in, `--log-file` / `$HEADROOM_LOG_FILE` | JSONL per-request records; **full request and response content** when `--log-messages` is on | Until deleted | No | Inherits umask |
+| Request log | Opt-in, `--log-file` / `$HEADROOM_LOG_FILE` | JSONL per-request records; **full request and response content** when `--log-messages` is on | Until deleted | No | `0600`, owner-only |
The config directory is `$HEADROOM_CONFIG_DIR`, else `$HEADROOM_WORKSPACE_DIR/config`,
else `~/.headroom/config`.
@@ -107,7 +107,7 @@ rests on filesystem permissions and on the security of the account the proxy run
### The settings store
-The dashboard settings GUI persists a curated set of 59 knobs to
+The dashboard settings GUI persists a curated set of 64 knobs to
`<workspace>/settings.json`. Two of them are marked secret, and both are credential-shaped:
`ANTHROPIC_TARGET_API_HEADERS` and `OPENAI_TARGET_API_HEADERS` are free-form JSON header
maps merged into forwarded requests — the field's own help text gives
@@ -296,7 +296,7 @@ credential-bearing traffic through it.
The settings routes are the wider surface, and they should be read as part of the same
threat model as `/admin/*` rather than as a separate UI concern. `POST /settings`
-validates against the 59-field registry described under
+validates against the 64-field registry described under
[The settings store](#the-settings-store) and writes the result to disk;
`POST /settings/apply` does the same and then **restarts the proxy** so the values take
effect (self-restarting on service deployments, returning the host command under Docker).
@@ -330,7 +330,7 @@ logger, not a file of its own, so in a default install it lands in
The loopback and same-origin gates are an effective boundary against remote and
browser-based attackers. They are not a boundary against local ones. Any process that can
-bind a loopback socket as your user can flip the seven runtime knobs, write the 59
+bind a loopback socket as your user can flip the ten runtime knobs, write the 64
settings and restart the proxy to apply them, read `/v1/retrieve*`, and reach the debug
routes. There is no token, no mTLS, and no per-caller authorization — the guards
distinguish *where a request came from*, not *who sent it*.
@@ -349,12 +349,14 @@ Beyond your configured LLM providers, Headroom may contact:
| `pypi.org` | Daily version check for update notices | On | `HEADROOM_UPDATE_CHECK=off`; also skipped in `--stateless`, in CI, and from source checkouts |
| `huggingface.co` | Downloads models for the optional ML compression paths | On first use of those features | Pre-provision the model cache, or leave the features disabled |
| `app.headroomlabs.ai` | License validation and usage reporting | Only with a license key configured | Omit the license key |
+| `api.anthropic.com` | Subscription usage poll (`/api/oauth/usage`) for the quota panel; sends your Claude OAuth token as a bearer credential | On, but it only polls when a token is found (`CLAUDE_CODE_OAUTH_TOKEN` or the Claude credentials file); every 300 s | `HEADROOM_NO_SUBSCRIPTION_TRACKING=1` or `HEADROOM_OFFLINE` |
+| `api.github.com` | GitHub Copilot quota poll (`/copilot_internal/user`); sends a GitHub token as a bearer credential | On, but it only polls when one of `GITHUB_COPILOT_GITHUB_TOKEN`, `GITHUB_TOKEN`, `COPILOT_GITHUB_TOKEN` or `GITHUB_COPILOT_API_TOKEN` is set; every 60 s | No dedicated switch found. Unset those variables, or use `HEADROOM_OFFLINE` |
| `mobile.events.data.microsoft.com` | ONNX Runtime's own usage telemetry to Microsoft (ORT 1.31+ on Linux and macOS): hashed device id, model file and graph names, model hashes, execution providers, hardware ids | **Off**: importing `headroom` sets `ORT_DISABLE_TELEMETRY=1` unless it is already set | Leave `ORT_DISABLE_TELEMETRY` unset or `1`; setting it to `0` turns ORT's telemetry back on |
### The beacon is on by default
-This is the one egress path that is enabled without any action from you, so it warrants
-its own treatment. It is governed by `HEADROOM_BEACON` and is **opt-out**
+This is the one egress path that is enabled by default whatever credentials you have, so it
+warrants its own treatment. It is governed by `HEADROOM_BEACON` and is **opt-out**
(`BEACON_DEFAULT_ON = True`). Session summaries are POSTed to
`https://headroom-beacon.headroom-beacon.workers.dev/v1/logs`, currently a Cloudflare
`workers.dev` address.
@@ -372,6 +374,16 @@ snapshot — not a delta — carrying:
latency/overhead in milliseconds, passthrough turns, and response-cache hits.
- **Context**: request sources (`proxy` / `mcp`), the sorted provider and model names seen,
a failure count, and those failures split by HTTP status code.
+- **Schema v2 additions** (`schema_version: 2`, additive over v1): `quality` (tokens re-read
+ because compression removed them), `hist` (fixed-bucket distributions), `shapes` (content
+ type and strategy counts, plus a bucketed structural descriptor per tool output: field
+ count rounded down to a power of two, nesting depth and shape-flag letters, never field
+ names or TOIN's structure hash), `cache` (prompt-cache hit rate by gap since the previous
+ turn), `trajectory`, `clients` (harness name and turn count), `errors` (4xx counts by
+ status), `strata` (output-shaper A/B arm and request features), and `config` (the values
+ of 15 allow-listed `HEADROOM_*` variables, each reduced to a short slug; the list is
+ `_CONFIG_ENV_KEYS` in `headroom/telemetry/session.py`). `headroom telemetry --show` prints
+ the exact payload.
Alongside each report go resource attributes: a random per-install UUID, Headroom version,
OS type, CPU architecture, and — when known — install mode and detected stack.
diff --git a/headroom/telemetry/session.py b/headroom/telemetry/session.py
index 964ee0e88..aecbf50ef 100644
--- a/headroom/telemetry/session.py
+++ b/headroom/telemetry/session.py
@@ -1,7 +1,8 @@
"""Session aggregation for the anonymous telemetry beacon.
One wide event per session, emitted when the session goes idle. Everything here
-is off unless ``HEADROOM_TELEMETRY`` is explicitly on — see
+is on by default and off when the beacon is disabled (``HEADROOM_BEACON=off``,
+``HEADROOM_TELEMETRY=off``, ``DO_NOT_TRACK=1`` or offline mode) — see
:mod:`headroom.telemetry.beacon`.
# What counts as a session
@@ -1905,8 +1906,8 @@ def record_compression(strategy: str, original_tokens: int, compressed_tokens: i
(``PrometheusMetrics.tokens_saved_by_strategy``); they just never left the
process.
- Same discipline as the rest of this module: off by default and cheap when
- off, never raises. This runs once per routing decision, so it must not do
+ Same discipline as the rest of this module: cheap when the beacon is
+ disabled, never raises. This runs once per routing decision, so it must not do
anything a request would notice.
"""
from headroom.telemetry.beacon import is_beacon_enabled
@@ -2022,7 +2023,7 @@ def record_content_shape(
Single-observation form of :func:`record_content_shapes`, which is what the
router actually calls. Same discipline as everything else in this module:
- off by default, cheap when off, never raises, and never touches the
+ cheap when the beacon is disabled, never raises, and never touches the
aggregator lock.
"""
record_content_shapes(((content_type, strategy, original_tokens, compressed_tokens),))
@@ -2200,8 +2201,8 @@ def _drain_staged_tool_shapes() -> dict[str, list[int]]:
def record_outcome(outcome: Any) -> None:
"""Beacon entry point, called from the proxy's outcome funnel.
- Off by default and cheap when off: the enabled check short-circuits before
- the aggregator is ever constructed, so a user who never opted in pays one
+ Cheap when the beacon is disabled: the enabled check short-circuits before
+ the aggregator is ever constructed, so a user who has opted out pays one
env lookup per request and allocates nothing.
"""
from headroom.telemetry.beacon import is_beacon_enabled