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(install): keep the HuggingFace cache on a writable mount in Docker presets (#4207) (#4209)
Shivam Maurya7b6cb7790552
diff --git a/docker/docker-compose.native.yml b/docker/docker-compose.native.ymlindex aeac66f18..d2f32920e 100644--- a/docker/docker-compose.native.yml+++ b/docker/docker-compose.native.yml@@ -7,6 +7,11 @@ services:tty: trueenvironment:HOME: /tmp/headroom-home+ # Docker creates /tmp/headroom-home as root:root, so $HOME is not+ # writable by the --user the container runs as (issue #4207). Keep the+ # HuggingFace/XDG caches on the bind-mounted workspace instead.+ HF_HOME: /tmp/headroom-home/.headroom/cache/huggingface+ XDG_CACHE_HOME: /tmp/headroom-home/.headroom/cache# Canonical Headroom filesystem contract (issue #175). Forwarded into# the container so the proxy resolves state/config to the bind-mounted# /tmp/headroom-home/.headroom path. HEADROOM_WORKSPACE (above) remains@@ -28,6 +33,9 @@ services:restart: unless-stoppedenvironment:HOME: /tmp/headroom-home+ # See the `cli` service above (issue #4207).+ HF_HOME: /tmp/headroom-home/.headroom/cache/huggingface+ XDG_CACHE_HOME: /tmp/headroom-home/.headroom/cacheHEADROOM_HOST: 0.0.0.0HEADROOM_PROXY_TOKEN: ${HEADROOM_PROXY_TOKEN:-}# The container binds 0.0.0.0 so the loopback publication below can reachdiff --git a/headroom/install/runtime.py b/headroom/install/runtime.pyindex 2c0135844..1c50b5ae4 100644--- a/headroom/install/runtime.py+++ b/headroom/install/runtime.py@@ -160,6 +160,18 @@ def build_runtime_command(manifest: DeploymentManifest) -> list[str]:container_home,"--env",f"HOME={container_home}",+ # Docker creates the parent of every bind mount as root:root when it is+ # absent from the image, so $HOME itself is NOT writable by the+ # --user <host-uid> process (issue #4207). Anything that writes under+ # $HOME outside the mounts then fails, which is what breaks the+ # HuggingFace download of the Kompress model. Point the HuggingFace and+ # XDG caches at the bind-mounted workspace instead: that directory+ # belongs to the host user the container runs as, so it is writable,+ # and it survives `docker rm` of the container.+ "--env",+ f"HF_HOME={container_home}/.headroom/cache/huggingface",+ "--env",+ f"XDG_CACHE_HOME={container_home}/.headroom/cache","--env","PYTHONUNBUFFERED=1",# Canonical Headroom filesystem contract (issue #175).diff --git a/headroom/transforms/kompress_compressor.py b/headroom/transforms/kompress_compressor.pyindex 766373370..cd23c5b5b 100644--- a/headroom/transforms/kompress_compressor.py+++ b/headroom/transforms/kompress_compressor.py@@ -905,8 +905,9 @@ def _create_onnx_session(raise refusedif not allow_download and cache_miss:raise KompressModelNotCached(model_id) from last_err+ detail = f": {last_err}" if last_err is not None else ""raise FileNotFoundError(- f"No loadable ONNX artifact in {model_id}; tried {_onnx_filename_candidates()}"+ f"No loadable ONNX artifact in {model_id}; tried {_onnx_filename_candidates()}{detail}") from last_err@@ -1241,6 +1242,7 @@ def _load_kompress(# Auto mode: preserve stable default behavior. This avoids changing# compression quality/perf characteristics for existing installs while# allowing opt-in MPS/CoreML experiments via HEADROOM_KOMPRESS_BACKEND.+ onnx_error: Exception | None = Noneif _is_onnx_available():try:return _load_kompress_onnx(model_id, use_coreml=False, allow_download=allow_download)@@ -1250,11 +1252,24 @@ def _load_kompress(if not allow_download:raiseexcept Exception as e:+ onnx_error = elogger.warning("ONNX load failed for %s, trying PyTorch: %s", model_id, e)if _is_pytorch_available():return _load_kompress_pytorch(model_id, device, allow_download=allow_download)+ if onnx_error is not None:+ # onnxruntime IS installed and was tried, but loading failed. The+ # "requires onnxruntime or torch" message would be a lie that sends the+ # operator to reinstall extras that are already present (issue #4207:+ # an unwritable $HOME fails the HuggingFace download, which surfaces as+ # "No loadable ONNX artifact" and was then reported as a missing+ # dependency). Re-raise the real error instead, chained so the original+ # traceback is preserved.+ raise RuntimeError(+ f"Kompress ONNX backend failed for {model_id}: {onnx_error}"+ ) from onnx_error+raise ImportError("Kompress requires onnxruntime or torch. Install with: pip install headroom-ai[proxy]")diff --git a/scripts/install.sh b/scripts/install.shindex bbd10bb36..6e7143a39 100644--- a/scripts/install.sh+++ b/scripts/install.sh@@ -122,6 +122,12 @@ append_common_container_args() {ensure_host_dirsref+=(-w /workspace)ref+=(--env "HOME=${HEADROOM_CONTAINER_HOME}")+ # Docker creates ${HEADROOM_CONTAINER_HOME} as root:root when the image has+ # no such directory, so $HOME is not writable by the --user <host-uid>+ # process (issue #4207). Keep the HuggingFace/XDG caches on the+ # bind-mounted workspace, which the host user owns.+ ref+=(--env "HF_HOME=${HEADROOM_CONTAINER_HOME}/.headroom/cache/huggingface")+ ref+=(--env "XDG_CACHE_HOME=${HEADROOM_CONTAINER_HOME}/.headroom/cache")ref+=(--env "PYTHONUNBUFFERED=1")# Canonical Headroom filesystem contract (issue #175) — forward into the# container so the proxy resolves state/config to the bind-mounted path.diff --git a/tests/test_install/test_runtime.py b/tests/test_install/test_runtime.pyindex 8d72bcf42..f1e6e31d8 100644--- a/tests/test_install/test_runtime.py+++ b/tests/test_install/test_runtime.py@@ -118,6 +118,47 @@ def test_build_runtime_command_for_docker_includes_deployment_env()+def test_build_runtime_command_keeps_hf_cache_on_the_writable_mount(+ monkeypatch, tmp_path: Path+) -> None:+ """Issue #4207: ``$HOME`` is created root-owned by Docker but the container+ runs as the host uid, so the HuggingFace cache must live on a bind mount the+ host user owns. Otherwise the Kompress model download dies with+ ``Permission denied``.+ """+ monkeypatch.setattr(Path, "home", lambda: tmp_path)+ manifest = DeploymentManifest(+ profile="default",+ preset="persistent-docker",+ runtime_kind="docker",+ supervisor_kind="none",+ scope="user",+ provider_mode="manual",+ targets=["claude"],+ port=8787,+ host="127.0.0.1",+ backend="anthropic",+ image="ghcr.io/headroomlabs-ai/headroom:latest",+ base_env={"HEADROOM_PORT": "8787"},+ proxy_args=["--host", "127.0.0.1", "--port", "8787"],+ )++ command = build_runtime_command(manifest)++ # The cache path sits under the ``~/.headroom`` bind mount, which the host+ # user (and therefore the --user the container runs as) can write.+ hf_home = "HF_HOME=/tmp/headroom-home/.headroom/cache/huggingface"+ xdg_cache = "XDG_CACHE_HOME=/tmp/headroom-home/.headroom/cache"+ assert hf_home in command+ assert xdg_cache in command+ # Both are real --env flags, not stray argv tokens.+ assert command[command.index(hf_home) - 1] == "--env"+ assert command[command.index(xdg_cache) - 1] == "--env"+ # The cache lives under the .headroom mount, so it must not be mounted+ # anywhere Docker would create as root.+ assert f"{_mount_source(str(tmp_path), '.headroom')}:/tmp/headroom-home/.headroom" in command++def test_build_runtime_command_lets_the_host_dashboard_read_its_data(monkeypatch, tmp_path: Path) -> None:diff --git a/tests/test_kompress_failsafe.py b/tests/test_kompress_failsafe.pyindex 973ab7bfc..e51cbe613 100644--- a/tests/test_kompress_failsafe.py+++ b/tests/test_kompress_failsafe.py@@ -609,6 +609,62 @@ def test_all_artifacts_failing_at_run_raises_rather_than_returning_a_dead_sessiokc._create_onnx_session("org/model", ["CPUExecutionProvider"])+def test_no_loadable_artifact_message_carries_the_underlying_error(monkeypatch):+ """Issue #4207: the ONNX loader reported only "No loadable ONNX artifact",+ hiding the Permission denied behind it. The message must show the cause.+ """++ def fake_artifact(model_id, filename, *, allow_network):+ raise PermissionError(13, "Permission denied")++ monkeypatch.setattr(kc, "_hf_artifact", fake_artifact)++ with pytest.raises(FileNotFoundError) as excinfo:+ kc._create_onnx_session("org/model", ["CPUExecutionProvider"])++ assert "No loadable ONNX artifact" in str(excinfo.value)+ assert "Permission denied" in str(excinfo.value)+++def test_onnx_failure_while_onnxruntime_available_reports_the_real_error(monkeypatch):+ """Issue #4207: when onnxruntime IS installed but loading failed, the+ compressor must not claim a missing dependency (which points operators at+ reinstalling extras that are already present). It must surface the real+ failure.+ """+ monkeypatch.setattr(kc, "_is_onnx_available", lambda: True)+ monkeypatch.setattr(kc, "_is_pytorch_available", lambda: False)++ def boom(*args, **kwargs):+ raise FileNotFoundError(+ "No loadable ONNX artifact in org/model; tried ('a.onnx',): "+ "Permission denied (os error 13)"+ )++ monkeypatch.setattr(kc, "_load_kompress_onnx", boom)+ monkeypatch.setattr(kc, "_selected_backend", lambda: "auto")+ kc._kompress_cache.pop("org/model", None)++ with pytest.raises(RuntimeError) as excinfo:+ kc._load_kompress("org/model")++ message = str(excinfo.value)+ assert "requires onnxruntime or torch" not in message+ assert "Permission denied" in message+ assert isinstance(excinfo.value.__cause__, FileNotFoundError)+++def test_missing_dependency_still_reports_install_hint(monkeypatch):+ """The genuine no-backend case keeps the actionable install hint."""+ monkeypatch.setattr(kc, "_is_onnx_available", lambda: False)+ monkeypatch.setattr(kc, "_is_pytorch_available", lambda: False)+ monkeypatch.setattr(kc, "_selected_backend", lambda: "auto")+ kc._kompress_cache.pop("org/model", None)++ with pytest.raises(ImportError, match="onnxruntime or torch"):+ kc._load_kompress("org/model")++# ── Load-stage timings: say where a slow warm-up spent its time ────────────────