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(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.yml
index aeac66f18..d2f32920e 100644
--- a/docker/docker-compose.native.yml
+++ b/docker/docker-compose.native.yml
@@ -7,6 +7,11 @@ services:
tty: true
environment:
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-stopped
environment:
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/cache
HEADROOM_HOST: 0.0.0.0
HEADROOM_PROXY_TOKEN: ${HEADROOM_PROXY_TOKEN:-}
# The container binds 0.0.0.0 so the loopback publication below can reach
diff --git a/headroom/install/runtime.py b/headroom/install/runtime.py
index 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.py
index 766373370..cd23c5b5b 100644
--- a/headroom/transforms/kompress_compressor.py
+++ b/headroom/transforms/kompress_compressor.py
@@ -905,8 +905,9 @@ def _create_onnx_session(
raise refused
if 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 = None
if _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:
raise
except Exception as e:
+ onnx_error = e
logger.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.sh
index bbd10bb36..6e7143a39 100644
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -122,6 +122,12 @@ append_common_container_args() {
ensure_host_dirs
ref+=(-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.py
index 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.py
index 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_sessio
kc._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 ────────────────