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): correct credential-storage claim and add a security model page (#2684)

Keshav Reddy6ff74c5db576
diff --git a/SECURITY.md b/SECURITY.md
index 7bdd35214..ad989f2a3 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -4,8 +4,13 @@
| Version | Supported |
| ------- | ------------------ |
-| 0.27.x (latest) | :white_check_mark: |
-| < 0.27.x | :x: |
+| Latest release on PyPI | :white_check_mark: |
+| Any earlier release | :x: |
+
+Headroom releases frequently and only the most recent release is supported. Security
+fixes ship in a new release rather than being backported to earlier ones, so upgrading is
+the remediation path. Check what you are running with `headroom --version`, and compare it
+against [the current release](https://pypi.org/project/headroom-ai/).
## Reporting a Vulnerability
@@ -38,8 +43,16 @@ When using Headroom:
1. **API Keys**: Never commit API keys. Use environment variables.
2. **Proxy Exposure**: Don't expose the proxy server to the public internet without authentication
-3. **Log Files**: Be aware that request logs may contain sensitive information
+3. **Log Files**: Headroom always writes an operational log to `~/.headroom/logs/proxy.log`.
+ The opt-in `--log-file` request log, and especially `--log-messages`, additionally write
+ request and response *content* to disk. Be aware that both may contain sensitive information.
4. **Budget Limits**: Set budget limits to prevent unexpected costs
+5. **Workspace directory**: `~/.headroom` holds both credential material and cached
+ request content. Treat it as sensitive — especially on shared or multi-user hosts.
+ Note that it is not the only location: with memory enabled, extracted memories default
+ to a project-local `.headroom/` directory beside the code you ran the agent in. See
+ [Security Model](https://headroom-docs.vercel.app/docs/security-model) for exactly what
+ is written where.
### Scope
@@ -53,14 +66,46 @@ The following are out of scope:
- Issues in dependencies (report these to the upstream project)
- Social engineering attacks
-## Security Features
-
-Headroom includes several security features:
-
-- **No credential storage**: We never store or log API keys
-- **Passthrough mode**: Sensitive content passes through unchanged by default
-- **Input validation**: All inputs are validated before processing
-- **Safe defaults**: Security-conscious defaults out of the box
+## Security Posture
+
+Headroom is a local proxy that sits between your agents and your LLM providers, so
+it necessarily handles both your traffic and your credentials. The
+[Security Model](https://headroom-docs.vercel.app/docs/security-model) documents this in
+full — what is written to disk, with what permissions and retention, what leaves the
+host, and what the local admin surface does and does not allow. The summary:
+
+- **Provider API keys are forwarded, not persisted.** Keys supplied via environment
+ variables or request headers are used to authenticate the upstream call and are not
+ written to disk or emitted to logs. The one exception is deliberate: the
+ `ANTHROPIC_TARGET_API_HEADERS` / `OPENAI_TARGET_API_HEADERS` header maps, if you set
+ them through the dashboard settings GUI, are persisted to `~/.headroom/settings.json`
+ in plaintext — and a header map is where a gateway key typically goes.
+- **Some credentials *are* stored, by design.** `headroom copilot-auth login` persists a
+ GitHub Copilot OAuth refresh token to `~/.headroom/copilot_auth.json` (relocatable via
+ `$HEADROOM_COPILOT_AUTH_FILE`). It is plaintext JSON, written with `0600` permissions
+ on a best-effort basis.
+- **Cached request content is written to disk.** CCR stores pre-compression originals —
+ tool outputs, file contents, retrieved chunks — in a local SQLite database
+ (`~/.headroom/ccr_store.db`, `0600`) so they can be retrieved after compression. Entries
+ 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,
+ 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.
+- **Passthrough mode**: Sensitive content passes through unchanged by default.
+- **Operational logs are written unconditionally.** `~/.headroom/logs/proxy.log`
+ (10 MB × 5 rotations) is always on and also carries the admin audit stream. The
+ request log (`--log-file`) and full message logging (`--log-messages`) are opt-in and
+ write request/response content to a path you choose.
+- **Local control surfaces are loopback-gated.** The `/admin/*`, `/debug/*`,
+ `/v1/retrieve*`, `/v1/telemetry*`, `/v1/toin/*`, and `/settings*` routes require a
+ loopback client address *and* a loopback `Host:` header, plus a same-origin check on
+ the mutating ones. This is a local-trust model: any process on the same host is
+ trusted. Setting `HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS` deliberately widens
+ the settings and stats surface beyond loopback.
Thank you for helping keep Headroom and its users safe!
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index f27889912..aa755499e 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -63,6 +63,8 @@
"runtime-rollouts",
"benchmarks",
"limitations",
+ "---Security---",
+ "security-model",
"---Help---",
"errors",
"troubleshooting"
diff --git a/docs/content/docs/security-model.mdx b/docs/content/docs/security-model.mdx
new file mode 100644
index 000000000..a0f0b4133
--- /dev/null
+++ b/docs/content/docs/security-model.mdx
@@ -0,0 +1,447 @@
+---
+title: Security Model
+description: What Headroom writes to disk, what leaves your host, and what the local control surfaces do and do not protect — enough detail for a security review without reading the source.
+---
+
+Headroom is a local MITM proxy. It sits between your coding agents and your LLM
+providers, and it inspects, rewrites, caches, and re-forwards the traffic that passes
+through it. That is the product, and it has direct consequences for where your data
+goes and what it is protected by.
+
+This page documents those consequences: what is written to disk, with what permissions
+and retention, what leaves the host, and what the local control surfaces do and do not
+allow. It is intended to be sufficient for a security review without reading the source.
+
+For reporting a vulnerability, see [SECURITY.md](https://github.com/headroomlabs-ai/headroom/blob/main/SECURITY.md).
+
+## Trust model in one paragraph
+
+Headroom runs as a local process under your own user account, and it trusts that
+account. It sees your full agent traffic in plaintext, and it holds whatever provider
+credentials you give it. Its local HTTP surfaces are restricted to loopback, which
+protects you from remote and cross-origin attackers but **not** from other processes
+running as you on the same machine. Headroom is not designed for multi-tenant hosts,
+and it should not be treated as an isolation boundary between users.
+
+## Data in flight
+
+The proxy terminates the connection from your agent, decompresses and parses the
+request body, applies its transforms, and re-issues the request upstream using your
+credentials. There is no mode in which it forwards traffic it cannot read — inspection
+is what makes compression possible.
+
+In practice this means the proxy process sees, in plaintext: system prompts, full
+conversation history, source code sent as context, tool call arguments and results,
+retrieved chunks, and anything else your agent transmits.
+
+Transport to the provider remains TLS. See
+[Governed knobs](#governed-knobs) for the one setting that relaxes certificate
+validation. The trust store itself is configurable: `SSL_CERT_FILE` and
+`REQUESTS_CA_BUNDLE` have **replacement** semantics — set either and only those CAs are
+trusted — while `NODE_EXTRA_CA_CERTS` is **additive**, loading extra roots on top of the
+system store, matching Node.js. First match wins in that order.
+
+### The upstream is partly client-selectable
+
+"Upstream" is not purely operator-configured. The OpenAI-compatible handlers accept an
+`x-headroom-base-url` request header, so a client on the proxy port can choose the
+destination of a single request. That is deliberate — it is how BYOK gateways (LiteLLM,
+Azure, self-hosted vLLM) reach the dedicated handlers instead of generic passthrough —
+and two separate guards bound it.
+
+**Where it may point.** A client-supplied base URL is resolved and rejected if it lands
+on a private, loopback, link-local, or otherwise non-public address: the confused-deputy
+case where the proxy is used to reach cloud metadata (`169.254.169.254`) or RFC1918
+hosts the caller cannot reach directly. NAT64-embedded IPv4 is unwrapped before the
+check, so it cannot be smuggled through an IPv6 literal. A rejected override is
+**ignored rather than fatal** — the request proceeds to the configured upstream and a
+warning is logged. `HEADROOM_ALLOWED_BASE_URLS` (comma-separated hosts or URLs)
+re-permits specific internal endpoints as an explicit operator choice: a bare host
+permits every safe scheme and port on that host, a full URL permits only its exact
+normalized origin. DNS resolution is bounded by `HEADROOM_UPSTREAM_RESOLVE_TIMEOUT_S`
+(3 seconds by default).
+
+**What may ride along with it.** The operator's own `*_extra_headers` secrets — the two
+credential-shaped maps in [the settings store](#the-settings-store) — travel only to a
+host the operator designated. Designated means one of the resolved provider API targets
+(`ANTHROPIC_TARGET_API_URL`, `OPENAI_TARGET_API_URL`, and the Gemini/Vertex/Bedrock/Cloud
+Code equivalents), the default `api.anthropic.com` / `api.openai.com`, or a host listed
+in `HEADROOM_UPSTREAM_ALLOWED_HOSTS`. Matching is exact equality on the *parsed*
+hostname, never the URL string, so neither
+`https://[email protected]` nor `https://api.anthropic.com.evil.example`
+matches. An undesignated destination is still proxied — it simply does not receive those
+headers — and the drop is warned once per host rather than once per request.
+
+Read the pair for what it is: it stops a client redirecting the *operator's* stored
+credentials to a host of its choosing, and it stops the proxy being used as an SSRF
+pivot into the local network. Neither guard authenticates the caller. They constrain
+what a request can reach and what it carries, not who is allowed to make one — the same
+boundary described under [Local control surfaces](#local-control-surfaces).
+
+## Data at rest
+
+Most state lives under the workspace directory — `~/.headroom` by default, relocatable
+with `$HEADROOM_WORKSPACE_DIR`. **The workspace is not exhaustive**, and an inventory
+that assumes it is will miss files: the memory store defaults to a *project-local* path,
+and both the memory store and the Copilot token can be relocated independently. The
+`Path` column below states where each item actually resolves.
+
+| What | Path | Contents | Retention | Encrypted | Permissions |
+|---|---|---|---|---|---|
+| Copilot OAuth token | `<workspace>/copilot_auth.json`, or `$HEADROOM_COPILOT_AUTH_FILE` | GitHub Copilot OAuth **refresh token**, plaintext JSON | Until you delete it | No | `0600`, best-effort |
+| CCR cache | `<workspace>/ccr_store.db` (SQLite) | **Pre-compression originals**: tool outputs, file contents, retrieved chunks | 30 min default (`HEADROOM_CCR_TTL_SECONDS`), lazily purged | No | `0600` |
+| Memory store | **Project-local by default** — see [Memory store paths](#memory-store-paths) | Extracted cross-session memories | Until deleted | No | Inherits umask |
+| Memory exports | `<workspace>/memories/` | Markdown exports of the above | Until deleted | No | Inherits umask |
+| Install ID | `<config dir>/install_id` | Random UUID identifying the install to the beacon | Until deleted | No | `0600`, best-effort |
+| Savings tracker | `<workspace>/proxy_savings.json` | Aggregate token/cost counters — no prompt content | Until deleted | No | Inherits umask |
+| 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 |
+
+The config directory is `$HEADROOM_CONFIG_DIR`, else `$HEADROOM_WORKSPACE_DIR/config`,
+else `~/.headroom/config`.
+
+**Nothing Headroom writes is encrypted at rest.** Confidentiality of everything above
+rests on filesystem permissions and on the security of the account the proxy runs as.
+
+### The settings store
+
+The dashboard settings GUI persists a curated set of 59 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
+`{"Api-Key": "..."}` as the example. Anything you put there is written to disk in
+plaintext. The GUI masks them on read (`GET /settings` returns a sentinel, not the
+value), but that is a display control, not an at-rest one.
+
+Where these two are *sent* is separately constrained: they are merged only after the
+destination is known, and only for operator-designated hosts. See
+[The upstream is partly client-selectable](#the-upstream-is-partly-client-selectable).
+That bounds the blast radius of the values; it does not change how they are stored.
+
+Two further properties matter for policy:
+
+- **It is a second way environment knobs get set.** `settings_store.apply_to_environ` runs
+ at CLI startup and again when the app is constructed, using `os.environ.setdefault`. The
+ precedence is `shell export > settings.json > code default`, so a stored value silently
+ becomes the effective configuration on any host where the operator assumed the
+ environment was the only input.
+- **The file is `0600` by construction, not by assertion.** `save()` writes atomically via
+ `tempfile.mkstemp` + `os.replace`, and inherits mkstemp's `0600`. There is no explicit
+ `chmod`, so treat the permission as a property of the current implementation rather than
+ a guarantee.
+
+`HEADROOM_TLS_STRICT`, `HEADROOM_BEACON`, `HEADROOM_CCR_BACKEND`, and `HEADROOM_OFFLINE`
+are **not** in the registry — none of them can be set from this file or the routes that
+write it.
+
+### Logs
+
+Two log paths, with very different sensitivity:
+
+- **`<workspace>/logs/proxy.log` — always on.** A `RotatingFileHandler` (10 MB, 5 backups)
+ is attached to the `headroom` logger when the app is created; there is no flag to
+ suppress it, and it is written before configuration is otherwise applied. It carries
+ INFO-level operational records, and — because the audit logger is a child of `headroom`
+ and writes no file of its own — the structured admin audit stream lands here too. Audit
+ events record the action, method, path, source IP, and status code of `/admin/*`,
+ `/cache/clear`, and `/stats/reset` calls.
+
+ Note the permission asymmetry: unlike `copilot_auth.json`, `ccr_store.db`, and
+ `settings.json`, this file gets no explicit mode. Under a common `0002` umask it lands
+ at `0664` — readable by every account on the host.
+- **The request log — opt-in, and content-bearing when you ask for it.** `--log-file`
+ (`$HEADROOM_LOG_FILE`) writes one JSON object per request. By default those objects hold
+ metadata only. `--log-messages` (`$HEADROOM_LOG_MESSAGES`) adds full request and response
+ message content to the same file *and* serves it on the live feed endpoint. Its own help
+ text warns that it may log sensitive data; on this page's terms, it writes your prompts
+ and completions to disk unencrypted, for as long as you keep the file.
+
+Both `HEADROOM_LOG_FILE` and `HEADROOM_LOG_MESSAGES` are in the settings registry, which
+means full message logging can be switched on — and its destination chosen — from the
+settings surface described under
+[Local control surfaces](#local-control-surfaces). `--stateless` suppresses the request
+log entirely (`log_file` is forced to `None`); it does not suppress `proxy.log`.
+
+### Memory store paths
+
+Memory is the one store that does **not** default into the global workspace. With
+`--memory` enabled and `--memory-db-path` unset, the proxy creates
+`{cwd}/.headroom/memory.db` — relative to the working directory the proxy was launched
+from, so a fleet running agents in many repos produces many databases.
+
+Partitioning is then governed by `--memory-storage`, which defaults to `project`:
+
+| Mode | Where memories land |
+|---|---|
+| `project` (default) | One DB per resolved workspace, under `<db_path_dir>/memories/projects/<basename>-<hash>/memory.db` |
+| `user` | One DB per resolved identity — see the note on `x-headroom-user-id` below |
+| `global` | A single shared DB — the `--memory-db-path` file itself |
+
+`--memory-db-path` (env `HEADROOM_MEMORY_DB_PATH`) sets the `global`-mode file and seeds
+the storage root for `project` mode. Scoping can also be steered per-request with the
+`x-headroom-project-id` and `x-headroom-cwd` headers.
+
+`x-headroom-user-id` is treated differently, and the distinction matters for anyone
+reasoning about who can read whose memories. It is a partition **hint, not an
+authenticated identity**, and `resolve_memory_identity` honors it only for loopback
+callers — the single-user local model. Any other caller is bound to a hash of
+`HEADROOM_PROXY_TOKEN`, or failing that the server's OS user, so a network client cannot
+select another user's partition by asserting a header. The check fails closed: a request
+whose peer metadata is missing is not treated as loopback, so unusual ASGI transports
+cannot opt into header trust. Multi-tenant deployments replace the default resolver
+through `set_identity_resolver`; the OSS proxy ships only the single-user default.
+
+For an inventory or a data-deletion procedure, enumerate project-local
+`.headroom/` directories as well as the workspace — memories are the store most likely
+to sit outside it.
+
+### The CCR cache deserves specific attention
+
+CCR ("Compress-Cache-Retrieve") makes compression reversible by keeping the original
+content so the model can retrieve it on demand. That original is written to disk.
+
+By default — `HEADROOM_CCR_BACKEND` unset or `sqlite` — entries land in
+`~/.headroom/ccr_store.db` as one JSON row per entry, with the original in an
+`original_content` field, in plaintext. The store is restart-safe by design, because the
+30-minute TTL assumes it can be shared across worker processes.
+
+Concretely: if a tool result contained a credential, an internal hostname, or a customer
+record, that value is on disk in a readable SQLite database for at least the TTL window.
+
+Two behaviors worth knowing:
+
+- **Expiry is lazy, not scheduled.** Expired rows are removed by a sweep that runs on
+ lookup, not by a background timer. On an idle proxy, content past its TTL remains on
+ disk until the next access. The TTL bounds *retrievability*, not *residency*.
+- **The backend can fall back silently.** If the SQLite backend fails to initialize,
+ Headroom logs a warning and continues with an in-memory store. Retrieval still works;
+ it simply stops surviving restarts.
+
+To avoid disk persistence entirely:
+
+```bash
+HEADROOM_CCR_BACKEND=memory headroom proxy --port 8787
+```
+
+This trades restart-safety and multi-worker sharing for keeping originals in process
+memory only.
+
+## Local control surfaces
+
+The proxy exposes HTTP routes beyond the provider-shaped ones. The sensitive ones —
+`/admin/*`, `/debug/*`, `/cache/clear`, `/stats/reset`, `/settings*`, `/transformations/feed`,
+`/v1/feedback*`, `/v1/telemetry*`, `/v1/toin/*`, and the content-bearing `/v1/retrieve*`
+family — are guarded by `require_loopback`, which enforces two independent conditions:
+
+1. The client address must be a loopback IP.
+2. The inbound `Host:` header must also name loopback.
+
+The second gate is what defeats DNS rebinding, where a remote page resolves an
+attacker-controlled hostname to `127.0.0.1` so the browser connects locally while the
+page origin stays remote. The IP check alone passes in that scenario; the `Host:` check
+does not. Guarded routes return **404**, not 403, so they are indistinguishable from
+absent routes to a scanner.
+
+A third gate, `require_same_origin`, sits on the mutating routes (`/admin/runtime-env`,
+`/cache/clear`, `/stats/reset`, `/settings`, `/settings/apply`). It defends a different
+attack: a plain CSRF, where a remote page's script posts a "simple" request straight at
+`http://127.0.0.1:<port>`. Both loopback gates pass in that case — the browser really is
+connecting to loopback and really does send a loopback `Host:` — but the `Origin:` header
+still names the attacker's page, and that is what this gate rejects. Requests with no
+`Origin` at all (CLI tools, curl) pass, which is the intended behaviour for a
+locally-driven surface.
+
+### The two CIDR allowlists
+
+Two environment variables can extend this beyond loopback. Both default to empty, so the
+default posture is the one described above — but an operator who sets either has changed
+the boundary and should say so in their own threat model.
+
+| Variable | Effect |
+|---|---|
+| `HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS` | Peers in these CIDRs reach `/settings`, `/settings/schema`, `/dashboard/settings`, and the settings *writes* **without being on loopback** — and additionally see the fields `/stats` and `/stats-lifetime` otherwise withhold from network callers (per-request ids, providers, models, errors, project names, backend config). Added so the settings UI works behind a reverse proxy. |
+| `HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS` | Peers in these CIDRs are trusted to supply `X-Forwarded-*` headers, which is what makes the client IP the *forwarded* one rather than the gateway's. |
+
+Both parse strictly: a malformed CIDR raises at startup rather than silently emptying the
+allowlist. Note the interaction — trusting a gateway for `X-Forwarded-For` means the
+dashboard CIDR check is applied to a client-supplied header, so the two must be configured
+together and pointed at infrastructure you control.
+
+### What `POST /admin/runtime-env` can change
+
+`headroom wrap` hot-syncs settings to a running proxy through this route. It does not
+accept arbitrary environment variables — writes are restricted to a hardcoded allowlist
+(`RUNTIME_ENV_KNOBS`), currently:
+
+| Knob | Purpose |
+|---|---|
+| `HEADROOM_OUTPUT_SHAPER` | Master switch for output-token shaping |
+| `HEADROOM_VERBOSITY_LEVEL` | Verbosity steering level |
+| `HEADROOM_EFFORT_ROUTER` | Lower effort on mechanical continuations |
+| `HEADROOM_MECHANICAL_EFFORT` | Effort value for those continuations |
+| `HEADROOM_VERBOSITY_AUTOTUNE` | AIMD verbosity controller state |
+| `HEADROOM_OUTPUT_HOLDOUT` | Output-shaping holdout fraction |
+| `HEADROOM_INTERCEPT_READ_MIN_CHARS` | ast-grep read-interception threshold |
+
+Keys outside this list are ignored, and `/admin/upstream` is read-only — there is no
+write route on the admin surface, specifically so a caller cannot redirect
+credential-bearing traffic through it.
+
+### What `POST /settings` can change
+
+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
+[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).
+
+That combination has consequences worth stating plainly:
+
+- **The upstream URL *can* be changed through this surface.** `ANTHROPIC_TARGET_API_URL`
+ and `OPENAI_TARGET_API_URL` are in the registry. `/admin/upstream` remains read-only,
+ but a caller who reaches `/settings` can still repoint credential-bearing traffic at a
+ destination of their choosing and restart the proxy to apply it. If you are relying on
+ the admin surface being read-only, this is the path that gets around it.
+- **Full message logging can be switched on.** `HEADROOM_LOG_MESSAGES` and
+ `HEADROOM_LOG_FILE` are both in the registry, so the same caller can start writing your
+ prompts and completions to a file path they choose.
+- **Credential-shaped values can be written.** The two `*_TARGET_API_HEADERS` maps are
+ stored here in plaintext.
+
+What is *not* reachable, verified against both the runtime-env allowlist and the settings
+registry: `HEADROOM_TLS_STRICT`, `HEADROOM_BEACON`, `HEADROOM_CCR_BACKEND`, and
+`HEADROOM_OFFLINE`. TLS verification in particular cannot be relaxed over HTTP; it is read
+from the process environment at startup only.
+
+All of these calls are audited. `/admin/*`, `/cache/clear`, and `/stats/reset` emit a
+structured event carrying action, method, path, source IP, and status; `/admin/runtime-env`,
+`POST /settings`, and `POST /settings/apply` add their own with the *changed keys* — keys
+only, deliberately, so a secret's value never reaches the log. The audit stream is a
+logger, not a file of its own, so in a default install it lands in
+`<workspace>/logs/proxy.log`.
+
+### Residual risk
+
+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
+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*.
+
+For single-user developer machines — the intended deployment — this is proportionate.
+For shared build boxes, multi-user jump hosts, or anywhere untrusted local code runs,
+it is not, and Headroom should not be deployed there without additional isolation.
+
+## Network egress
+
+Beyond your configured LLM providers, Headroom may contact:
+
+| Destination | Purpose | Default | Disable / pre-provision |
+|---|---|---|---|
+| `headroom-beacon.headroom-beacon.workers.dev` | Anonymous session summaries to Headroom Labs | **On** — see [The beacon](#the-beacon-is-on-by-default) | `HEADROOM_BEACON=off`, `DO_NOT_TRACK=1`, or `HEADROOM_OFFLINE` |
+| `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 |
+
+### 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**
+(`BEACON_DEFAULT_ON = True`). Session summaries are POSTed to
+`https://headroom-beacon.headroom-beacon.workers.dev/v1/logs`, currently a Cloudflare
+`workers.dev` address.
+
+**Payload class: counters and identifiers, no content.** Each report is a cumulative
+snapshot — not a delta — carrying:
+
+- **Session**: a random id, a sequence number, duration, turn count, and whether this is
+ the final report for the session.
+- **Tokens**: original, attempted, input, output, saved, tool-saved, cache read/write, and
+ uncached counts, plus derived percentages (saved, eligible, yield, all-layers variants,
+ cache-read, latency overhead).
+- **Compression**: transform and skip tallies keyed by transform slug, a per-strategy
+ breakdown (`strategy`, event count, tokens in, tokens out), aggregate and per-turn
+ 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.
+
+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.
+
+The keys in the tally dictionaries are internal slugs, not free text: transform names are
+truncated at the first colon before being counted, and sources are one of two literals.
+Prompts, completions, file contents, tool results, and file paths are **not** in the
+payload. The install id is a random UUID rather than a machine fingerprint, and resets
+if you delete `<config dir>/install_id`.
+
+Three controls switch it off, checked in this order:
+
+```bash
+HEADROOM_OFFLINE=1 # offline mode — disables all egress, not just the beacon
+DO_NOT_TRACK=1 # the cross-tool convention, honoured
+HEADROOM_BEACON=off # also false / 0 / no / disable / disabled
+```
+
+The destination can also be redirected with `HEADROOM_TELEMETRY_ENDPOINT`, which is
+useful if you would rather terminate the reports at a receiver you control than block
+them outright.
+
+One asymmetry is worth knowing for policy purposes: `HEADROOM_TELEMETRY` is fail-*closed*
+(an unrecognised value leaves it off), whereas the beacon is fail-*open* while the
+default stands — an unrecognised `HEADROOM_BEACON` value uploads. If you are disabling it
+by configuration management, assert one of the exact off-values above rather than
+assuming a typo fails safe.
+
+### Local telemetry and OpenTelemetry are separate
+
+`HEADROOM_TELEMETRY` is a **different switch**, off by default and opt-in. It aggregates
+stats locally for the in-process collector and the `/stats` and `/v1/telemetry`
+endpoints, and sends nothing off-host. Enabling it does not authorise beacon upload, and
+disabling it does not suppress the beacon — the two are deliberately independent.
+
+Operational metrics are separate again: OpenTelemetry export
+(`HEADROOM_OTEL_METRICS_*`) is opt-in and targets a collector you specify.
+
+For a controlled fleet, set `HEADROOM_BEACON=off` (or `DO_NOT_TRACK=1`) via configuration
+management, pin the package version, set `HEADROOM_UPDATE_CHECK=off`, and pre-provision
+model assets rather than allowing runtime fetches. `HEADROOM_OFFLINE=1` covers all four
+at once where fully-offline operation is acceptable.
+
+## Governed knobs
+
+Two further environment variables are worth an explicit policy decision.
+(`HEADROOM_BEACON` is the third, covered under [The beacon](#the-beacon-is-on-by-default).)
+
+A note on where "the environment" comes from: `settings.json` is applied to the process
+environment at startup with `setdefault`, so for any knob in the settings registry the
+effective value may come from that file rather than from your shell. None of the three
+knobs in this section are in that registry, but a fleet policy asserted purely by
+inspecting exported environment variables is incomplete for the ones that are — see
+[The settings store](#the-settings-store).
+
+**`HEADROOM_TLS_STRICT=0`** relaxes certificate validation so Headroom can operate
+behind a corporate TLS-inspecting proxy. It is narrowly scoped — it clears only the
+RFC 5280 strict flag and does not disable verification wholesale — but it is still a
+loosening of transport security and should be set deliberately rather than habitually.
+See the README for details on scope and platform behavior.
+
+**`HEADROOM_UPDATE_CHECK=off`** disables the daily PyPI version check. Recommended for
+managed fleets, where upgrades should be driven by your own release process.
+
+Neither is reachable through the admin endpoint or the settings routes; both are read
+from the process environment only.
+
+## What `wrap` changes on your machine
+
+`headroom wrap` makes persistent modifications to your development environment: it
+injects configuration into agent config files, may edit `CLAUDE.md` / `AGENTS.md`, and
+can install MCP servers. `headroom unwrap` reverses the wrapping.
+
+A full teardown currently spans several commands and is tracked in
+[#748](https://github.com/headroomlabs-ai/headroom/issues/748), which also proposes a
+consolidated `headroom uninstall`. Until that lands, treat wrapping as a change to
+inventory on managed machines.