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.

feat(docker): forward HEADROOM_WORKSPACE_DIR and HEADROOM_CONFIG_DIR into containers

JerrettDavis4a87753713d3
diff --git a/docker/docker-compose.native.yml b/docker/docker-compose.native.yml
index 040eef07d..916f47d38 100644
--- a/docker/docker-compose.native.yml
+++ b/docker/docker-compose.native.yml
@@ -7,6 +7,12 @@ services:
tty: true
environment:
HOME: /tmp/headroom-home
+ # 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
+ # the Docker bind-mount source and is intentionally different.
+ HEADROOM_WORKSPACE_DIR: /tmp/headroom-home/.headroom
+ HEADROOM_CONFIG_DIR: /tmp/headroom-home/.headroom/config
volumes:
- ${HEADROOM_WORKSPACE:-.}:/workspace
- ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.headroom:/tmp/headroom-home/.headroom
@@ -23,6 +29,10 @@ services:
environment:
HOME: /tmp/headroom-home
HEADROOM_HOST: 0.0.0.0
+ # Canonical Headroom filesystem contract (issue #175). See `cli` service
+ # above for rationale.
+ HEADROOM_WORKSPACE_DIR: /tmp/headroom-home/.headroom
+ HEADROOM_CONFIG_DIR: /tmp/headroom-home/.headroom/config
ports:
- "${HEADROOM_PORT:-8787}:${HEADROOM_PORT:-8787}"
volumes:
diff --git a/e2e/docker-native-install.sh b/e2e/docker-native-install.sh
index 42297e09a..3b046b475 100755
--- a/e2e/docker-native-install.sh
+++ b/e2e/docker-native-install.sh
@@ -85,3 +85,11 @@ curl --fail --silent "http://127.0.0.1:${PORT}/readyz" >/dev/null
"${WRAPPER}" install remove --profile "${PROFILE}"
[[ ! -e "${HOME}/.headroom/deploy/${PROFILE}" ]]
+
+# TODO(issue-175): verify HEADROOM_WORKSPACE_DIR / HEADROOM_CONFIG_DIR make it
+# into the container's env. The wrapper test installs and tears down so the
+# container is gone by the time we could `docker exec`. A follow-up change
+# should assert on the `docker inspect` env list after `install apply` but
+# before `install stop`. Unit tests in tests/test_install/test_runtime.py and
+# tests/test_install/test_native_installers.py already lock the install-time
+# env-forwarding; this e2e hop is nice-to-have, not blocking.
diff --git a/headroom/install/runtime.py b/headroom/install/runtime.py
index 40a7bc497..5a4dae53f 100644
--- a/headroom/install/runtime.py
+++ b/headroom/install/runtime.py
@@ -101,6 +101,11 @@ def build_runtime_command(manifest: DeploymentManifest) -> list[str]:
f"HOME={container_home}",
"--env",
"PYTHONUNBUFFERED=1",
+ # Canonical Headroom filesystem contract (issue #175).
+ "--env",
+ f"HEADROOM_WORKSPACE_DIR={container_home}/.headroom",
+ "--env",
+ f"HEADROOM_CONFIG_DIR={container_home}/.headroom/config",
"--volume",
f"{_mount_source(home, '.headroom')}:{container_home}/.headroom",
"--volume",
diff --git a/scripts/install.ps1 b/scripts/install.ps1
index 424491c2e..5c6c223ed 100644
--- a/scripts/install.ps1
+++ b/scripts/install.ps1
@@ -136,6 +136,11 @@ function Get-SharedDockerArgs {
$args.Add("HOME=$ContainerHome")
$args.Add('--env')
$args.Add('PYTHONUNBUFFERED=1')
+ # Canonical Headroom filesystem contract (issue #175).
+ $args.Add('--env')
+ $args.Add("HEADROOM_WORKSPACE_DIR=$ContainerHome/.headroom")
+ $args.Add('--env')
+ $args.Add("HEADROOM_CONFIG_DIR=$ContainerHome/.headroom/config")
$args.Add('--volume')
$args.Add("${PWD}:/workspace")
$args.Add('--volume')
@@ -325,6 +330,11 @@ function Get-PersistentDockerArgs {
$args.Add("HOME=$ContainerHome")
$args.Add('--env')
$args.Add('PYTHONUNBUFFERED=1')
+ # Canonical Headroom filesystem contract (issue #175).
+ $args.Add('--env')
+ $args.Add("HEADROOM_WORKSPACE_DIR=$ContainerHome/.headroom")
+ $args.Add('--env')
+ $args.Add("HEADROOM_CONFIG_DIR=$ContainerHome/.headroom/config")
$args.Add('--volume')
$args.Add((Join-Path $HostHome '.headroom') + ":$ContainerHome/.headroom")
$args.Add('--volume')
diff --git a/scripts/install.sh b/scripts/install.sh
index 4f9c0c9b2..3296d8fb6 100644
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -137,6 +137,10 @@ append_common_container_args() {
ref+=(-w /workspace)
ref+=(--env "HOME=${HEADROOM_CONTAINER_HOME}")
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.
+ ref+=(--env "HEADROOM_WORKSPACE_DIR=${HEADROOM_CONTAINER_HOME}/.headroom")
+ ref+=(--env "HEADROOM_CONFIG_DIR=${HEADROOM_CONTAINER_HOME}/.headroom/config")
ref+=(-v "${PWD}:/workspace")
ref+=(-v "${HEADROOM_HOST_HOME}/.headroom:${HEADROOM_CONTAINER_HOME}/.headroom")
ref+=(-v "${HEADROOM_HOST_HOME}/.claude:${HEADROOM_CONTAINER_HOME}/.claude")
@@ -300,6 +304,9 @@ append_persistent_container_args() {
ref+=(--workdir "${HEADROOM_CONTAINER_HOME}")
ref+=(--env "HOME=${HEADROOM_CONTAINER_HOME}")
ref+=(--env "PYTHONUNBUFFERED=1")
+ # Canonical Headroom filesystem contract (issue #175).
+ ref+=(--env "HEADROOM_WORKSPACE_DIR=${HEADROOM_CONTAINER_HOME}/.headroom")
+ ref+=(--env "HEADROOM_CONFIG_DIR=${HEADROOM_CONTAINER_HOME}/.headroom/config")
ref+=(-v "${HEADROOM_HOST_HOME}/.headroom:${HEADROOM_CONTAINER_HOME}/.headroom")
ref+=(-v "${HEADROOM_HOST_HOME}/.claude:${HEADROOM_CONTAINER_HOME}/.claude")
ref+=(-v "${HEADROOM_HOST_HOME}/.codex:${HEADROOM_CONTAINER_HOME}/.codex")
diff --git a/tests/test_install/test_native_installers.py b/tests/test_install/test_native_installers.py
index b83265580..b986ca66d 100644
--- a/tests/test_install/test_native_installers.py
+++ b/tests/test_install/test_native_installers.py
@@ -379,6 +379,10 @@ def test_bash_native_installer_supports_persistent_docker_lifecycle(tmp_path: Pa
call for call in docker_calls if call[:2] == ["run", "-d"] and "--name" in call
)
assert "/tmp/headroom-home/.headroom/memory.db" in install_call
+ # Canonical filesystem contract env vars (issue #175) forwarded into
+ # the container so the proxy resolves state/config to the bind mount.
+ assert "HEADROOM_WORKSPACE_DIR=/tmp/headroom-home/.headroom" in install_call
+ assert "HEADROOM_CONFIG_DIR=/tmp/headroom-home/.headroom/config" in install_call
status_result = _run(
[str(wrapper), "install", "status", "--profile", "smoke"],
@@ -627,6 +631,9 @@ def test_powershell_native_installer_supports_persistent_docker_lifecycle(tmp_pa
call for call in docker_calls if call[:2] == ["run", "-d"] and "--name" in call
)
assert "/tmp/headroom-home/.headroom/memory.db" in install_call
+ # Canonical filesystem contract env vars (issue #175).
+ assert "HEADROOM_WORKSPACE_DIR=/tmp/headroom-home/.headroom" in install_call
+ assert "HEADROOM_CONFIG_DIR=/tmp/headroom-home/.headroom/config" in install_call
status_result = _run(
[
diff --git a/tests/test_install/test_runtime.py b/tests/test_install/test_runtime.py
index ee8821e41..da0137143 100644
--- a/tests/test_install/test_runtime.py
+++ b/tests/test_install/test_runtime.py
@@ -41,6 +41,10 @@ def test_build_runtime_command_for_docker_includes_deployment_env(
assert "HEADROOM_DEPLOYMENT_PRESET=persistent-docker" in joined
assert "127.0.0.1:8787:8787" in joined
assert "ghcr.io/chopratejas/headroom:latest" in command
+ # Canonical Headroom filesystem contract (issue #175) forwarded into
+ # the container.
+ assert "HEADROOM_WORKSPACE_DIR=/tmp/headroom-home/.headroom" in command
+ assert "HEADROOM_CONFIG_DIR=/tmp/headroom-home/.headroom/config" in command
def test_build_runtime_command_for_docker_matches_wrapper_parity(