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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix(telemetry): switch anonymous telemetry to opt-in (off by default) (#1223)
Tejas Choprab99869778bb3
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ad3a33dca..abf2fb0bc 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## Unreleased+### 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.+### Features* **proxy:** measure and surface rolling and current token throughput metrics (active/wall-clock input, compression, effective forward, and streamed generation) in `headroom perf` CLI and the dashboard ([#959](https://github.com/chopratejas/headroom/issues/959)).diff --git a/docs/content/docs/benchmarks.mdx b/docs/content/docs/benchmarks.mdxindex 53856f160..fa69ea90f 100644--- a/docs/content/docs/benchmarks.mdx+++ b/docs/content/docs/benchmarks.mdx@@ -107,7 +107,7 @@ ContentRouter accounts for 91--98% of pipeline cost on average. CacheAligner and## Production Telemetry-Real-world data from **50,000+ proxy sessions** across 250+ unique instances (March--April 2026). Collected via anonymous telemetry (opt-out: `HEADROOM_TELEMETRY=off`).+Real-world data from **50,000+ proxy sessions** across 250+ unique instances (March--April 2026). Collected via anonymous telemetry (opt-in: `HEADROOM_TELEMETRY=on`; telemetry is off by default).### Proxy Overheaddiff --git a/docs/content/docs/community-savings.mdx b/docs/content/docs/community-savings.mdxindex 0e174dc79..a0ec8b702 100644--- a/docs/content/docs/community-savings.mdx+++ b/docs/content/docs/community-savings.mdx@@ -3,7 +3,7 @@ title: Community Savingsdescription: Aggregate savings from Headroom instances across the community. Anonymous telemetry data — no prompts, no content, no PII.----Real-time aggregate metrics from Headroom proxy instances worldwide. All data is anonymous — only token counts, compression ratios, and cost estimates are collected. [Opt out anytime](https://github.com/chopratejas/headroom/blob/main/headroom/telemetry/beacon.py) with `HEADROOM_TELEMETRY=off`.+Real-time aggregate metrics from Headroom proxy instances worldwide. All data is anonymous — only token counts, compression ratios, and cost estimates are collected. Telemetry is off by default; [opt in](https://github.com/chopratejas/headroom/blob/main/headroom/telemetry/beacon.py) with `HEADROOM_TELEMETRY=on`.## Overviewdiff --git a/docs/content/docs/configuration.mdx b/docs/content/docs/configuration.mdxindex fb232abb9..98e20ad65 100644--- a/docs/content/docs/configuration.mdx+++ b/docs/content/docs/configuration.mdx@@ -224,7 +224,7 @@ headroom proxy --learn --min-evidence 3| `HEADROOM_MAX_CONNECTIONS` | Maximum upstream HTTP connections | `500` || `HEADROOM_MAX_KEEPALIVE` | Maximum upstream keep-alive connections | `100` || `HEADROOM_BUDGET` | Daily budget limit in USD | -- |-| `HEADROOM_TELEMETRY` | Set to `off` to disable anonymous telemetry | enabled |+| `HEADROOM_TELEMETRY` | Set to `on` to opt in to anonymous telemetry | `off` (opt-in) || `HEADROOM_STATELESS` | Set to `true` to disable filesystem writes | `false` || `HEADROOM_MODEL_LIMITS` | Custom model config (JSON string or file path) | -- || `HEADROOM_BASE_URL` | Base URL of the Headroom proxy (TypeScript SDK) | `http://localhost:8787` |@@ -234,7 +234,7 @@ headroom proxy --learn --min-evidence 3| `HEADROOM_SAVINGS_PATH` | Override persistent savings file location. Always wins when set. | derived from `${HEADROOM_WORKSPACE_DIR}` || `HEADROOM_TOIN_PATH` | Override TOIN telemetry file location. Always wins when set. | derived from `${HEADROOM_WORKSPACE_DIR}` || `HEADROOM_SUBSCRIPTION_STATE_PATH` | Override subscription tracker state file. Always wins when set. | derived from `${HEADROOM_WORKSPACE_DIR}` |-| `HEADROOM_TELEMETRY` | Set to `off` to disable anonymous telemetry | `on` |+| `HEADROOM_TELEMETRY` | Set to `on` to opt in to anonymous telemetry | `off` || `HEADROOM_MEMORY_INJECTION_MODE` | Memory-context routing mode: `live_zone_tail` (default) or `disabled`. The legacy `system_prompt` mode was retired by PR-A2; supplying it raises. | `live_zone_tail` || `HEADROOM_PROXY_PYTHON_FORWARDER_MODE` | Python forwarder serialization mode. `byte_faithful` (default) forwards original request bytes verbatim when no transform mutated the body and re-serializes canonically only when needed — keeps Anthropic prompt-cache hit-rate intact. `legacy_json_kwarg` is an explicit operator opt-in for emergency rollback to the historical `httpx ... json=body` behavior. NOT a fallback — only flip on explicit operator decision. | `byte_faithful` || `HEADROOM_STRIP_INTERNAL_HEADERS` | Python proxy: whether to strip internal `x-headroom-*` request headers (e.g. `x-headroom-bypass`, `x-headroom-mode`, `x-headroom-user-id`, `x-headroom-stack`, `x-headroom-base-url`) before every upstream forwarder call (PR-A5, fixes P5-49). `enabled` (default) stops fingerprinting / leakage. `disabled` is an explicit operator opt-in for diagnostic shadow tracing — NOT a fallback. Inbound reads of these headers (bypass gating, memory user-id resolution) are unaffected because they read `request.headers` directly. | `enabled` |diff --git a/docs/content/docs/installation.mdx b/docs/content/docs/installation.mdxindex 96a3ef7bd..4b681a170 100644--- a/docs/content/docs/installation.mdx+++ b/docs/content/docs/installation.mdx@@ -227,7 +227,7 @@ These variables configure Headroom at runtime. Set them in your shell, `.env` fi| `HEADROOM_PORT` | `8787` | Port the proxy listens on || `HEADROOM_HOST` | `127.0.0.1` | Host the proxy binds to || `HEADROOM_MODE` | `token` | Default optimization mode: `token` or `cache` |-| `HEADROOM_TELEMETRY` | enabled | Set to `off` to disable anonymous telemetry |+| `HEADROOM_TELEMETRY` | `off` (opt-in) | Set to `on` to opt in to anonymous telemetry |### TypeScript SDKdiff --git a/docs/content/docs/proxy.mdx b/docs/content/docs/proxy.mdxindex 6567d514f..ebcec1c23 100644--- a/docs/content/docs/proxy.mdx+++ b/docs/content/docs/proxy.mdx@@ -20,7 +20,7 @@ headroom proxy \--budget 100.0```-Telemetry is enabled by default. Opt out with `HEADROOM_TELEMETRY=off` or `--no-telemetry`.+Telemetry is **off by default** (opt-in). Opt in with `HEADROOM_TELEMETRY=on` or `--telemetry`.## CLI options@@ -46,7 +46,8 @@ Telemetry is enabled by default. Opt out with `HEADROOM_TELEMETRY=off` or `--no-| `--gemini-api-url` | Gemini default | Custom Gemini API URL || `--backend` | `anthropic` | Backend: `anthropic`, `bedrock`, `openrouter`, `anyllm`, or `litellm-<provider>` || `--bedrock-api-url` | None | Bedrock InvokeModel upstream for the `/model/{id}/invoke` passthrough routes (see [Bedrock via a local gateway](#bedrock-via-a-local-gateway)) |-| `--no-telemetry` | `false` | Disable anonymous telemetry |+| `--telemetry` | `false` | Opt in to anonymous telemetry (off by default) |+| `--no-telemetry` | `false` | Force anonymous telemetry off (already the default) || `--stateless` | `false` | Disable filesystem writes and keep runtime state in memory |### Context managementdiff --git a/docs/spec/011-deployment.md b/docs/spec/011-deployment.mdindex ce4e5cf8b..b9be6f433 100644--- a/docs/spec/011-deployment.md+++ b/docs/spec/011-deployment.md@@ -125,7 +125,7 @@ deployment:| `HEADROOM_HOST` | `127.0.0.1` | Proxy host || `ANTHROPIC_API_KEY` | - | Anthropic API key || `OPENAI_API_KEY` | - | OpenAI API key |-| `HEADROOM_TELEMETRY` | enabled | Set to `off` to disable telemetry |+| `HEADROOM_TELEMETRY` | `off` (opt-in) | Set to `on` to opt in to telemetry |### Config Filediff --git a/docs/spec/015-interfaces.md b/docs/spec/015-interfaces.mdindex 20b7069ee..3972cd87e 100644--- a/docs/spec/015-interfaces.md+++ b/docs/spec/015-interfaces.md@@ -26,7 +26,8 @@ headroom proxy [OPTIONS]| `--memory` | `false` | Enable persistent memory || `--learn` | `false` | Enable live traffic learning || `--backend` | `anthropic` | Backend: anthropic, bedrock, openrouter, anyllm, or litellm-* |-| `--no-telemetry` | `false` | Disable anonymous telemetry |+| `--telemetry` | `false` | Opt in to anonymous telemetry (off by default) |+| `--no-telemetry` | `false` | Force anonymous telemetry off (already the default) || `--stateless` | `false` | Disable filesystem writes |---@@ -231,7 +232,7 @@ X-Headroom-Compressed-Tokens: 5325| `HEADROOM_MAX_CONNECTIONS` | `500` | Maximum upstream HTTP connections || `HEADROOM_MAX_KEEPALIVE` | `100` | Maximum upstream keep-alive connections || `HEADROOM_BUDGET` | - | Daily budget limit in USD |-| `HEADROOM_TELEMETRY` | enabled | Set to `off` to disable anonymous telemetry |+| `HEADROOM_TELEMETRY` | `off` (opt-in) | Set to `on` to opt in to anonymous telemetry || `HEADROOM_STATELESS` | `false` | Disable filesystem writes |### Provider@@ -247,7 +248,7 @@ X-Headroom-Compressed-Tokens: 5325| Variable | Default | Description ||----------|---------|-------------|-| `HEADROOM_TELEMETRY` | enabled | Set to `off` to disable telemetry |+| `HEADROOM_TELEMETRY` | `off` (opt-in) | Set to `on` to opt in to telemetry || `HEADROOM_MIN_EVIDENCE` | `5` | Minimum observations before live learning persists a pattern || `HEADROOM_PROXY_EXTENSIONS` | - | Comma-separated proxy extensions to enable || `HEADROOM_STATELESS` | `false` | Disable filesystem writes |diff --git a/headroom/cli/install.py b/headroom/cli/install.pyindex c05ee9d75..12a1727ad 100644--- a/headroom/cli/install.py+++ b/headroom/cli/install.py@@ -157,7 +157,16 @@ def _reject_task_lifecycle(manifest: DeploymentManifest, action: str) -> None:"--mode", "proxy_mode", default="token", show_default=True, help="Proxy optimization mode.")@click.option("--memory", is_flag=True, help="Enable persistent memory in the proxy runtime.")[email protected]("--no-telemetry", is_flag=True, help="Disable anonymous telemetry in the runtime.")+ "--telemetry",+ is_flag=True,+ help="Opt in to anonymous telemetry in the runtime (off by default).",+)+ "--no-telemetry",+ is_flag=True,+ help="Force anonymous telemetry off in the runtime (already the default).",+)@click.option("--image",default="ghcr.io/chopratejas/headroom:latest",@@ -177,6 +186,7 @@ def install_apply(region: str | None,proxy_mode: str,memory: bool,+ telemetry: bool,no_telemetry: bool,image: str,) -> None:@@ -198,7 +208,7 @@ def install_apply(region=region,proxy_mode=proxy_mode,memory_enabled=memory,- telemetry_enabled=not no_telemetry,+ telemetry_enabled=telemetry and not no_telemetry,image=image,)diff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.pyindex bf5e229e1..126dfe7e6 100644--- a/headroom/cli/proxy.py+++ b/headroom/cli/proxy.py@@ -598,10 +598,15 @@ def _selected_context_tool() -> str:"(env: BEDROCK_TARGET_API_URL)"),)+ "--telemetry",+ is_flag=True,+ help="Opt in to anonymous usage telemetry — off by default (env: HEADROOM_TELEMETRY=on)",+)@click.option("--no-telemetry",is_flag=True,- help="Disable anonymous usage telemetry (env: HEADROOM_TELEMETRY=off)",+ help="Force anonymous usage telemetry off (already the default; env: HEADROOM_TELEMETRY=off)",)@click.option("--stateless",@@ -686,6 +691,7 @@ def proxy(bedrock_region: str | None,bedrock_profile: str | None,bedrock_api_url: str | None,+ telemetry: bool,no_telemetry: bool,stateless: bool,embedding_server: bool,@@ -783,7 +789,10 @@ def proxy("on",)- # Telemetry opt-out: --no-telemetry flag sets the env var+ # Telemetry is opt-in (off by default). --telemetry opts in; --no-telemetry+ # forces it off. If both are passed, the explicit opt-out wins (fail-closed).+ if telemetry:+ os.environ["HEADROOM_TELEMETRY"] = "on"if no_telemetry:os.environ["HEADROOM_TELEMETRY"] = "off"@@ -993,14 +1002,17 @@ Memory (Multi-Provider):from headroom.telemetry.beacon import is_telemetry_enabled- # Build telemetry section for the startup banner+ # Build telemetry section for the startup banner. Telemetry is opt-in+ # (off by default); the disabled line surfaces how to opt in.if is_telemetry_enabled():telemetry_line = (- " Telemetry: ENABLED (anonymous aggregate stats)\n"+ " Telemetry: ENABLED (anonymous aggregate stats — you opted in)\n"" Disable: HEADROOM_TELEMETRY=off or headroom proxy --no-telemetry")else:- telemetry_line = " Telemetry: DISABLED"+ telemetry_line = (+ " Telemetry: DISABLED (opt in: HEADROOM_TELEMETRY=on or headroom proxy --telemetry)"+ )# Discover proxy extensions (third-party packages registered via the# `headroom.proxy_extension` entry-point group). Surfaced in the bannerdiff --git a/headroom/install/planner.py b/headroom/install/planner.pyindex 3aac1b7b2..e12f286b6 100644--- a/headroom/install/planner.py+++ b/headroom/install/planner.py@@ -141,8 +141,9 @@ def build_manifest(base_env["HEADROOM_ANYLLM_PROVIDER"] = anyllm_providerif region:base_env["HEADROOM_REGION"] = region- if not telemetry_enabled:- base_env["HEADROOM_TELEMETRY"] = "off"+ # Telemetry is opt-in (off by default). Write the value explicitly so the+ # generated manifest is unambiguous and doesn't depend on the runtime default.+ base_env["HEADROOM_TELEMETRY"] = "on" if telemetry_enabled else "off"if memory_enabled:base_env["HEADROOM_MEMORY_ENABLED"] = "1"@@ -156,8 +157,7 @@ def build_manifest("--backend",backend,]- if not telemetry_enabled:- proxy_args.append("--no-telemetry")+ proxy_args.append("--telemetry" if telemetry_enabled else "--no-telemetry")if memory_enabled:proxy_args.extend(["--memory", "--memory-db-path", str(_paths.memory_db_path())])if anyllm_provider:diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 8504ecf4c..e85f4ded8 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -1376,7 +1376,10 @@ class HeadroomProxy("Opt out: HEADROOM_TELEMETRY=off or --no-telemetry")else:- logger.info("Anonymous telemetry: DISABLED")+ logger.info(+ "Anonymous telemetry: DISABLED (off by default — opt in: "+ "HEADROOM_TELEMETRY=on or --telemetry)"+ )self.pipeline_extensions.emit(PipelineStage.POST_START,diff --git a/headroom/telemetry/beacon.py b/headroom/telemetry/beacon.pyindex 09bb77e16..69c1773ad 100644--- a/headroom/telemetry/beacon.py+++ b/headroom/telemetry/beacon.py@@ -3,9 +3,9 @@Sends aggregate-only stats (tokens saved, compression ratios, cache hit rates,performance overhead) to help improve Headroom. No prompts, no content, no PII.-On by default. Opt out with:- HEADROOM_TELEMETRY=off headroom proxy- headroom proxy --no-telemetry+Off by default (opt-in). Nothing is collected or sent unless you opt in with:+ HEADROOM_TELEMETRY=on headroom proxy+ headroom proxy --telemetry"""from __future__ import annotations@@ -42,6 +42,7 @@ _INTERVAL_SECONDS = 300_OFF_VALUES = frozenset(("off", "false", "0", "no", "disable", "disabled"))+_ON_VALUES = frozenset(("on", "true", "1", "yes", "enable", "enabled"))def _build_pipeline_timing(stats: dict) -> dict[str, object]:@@ -69,9 +70,14 @@ def _build_pipeline_timing(stats: dict) -> dict[str, object]:def is_telemetry_enabled() -> bool:- """Check if telemetry is enabled (on by default, opt out with env var)."""- val = os.environ.get("HEADROOM_TELEMETRY", "on").lower().strip()- return val not in _OFF_VALUES+ """Check if telemetry is enabled (off by default, opt in with env var).++ Fail-closed: telemetry is only enabled when HEADROOM_TELEMETRY is set to an+ explicit on-value (on/true/1/yes/enable/enabled). Anything else — including+ unset, empty, or an unrecognized value — leaves it disabled.+ """+ val = os.environ.get("HEADROOM_TELEMETRY", "").lower().strip()+ return val in _ON_VALUESdef is_telemetry_warn_enabled() -> bool:diff --git a/tests/test_install/test_planner.py b/tests/test_install/test_planner.pyindex 6a84369b1..2832bb08c 100644--- a/tests/test_install/test_planner.py+++ b/tests/test_install/test_planner.py@@ -39,6 +39,7 @@ def test_build_manifest_for_persistent_docker_sets_expected_defaults() -> None:assert manifest.health_url == "http://127.0.0.1:8787/readyz"assert manifest.base_env["HEADROOM_PORT"] == "8787"assert manifest.base_env["HEADROOM_TELEMETRY"] == "off"+ assert "--no-telemetry" in manifest.proxy_argsassert manifest.tool_envs["claude"]["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:8787"assert manifest.tool_envs["copilot"]["COPILOT_PROVIDER_TYPE"] == "anthropic"assert "--memory" in manifest.proxy_args@@ -62,6 +63,9 @@ def test_build_manifest_uses_provider_slice_env_builders_for_all_supported_targeimage="ghcr.io/chopratejas/headroom:latest",)+ # telemetry_enabled=True must write the explicit opt-in value + flag.+ assert manifest.base_env["HEADROOM_TELEMETRY"] == "on"+ assert "--telemetry" in manifest.proxy_argsassert manifest.tool_envs["claude"]["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:9999"assert manifest.tool_envs["codex"]["OPENAI_BASE_URL"] == "http://127.0.0.1:9999/v1"assert manifest.tool_envs["aider"] == {diff --git a/tests/test_telemetry.py b/tests/test_telemetry.pyindex b00c52d3f..f6fae06cf 100644--- a/tests/test_telemetry.py+++ b/tests/test_telemetry.py@@ -601,7 +601,9 @@ class TestGlobalTelemetryCollector:)def test_headroom_telemetry_on_keeps_collector_enabled(self, monkeypatch):- """Sanity check: the explicit on/unset path leaves the collector enabled."""+ """Sanity check: the explicit opt-in path (HEADROOM_TELEMETRY=on) leaves+ the collector enabled. Telemetry is off by default, so this requires the+ user to have turned it on."""reset_telemetry_collector()monkeypatch.delenv("HEADROOM_TELEMETRY_DISABLED", raising=False)monkeypatch.setenv("HEADROOM_TELEMETRY", "on")diff --git a/tests/test_telemetry_warning.py b/tests/test_telemetry_warning.pyindex 43186c4a4..66ad64716 100644--- a/tests/test_telemetry_warning.py+++ b/tests/test_telemetry_warning.py@@ -97,6 +97,20 @@ class TestProxyCLITelemetryBanner:return CliRunner()def test_banner_shows_telemetry_enabled(self, runner, monkeypatch):+ # Telemetry is opt-in: it only shows ENABLED once explicitly turned on.+ monkeypatch.setenv("HEADROOM_TELEMETRY", "on")++ from headroom.cli.main import main++ with patch("headroom.proxy.server.run_server", side_effect=SystemExit(0)):+ result = runner.invoke(main, ["proxy"])++ assert "Telemetry:" in result.output+ assert "ENABLED" in result.output++ def test_banner_disabled_by_default(self, runner, monkeypatch):+ # The whole point of opt-in: unset env => telemetry off, banner says so+ # and surfaces how to opt in.monkeypatch.delenv("HEADROOM_TELEMETRY", raising=False)from headroom.cli.main import main@@ -104,6 +118,18 @@ class TestProxyCLITelemetryBanner:with patch("headroom.proxy.server.run_server", side_effect=SystemExit(0)):result = runner.invoke(main, ["proxy"])+ assert "Telemetry:" in result.output+ assert "DISABLED" in result.output+ assert "HEADROOM_TELEMETRY=on" in result.output or "--telemetry" in result.output++ def test_telemetry_flag_opts_in(self, runner, monkeypatch):+ monkeypatch.delenv("HEADROOM_TELEMETRY", raising=False)++ from headroom.cli.main import main++ with patch("headroom.proxy.server.run_server", side_effect=SystemExit(0)):+ result = runner.invoke(main, ["proxy", "--telemetry"])+assert "Telemetry:" in result.outputassert "ENABLED" in result.output@@ -130,7 +156,7 @@ class TestProxyCLITelemetryBanner:assert "DISABLED" in result.outputdef test_banner_shows_opt_out_instructions_when_enabled(self, runner, monkeypatch):- monkeypatch.delenv("HEADROOM_TELEMETRY", raising=False)+ monkeypatch.setenv("HEADROOM_TELEMETRY", "on")from headroom.cli.main import main@@ -202,7 +228,8 @@ class TestStatsEndpointTelemetryFlag:pytest.importorskip("fastapi")async def test_stats_includes_anon_telemetry_shipping_true(self, monkeypatch):- monkeypatch.delenv("HEADROOM_TELEMETRY", raising=False)+ # Opt-in: shipping is only true once telemetry is explicitly enabled.+ monkeypatch.setenv("HEADROOM_TELEMETRY", "on")from headroom.proxy.server import ProxyConfig, create_appapp = create_app(diff --git a/wiki/benchmarks.md b/wiki/benchmarks.mdindex 673024225..c6d30ba8b 100644--- a/wiki/benchmarks.md+++ b/wiki/benchmarks.md@@ -31,7 +31,7 @@ Tested on Apple M-series (CPU), headroom v0.5.18. Each test runs `compress()` on## Production Telemetry-Real-world data from **50,000+ proxy sessions** across 250+ unique instances (March 30 – April 2, 2026). Collected via anonymous telemetry beacon (opt-out: `HEADROOM_TELEMETRY=off`).+Real-world data from **50,000+ proxy sessions** across 250+ unique instances (March 30 – April 2, 2026). Collected via anonymous telemetry beacon (opt-in: `HEADROOM_TELEMETRY=on`; telemetry is off by default).### Proxy Overhead@@ -184,7 +184,7 @@ A 94.9% compression means the output is 5.1% of the original size.- Collected via anonymous beacon (no prompts, no content, no PII)- Image-inflated instances excluded (base64 counted as text tokens — fixed in v0.5.18)- Multi-worker beacon spam excluded (per-instance MAX, not SUM)-- Opt-out: `HEADROOM_TELEMETRY=off`+- Opt-in: `HEADROOM_TELEMETRY=on` (telemetry is off by default)---diff --git a/wiki/cli.md b/wiki/cli.mdindex 47a27300e..becd6c6a0 100644--- a/wiki/cli.md+++ b/wiki/cli.md@@ -272,7 +272,8 @@ headroom proxy --mode cache| `--region` | `us-west-2` | Cloud region for Bedrock / Vertex / related backends || `--bedrock-region` | unset | Deprecated Bedrock region override || `--bedrock-profile` | unset | AWS profile name for Bedrock |-| `--no-telemetry` | off | Disable anonymous usage telemetry |+| `--telemetry` | off | Opt in to anonymous usage telemetry (off by default) |+| `--no-telemetry` | off | Force anonymous usage telemetry off (already the default) |Notes:@@ -603,7 +604,10 @@ Options:backends.--mode TEXT Proxy optimization mode. [default: token]--memory Enable persistent memory in the proxy runtime.- --no-telemetry Disable anonymous telemetry in the runtime.+ --telemetry Opt in to anonymous telemetry in the runtime+ (off by default).+ --no-telemetry Force anonymous telemetry off in the runtime+ (already the default).--image TEXT Docker image to use when runtime=docker orpreset=persistent-docker. [default:ghcr.io/chopratejas/headroom:latest]@@ -632,7 +636,8 @@ headroom install apply --preset persistent-docker --scope user| `--region` | unset | Cloud region override || `--mode` | `token` | Proxy optimization mode || `--memory` | off | Enable persistent memory in the managed runtime |-| `--no-telemetry` | off | Disable anonymous telemetry |+| `--telemetry` | off | Opt in to anonymous telemetry (off by default) |+| `--no-telemetry` | off | Force anonymous telemetry off (already the default) || `--image` | `ghcr.io/chopratejas/headroom:latest` | Docker image for Docker-backed installs |`apply` stores a manifest underdiff --git a/wiki/metrics.md b/wiki/metrics.mdindex 7408558c1..550e366ad 100644--- a/wiki/metrics.md+++ b/wiki/metrics.md@@ -248,7 +248,7 @@ Headroom's managed OTEL exporters are intentionally scoped to Headroom's own insHeadroom has two separate systems:-- `HEADROOM_TELEMETRY` / `--no-telemetry` controls the privacy-preserving anonymous data-flywheel beacon and TOIN-related aggregate reporting.+- `HEADROOM_TELEMETRY` / `--telemetry` / `--no-telemetry` controls the privacy-preserving anonymous data-flywheel beacon and TOIN-related aggregate reporting. It is **off by default** (opt-in): set `HEADROOM_TELEMETRY=on` or pass `--telemetry` to enable it.- `HEADROOM_OTEL_*` controls operational OTEL metric export.They are independent by design so you can disable the anonymous beacon while keeping OTEL metrics enabled, or vice versa.diff --git a/wiki/proxy.md b/wiki/proxy.mdindex fec3f86dd..d8f6994c4 100644--- a/wiki/proxy.md+++ b/wiki/proxy.md@@ -36,7 +36,7 @@ OPENAI_BASE_URL=http://localhost:8787/v1 your-app`headroom wrap copilot` uses Copilot CLI's BYOK provider settings under the hood. In `provider-type=auto`, it chooses Headroom's Anthropic route for the default proxy backend and the OpenAI-compatible `/v1` route for translated backends such as `anyllm` and LiteLLM.-Anonymous aggregate telemetry is enabled by default. Opt out with `HEADROOM_TELEMETRY=off` or `headroom proxy --no-telemetry`. Downstream apps can set `HEADROOM_SDK=headroom-app` to override the anonymous telemetry `sdk` label; the default remains `proxy`.+Anonymous aggregate telemetry is **off by default** (opt-in). Opt in with `HEADROOM_TELEMETRY=on` or `headroom proxy --telemetry`. Downstream apps can set `HEADROOM_SDK=headroom-app` to override the anonymous telemetry `sdk` label; the default remains `proxy`.Operational OTEL metrics are configured separately and are **off by default**. Install `headroom-ai[proxy,otel]` and set: