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): preserve host file ownership with rootless Podman (#3592)

William Echo21accecc9803
diff --git a/docs/content/docs/persistent-installs.mdx b/docs/content/docs/persistent-installs.mdx
index e00c2f8d2..fd1c33195 100644
--- a/docs/content/docs/persistent-installs.mdx
+++ b/docs/content/docs/persistent-installs.mdx
@@ -60,6 +60,23 @@ This uses Docker's restart policy instead of an OS supervisor.
If you are using the Docker-native host wrapper instead of a Python install, you can use `headroom install apply|status|start|stop|restart|remove` for the `persistent-docker` preset directly from the installed wrapper. Service/task installs and provider/user/system mutation flows still belong to the Python-native CLI.
+### Rootless Podman file ownership
+
+For the Python-native `persistent-docker` preset, if `docker` is a Podman wrapper
+script rather than a symlink, set `HEADROOM_CONTAINER_RUNTIME=podman` in the
+installer/runtime environment so it selects the Podman path.
+
+On Linux the Podman command combines `--userns=keep-id` with an
+explicit `--user` using the invoking user's UID and GID. Both are needed on
+Podman versions that honor the image's `USER root` even with `keep-id`: the
+namespace preserves the host mapping, and the process user keeps newly created
+files owned by the host user. The configured image is not changed.
+
+Restart the deployment with the updated installer to use these flags. This
+prevents new ownership mismatches; it does not repair files created by an older
+container. Inspect and restore ownership of affected files separately before
+restarting if the host user can no longer read them.
+
## Command surface
```text
diff --git a/headroom/install/runtime.py b/headroom/install/runtime.py
index 5288cdc74..2abdcd9aa 100644
--- a/headroom/install/runtime.py
+++ b/headroom/install/runtime.py
@@ -162,14 +162,17 @@ def build_runtime_command(manifest: DeploymentManifest) -> list[str]:
if docker_gpus:
command.extend(["--gpus", docker_gpus])
if not _is_windows():
- if _container_runtime_is_podman():
- # Rootless Podman maps the host user to container UID 0, so --user
- # would map to a subordinate UID that owns none of the bind mounts and
- # every write into ~/.headroom fails (#2804). keep-id maps the host
- # user to the same UID inside the container, keeping the mounts
- # writable. Docker maps UIDs 1:1, so --user stays correct there.
+ podman = _container_runtime_is_podman()
+ if podman:
+ # keep-id maps the host UID/GID to the same IDs in the container;
+ # --user alone would select subordinate host IDs (#2804). Also set
+ # the process user below: Podman versions such as 5.4.2 otherwise
+ # honor USER root from the image, creating files as a subordinate
+ # host UID even with keep-id (#3569). Docker already maps IDs 1:1.
command.append("--userns=keep-id")
- else:
+ # macOS Podman runs remotely in a VM whose user IDs may differ from
+ # the client's; retain its existing keep-id-only behavior.
+ if not podman or sys.platform.startswith("linux"):
getuid = getattr(os, "getuid", None)
getgid = getattr(os, "getgid", None)
if callable(getuid) and callable(getgid):
diff --git a/tests/test_install/test_runtime.py b/tests/test_install/test_runtime.py
index 8b5e08ed4..4b254cd45 100644
--- a/tests/test_install/test_runtime.py
+++ b/tests/test_install/test_runtime.py
@@ -305,14 +305,21 @@ def test_build_runtime_command_python_and_docker_user(monkeypatch, tmp_path: Pat
assert "--userns=keep-id" not in command
-def test_build_runtime_command_podman_uses_keep_id_not_user(monkeypatch, tmp_path: Path) -> None:
- """Under rootless Podman, --user <host-uid>:<host-gid> selects a subordinate
- UID that owns none of the bind mounts, so writes into ~/.headroom fail. The
- command must use --userns=keep-id and drop --user instead (#2804)."""
[email protected]("platform", ["linux", "darwin", "win32"])
[email protected]("uid,gid", [(1000, 1001), (1007, 1013)])
[email protected]("image", ["ghcr.io/headroomlabs-ai/headroom:latest", "custom:nonroot"])
+def test_build_runtime_command_podman_preserves_host_identity(
+ monkeypatch, tmp_path: Path, uid: int, gid: int, image: str, platform: str
+) -> None:
+ """keep-id needs an explicit process user when the image declares USER root.
+
+ Together the flags select the host identity, without reverting to the
+ subordinate-ID mapping caused by --user alone (#2804, #3569).
+ """
monkeypatch.setattr(Path, "home", lambda: tmp_path)
- monkeypatch.setattr("headroom.install.runtime.sys.platform", "linux")
- monkeypatch.setattr("headroom.install.runtime.os.getuid", lambda: 1000, raising=False)
- monkeypatch.setattr("headroom.install.runtime.os.getgid", lambda: 1001, raising=False)
+ monkeypatch.setattr("headroom.install.runtime.sys.platform", platform)
+ monkeypatch.setattr("headroom.install.runtime.os.getuid", lambda: uid, raising=False)
+ monkeypatch.setattr("headroom.install.runtime.os.getgid", lambda: gid, raising=False)
monkeypatch.setenv("HEADROOM_CONTAINER_RUNTIME", "podman")
manifest = DeploymentManifest(
profile="default",
@@ -325,14 +332,18 @@ def test_build_runtime_command_podman_uses_keep_id_not_user(monkeypatch, tmp_pat
port=8787,
host="127.0.0.1",
backend="anthropic",
- image="ghcr.io/headroomlabs-ai/headroom:latest",
+ image=image,
base_env={"HEADROOM_PORT": "8787"},
proxy_args=["--host", "127.0.0.1", "--port", "8787"],
)
command = build_runtime_command(manifest)
- assert "--userns=keep-id" in command
- assert "--user" not in command
- assert "1000:1001" not in command
+ assert ("--userns=keep-id" in command) == (platform != "win32")
+ assert image in command
+ if platform == "linux":
+ assert command[command.index("--user") + 1] == f"{uid}:{gid}"
+ assert command.index("--user") < command.index(image)
+ else:
+ assert "--user" not in command
def test_read_pid_handles_invalid_content(monkeypatch, tmp_path: Path) -> None: