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(proxy)!: read HEADROOM_LICENSE and make usage reporting opt-in (#3857)

Tejas Chopra746038991cf2
diff --git a/docs/content/docs/proxy.mdx b/docs/content/docs/proxy.mdx
index f4476b938..d08755278 100644
--- a/docs/content/docs/proxy.mdx
+++ b/docs/content/docs/proxy.mdx
@@ -341,6 +341,8 @@ with a privileged job.
| `HEADROOM_PROXY_TOKEN` | none | Require a bearer token (`X-Headroom-Proxy-Token`) from non-loopback callers. |
| `HEADROOM_COMPRESS_ALLOW_REMOTE` | `false` | Allow non-loopback callers to reach [`POST /v1/compress`](#post-v1compress) and `POST /v1/usage`. Required to run Headroom as a remote gateway/sidecar; without it remote callers get `404`. |
| `--offline` / `HEADROOM_OFFLINE` | `false` | Air-gap mode: hard-disable **all** egress (telemetry, update checks, license reporting, model downloads). |
+| `HEADROOM_LICENSE` | unset | Licence token, read by core and every licensed extension. `HEADROOM_LICENSE_KEY` is a deprecated alias for one release and logs a warning. A licence on its own sends nothing to Headroom. |
+| `HEADROOM_USAGE_REPORTING` | `false` | Set `1` to let the proxy validate the licence and post aggregate usage counts (no content) to the Headroom cloud. Off unless set; `HEADROOM_OFFLINE` still overrides it. |
| `--stateless` / `HEADROOM_STATELESS` | `false` | Keep all state in memory; no filesystem writes (disables logs, memory, TOIN). |
| `HEADROOM_STRIP_INTERNAL_HEADERS` | `enabled` | Strip internal `x-headroom-*` headers before forwarding upstream. |
| `HEADROOM_TLS_STRICT` | strict | Set `0` to relax CA-constraint checks behind a corporate TLS-inspection proxy. |
diff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.py
index fdbcf34a2..30132ac0f 100644
--- a/headroom/cli/proxy.py
+++ b/headroom/cli/proxy.py
@@ -1304,8 +1304,13 @@ def proxy(
if is_stateless:
os.environ["HEADROOM_TOIN_BACKEND"] = "none"
- # License key for managed/enterprise deployments (optional)
- license_key = os.environ.get("HEADROOM_LICENSE_KEY")
+ # Licence token (HEADROOM_LICENSE; HEADROOM_LICENSE_KEY is a deprecated
+ # alias). Having one set never enables outbound usage reporting: that
+ # needs the explicit HEADROOM_USAGE_REPORTING=1 opt-in.
+ from headroom.license_env import resolve_license_token, usage_reporting_enabled
+
+ license_key = resolve_license_token()
+ usage_reporting = usage_reporting_enabled()
# Qdrant connection for the qdrant-neo4j backend. CLI flags default
# to None; when omitted we let ProxyConfig's default_factory resolve
@@ -1478,6 +1483,7 @@ def proxy(
anyllm_provider=effective_anyllm_provider,
# License / Usage Reporting (managed/enterprise)
license_key=license_key,
+ usage_reporting=usage_reporting,
# Stateless mode: disable all filesystem writes
stateless=is_stateless,
# Unit 4: bounded pre-upstream concurrency on the Anthropic HTTP
@@ -1503,9 +1509,16 @@ def proxy(
if config.memory_enabled:
memory_status = "ENABLED (multi-provider)"
- license_status = "OSS (no license key)"
+ license_status = "OSS (no licence)"
if license_key:
- license_status = f"MANAGED (key={license_key[:8]}...)"
+ # Never print licence material, not even a prefix.
+ if not usage_reporting:
+ reporting = "off"
+ elif config.offline:
+ reporting = "suppressed by HEADROOM_OFFLINE"
+ else:
+ reporting = "ON"
+ license_status = f"LICENSED (usage reporting {reporting})"
provider_api_targets = resolve_api_targets(config.provider_api_overrides)
anthropic_url = provider_api_targets.anthropic
diff --git a/headroom/license_env.py b/headroom/license_env.py
new file mode 100644
index 000000000..142769310
--- /dev/null
+++ b/headroom/license_env.py
@@ -0,0 +1,73 @@
+"""One licence variable, and an explicit switch for usage reporting.
+
+Headroom reads its licence token from ``HEADROOM_LICENSE``. Every licensed
+extension reads the same variable, so core does too.
+
+``HEADROOM_LICENSE_KEY`` was the older name read only by core's cloud usage
+reporter. It is still honoured for one release as a deprecated alias, with a
+warning, so existing managed deployments keep their licence while they rename.
+
+Having a licence set never turns on outbound reporting by itself. The usage
+reporter validates the licence against the Headroom cloud and posts aggregate
+usage counts; it runs only when the operator also sets
+``HEADROOM_USAGE_REPORTING=1``. ``HEADROOM_OFFLINE`` still suppresses it.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Mapping
+
+logger = logging.getLogger("headroom.license_env")
+
+LICENSE_ENV = "HEADROOM_LICENSE"
+DEPRECATED_LICENSE_ENV = "HEADROOM_LICENSE_KEY"
+USAGE_REPORTING_ENV = "HEADROOM_USAGE_REPORTING"
+
+_TRUE = frozenset({"1", "true", "yes", "on"})
+
+
+def _clean(value: str | None) -> str | None:
+ if value is None:
+ return None
+ value = value.strip()
+ return value or None
+
+
+def resolve_license_token(environ: Mapping[str, str] | None = None) -> str | None:
+ """Return the licence token, preferring ``HEADROOM_LICENSE``.
+
+ Falls back to the deprecated ``HEADROOM_LICENSE_KEY`` with a warning. When
+ both are set to different values, ``HEADROOM_LICENSE`` wins and a warning
+ says so, because silently picking one would hide a misconfiguration.
+ """
+ env = os.environ if environ is None else environ
+ current = _clean(env.get(LICENSE_ENV))
+ legacy = _clean(env.get(DEPRECATED_LICENSE_ENV))
+
+ if current and legacy and current != legacy:
+ logger.warning(
+ "event=license_env_conflict using=%s ignored=%s hint=unset_%s_it_is_deprecated",
+ LICENSE_ENV,
+ DEPRECATED_LICENSE_ENV,
+ DEPRECATED_LICENSE_ENV,
+ )
+ return current
+ if current:
+ return current
+ if legacy:
+ logger.warning(
+ "event=license_env_deprecated variable=%s replacement=%s "
+ "hint=rename_it_the_alias_is_removed_in_the_next_release",
+ DEPRECATED_LICENSE_ENV,
+ LICENSE_ENV,
+ )
+ return legacy
+ return None
+
+
+def usage_reporting_enabled(environ: Mapping[str, str] | None = None) -> bool:
+ """True only when the operator explicitly opted in to usage reporting."""
+ env = os.environ if environ is None else environ
+ return (env.get(USAGE_REPORTING_ENV) or "").strip().lower() in _TRUE
diff --git a/headroom/proxy/models.py b/headroom/proxy/models.py
index e872e784b..add92f0e2 100644
--- a/headroom/proxy/models.py
+++ b/headroom/proxy/models.py
@@ -466,8 +466,11 @@ class ProxyConfig:
memory_bridge_auto_import: bool = False
memory_bridge_export_path: str = ""
- # License / Usage Reporting
+ # Licence / usage reporting. ``license_key`` holds the HEADROOM_LICENSE
+ # token. The cloud usage reporter runs only when ``usage_reporting`` is
+ # also true (HEADROOM_USAGE_REPORTING=1); a licence alone sends nothing.
license_key: str | None = None
+ usage_reporting: bool = False
license_cloud_url: str = "https://app.headroomlabs.ai"
license_report_interval: int = 300
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index 9f73ef592..19ca411db 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -1425,11 +1425,13 @@ class HeadroomProxy(
"hint=bridge_syncs_only_the_legacy_DB_today_per-project_bridge_follow-up_planned"
)
- # Usage Reporter (license validation + phone-home for managed/enterprise).
+ # Usage Reporter (licence validation + phone-home for managed deployments).
+ # Explicit opt-in only: a licence being present must not start outbound
+ # reporting on its own (HEADROOM_USAGE_REPORTING=1 is required).
# Suppressed entirely in offline mode — the air-gap switch must stop all
- # egress, including license phone-home, even when a key is configured.
+ # egress, including licence phone-home, even when opted in.
self.usage_reporter: UsageReporter | None = None
- if config.license_key and not (config.offline or is_offline()):
+ if config.license_key and config.usage_reporting and not (config.offline or is_offline()):
from headroom.telemetry.reporter import UsageReporter
self.usage_reporter = UsageReporter(
diff --git a/run-all-plugins.sh b/run-all-plugins.sh
index f8b9b2ec9..2570c5a65 100755
--- a/run-all-plugins.sh
+++ b/run-all-plugins.sh
@@ -69,9 +69,9 @@ set -a; # shellcheck disable=SC1090
source "$ENV_TXT"; set +a
# ── 4. plugin license (Ed25519, offline, wildcard) ────────────────────────────
-# HEADROOM_LICENSE + HEADROOM_LICENSE_PUBKEY. This is SEPARATE from the OSS cloud
-# key (HEADROOM_LICENSE_KEY) — the banner will still say "OSS (no license key)",
-# but each plugin prints "license accepted". Fallback: skip verification entirely.
+# HEADROOM_LICENSE + HEADROOM_LICENSE_PUBKEY. Core and every plugin read the same
+# HEADROOM_LICENSE; the banner says "LICENSED (usage reporting off)" unless
+# HEADROOM_USAGE_REPORTING=1 is also set. Fallback: skip verification entirely.
if [ -f "$PLUGINS_ENV" ]; then
set -a; # shellcheck disable=SC1090
source "$PLUGINS_ENV"; set +a
diff --git a/tests/test_license_env_and_usage_reporting.py b/tests/test_license_env_and_usage_reporting.py
new file mode 100644
index 000000000..f71d33e81
--- /dev/null
+++ b/tests/test_license_env_and_usage_reporting.py
@@ -0,0 +1,142 @@
+"""D-12: one licence variable, and usage reporting only on explicit opt-in.
+
+Before this change core read ``HEADROOM_LICENSE_KEY`` while every extension
+read ``HEADROOM_LICENSE``, and the cloud usage reporter started whenever a key
+was present. Unifying the variable without the opt-in would have switched the
+reporter on in every licensed enterprise deployment. These tests pin both
+halves: the variable is ``HEADROOM_LICENSE`` (old name is a warned alias), and
+nothing is sent to the Headroom cloud unless ``HEADROOM_USAGE_REPORTING=1``.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import httpx
+import pytest
+
+pytest.importorskip("fastapi")
+
+from fastapi.testclient import TestClient # noqa: E402
+
+from headroom.license_env import ( # noqa: E402
+ resolve_license_token,
+ usage_reporting_enabled,
+)
+from headroom.proxy.models import ProxyConfig # noqa: E402
+from headroom.proxy.server import create_app # noqa: E402
+
+CLOUD = "https://cloud.headroom.test"
+
+
+class _Capture(logging.Handler):
+ def __init__(self) -> None:
+ super().__init__(level=logging.DEBUG)
+ self.messages: list[str] = []
+
+ def emit(self, record: logging.LogRecord) -> None:
+ self.messages.append(record.getMessage())
+
+
+def license_log():
+ # Attach directly: headroom.* loggers are not reliably visible to caplog.
+ logger = logging.getLogger("headroom.license_env")
+ handler = _Capture()
+ logger.addHandler(handler)
+ try:
+ yield handler
+ finally:
+ logger.removeHandler(handler)
+
+
+# --- variable resolution -------------------------------------------------
+
+
+def test_headroom_license_is_the_variable(license_log):
+ assert resolve_license_token({"HEADROOM_LICENSE": "tok-new"}) == "tok-new"
+ assert license_log.messages == []
+
+
+def test_legacy_name_is_an_alias_with_a_warning(license_log):
+ assert resolve_license_token({"HEADROOM_LICENSE_KEY": "tok-old"}) == "tok-old"
+ assert any("license_env_deprecated" in m for m in license_log.messages)
+
+
+def test_new_name_wins_on_conflict_and_says_so(license_log):
+ env = {"HEADROOM_LICENSE": "tok-new", "HEADROOM_LICENSE_KEY": "tok-old"}
+ assert resolve_license_token(env) == "tok-new"
+ assert any("license_env_conflict" in m for m in license_log.messages)
+
+
+def test_same_value_under_both_names_is_quiet(license_log):
+ env = {"HEADROOM_LICENSE": "tok", "HEADROOM_LICENSE_KEY": "tok"}
+ assert resolve_license_token(env) == "tok"
+ assert license_log.messages == []
+
+
+def test_blank_values_mean_unset():
+ assert resolve_license_token({"HEADROOM_LICENSE": " ", "HEADROOM_LICENSE_KEY": ""}) is None
+
+
[email protected]("value", ["1", "true", "YES", " on "])
+def test_usage_reporting_opt_in_values(value):
+ assert usage_reporting_enabled({"HEADROOM_USAGE_REPORTING": value}) is True
+
+
[email protected]("value", [None, "", "0", "false", "no", "off", "maybe"])
+def test_usage_reporting_is_off_unless_opted_in(value):
+ env = {} if value is None else {"HEADROOM_USAGE_REPORTING": value}
+ assert usage_reporting_enabled(env) is False
+
+
+# --- outbound traffic ----------------------------------------------------
+
+
+def cloud_calls(monkeypatch):
+ """Record every request any httpx.AsyncClient sends to the fake cloud."""
+ calls: list[httpx.Request] = []
+ real_send = httpx.AsyncClient.send
+
+ async def send(self, request, *args, **kwargs):
+ if str(request.url).startswith(CLOUD):
+ calls.append(request)
+ return httpx.Response(200, json={"status": "active"}, request=request)
+ return await real_send(self, request, *args, **kwargs)
+
+ monkeypatch.setattr(httpx.AsyncClient, "send", send)
+ monkeypatch.delenv("HEADROOM_OFFLINE", raising=False)
+ return calls
+
+
+def _config(**overrides) -> ProxyConfig:
+ return ProxyConfig(
+ license_key="tok-licensed",
+ license_cloud_url=CLOUD,
+ license_report_interval=3600,
+ optimize=False,
+ **overrides,
+ )
+
+
+def test_licence_alone_sends_nothing(cloud_calls):
+ app = create_app(_config())
+ with TestClient(app) as client:
+ client.get("/livez")
+ assert cloud_calls == []
+
+
+def test_opt_in_reports_to_the_cloud(cloud_calls):
+ app = create_app(_config(usage_reporting=True))
+ with TestClient(app) as client:
+ client.get("/livez")
+ assert [c.url.path for c in cloud_calls][:1] == ["/v1/license/validate"]
+
+
+def test_offline_beats_opt_in(cloud_calls, monkeypatch):
+ monkeypatch.setenv("HEADROOM_OFFLINE", "1")
+ app = create_app(_config(usage_reporting=True))
+ with TestClient(app) as client:
+ client.get("/livez")
+ assert cloud_calls == []