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(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.mdxindex 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.pyindex 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 writesstateless=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.anthropicdiff --git a/headroom/license_env.py b/headroom/license_env.pynew file mode 100644index 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 _TRUEdiff --git a/headroom/proxy/models.py b/headroom/proxy/models.pyindex e872e784b..add92f0e2 100644--- a/headroom/proxy/models.py+++ b/headroom/proxy/models.py@@ -466,8 +466,11 @@ class ProxyConfig:memory_bridge_auto_import: bool = Falsememory_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 = Falselicense_cloud_url: str = "https://app.headroomlabs.ai"license_report_interval: int = 300diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 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 UsageReporterself.usage_reporter = UsageReporter(diff --git a/run-all-plugins.sh b/run-all-plugins.shindex f8b9b2ec9..2570c5a65 100755--- a/run-all-plugins.sh+++ b/run-all-plugins.sh@@ -69,9 +69,9 @@ set -a; # shellcheck disable=SC1090source "$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" ]; thenset -a; # shellcheck disable=SC1090source "$PLUGINS_ENV"; set +adiff --git a/tests/test_license_env_and_usage_reporting.py b/tests/test_license_env_and_usage_reporting.pynew file mode 100644index 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 == []