feat(nix): container-aware CLI — auto-route into managed container

[alt-glitch]

Summary

• When container.enable = true, the host hermes CLI transparently routes all subcommands into the managed Docker/Podman container via docker exec
• New container.hostUsers option creates a ~/.hermes symlink bridge to the service stateDir, unifying sessions/config/memories between host and container
• Users in hostUsers are auto-added to the hermes group
• Retry with spinner on container-down (TTY: 5s, non-TTY: 10s), hard fail instead of silent fallback
• HERMES_DEV=1 env var bypasses routing for development
• Cleanup on disable: removes symlinks, .container-mode, stops service

Depends on #7488 (mautrix migration) for a clean nix build — the atomicwrites sdist failure from matrix-nio[e2e] is resolved there.

Test plan

• 16 unit tests passing (container detection, metadata parsing, exec construction, retry behavior)
• NixOS module parses (nix-instantiate --parse)
• Smoke tested on live NixOS system: hermes version, hermes config, hermes sessions list, hermes chat -q, tool calling, session persistence
• HERMES_DEV=1 bypass verified (host Python 3.12 vs container Python 3.11)
• Routing is invisible (no stderr messages)

[github-actions]

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py

---

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

[alt-glitch]

fixes #7380

[alt-glitch]

@BugBot review

[cursor]

PR Summary

Medium Risk
Routes all host CLI invocations through docker/podman exec based on a state-file marker and adds activation-time symlink/user management, which could break interactive workflows if container metadata or runtime visibility is misconfigured. Uses sudo probing and retry behavior that changes failure modes for scripts and terminals.

Overview
Adds a container-aware host CLI path for NixOS container deployments: when HERMES_HOME/.container-mode is present, hermes now transparently re-execs all subcommands into the managed Docker/Podman container (with env passthrough, TTY handling, retry-on-container failures, and optional sudo fallback when the container is only visible to root).

Extends the NixOS module with container.hostUsers to auto-add interactive users to the Hermes group and to create/cleanup a ~/.hermes symlink bridge to the service state directory; the activation script also writes/removes the .container-mode metadata file used for routing.

Adds comprehensive unit tests for container detection/metadata parsing/exec retry logic and updates Nix setup docs to describe routing behavior, HERMES_DEV=1 bypass, and Podman sudo requirements.

^{Reviewed by Cursor Bugbot for commit 38277a6. Configure here.}

[nousr]

this branch currently does not seem to work for me.

error: Cannot build '/nix/store/07q2i2awg59mdhjdshj5533g0s6m8fsg-atomicwrites-1.4.1.drv'.
       Reason: builder failed with exit code 2.
       Output paths:
         /nix/store/v766f9izcyprbrmqj0hrc558s0wc16lq-atomicwrites-1.4.1
       Last 25 log lines:
       > DEBUG Proceeding without build isolation
       > DEBUG Locking the source tree for setuptools
       > DEBUG Acquired exclusive lock for `/build/atomicwrites-1.4.1`
       > DEBUG Calling `setuptools.build_meta:__legacy__.build_wheel("/build/atomicwrites-1.4.1/dist/", {}, None)`
       > Traceback (most recent call last):
       >   File "<string>", line 8, in <module>
       > ModuleNotFoundError: No module named 'setuptools'
       > DEBUG Released lock at `/build/uv-setuptools-91b6cf3c668b19dd.lock`
       >   x Failed to build `/build/atomicwrites-1.4.1`
       >   |-> The build backend returned an error
       >   `-> Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit
       >       status: 1)
       >
       >       hint: This error likely indicates that `atomicwrites-1.4.1` depends
       >       on `setuptools`, but doesn't declare it as a build dependency.
       >       If `atomicwrites-1.4.1` is a first-party package, consider adding
       >       `setuptools` to its `build-system.requires`. Otherwise, either add it to
       >       your `pyproject.toml` under:
       >
       >       [tool.uv.extra-build-dependencies]
       >       "atomicwrites-1.4.1" = ["setuptools"]
       >
       >       or `uv pip install setuptools` into the environment and re-run with
       >       `--no-build-isolation`.
       > DEBUG Released lock at `/build/.tmpGVjimy/.lock`

If I cherry-pick #7513, the build completes without this failure.

After that, hermes chat fails with:

Error: no container with name or ID "hermes-agent" found: no such container

My hermes.nix contains:

container = {
  enable = true;
  image = "localhost/hermes-research:2026-04-09-v1";
  backend = "podman";
  extraVolumes = [ "/srv/projects:/projects:rw" ];
};

From my user account, Podman shows no running containers:

[xxx@xxx]$ podman ps
CONTAINER ID  IMAGE       COMMAND     CREATED     STATUS      PORTS       NAMES

But the container does exist under sudo:

[xxx@xxx]$ sudo podman ps
CONTAINER ID  IMAGE                                    COMMAND               CREATED       STATUS         PORTS       NAMES
1b6816c1671a  localhost/hermes-research:2026-04-09-v1  /data/current-pac...  11 hours ago  Up 11 minutes              hermes-agent

So the managed container is running as root, not under my user. hermes chat appears to look for a user-owned Podman container and does not find the root-owned one.

If I start a separate container under my own user with:

podman run -d --name hermes-agent --replace localhost/hermes-research:2026-04-09-v1 sleep infinity

then hermes chat gets past the missing-container error, but fails with:

Error: unable to find user hermes: no matching entries in passwd file

i'll wait to hear thoughts before going further -- can do some more tests if helpful

[nousr]

rebased off main to include #7518 -- still got the

Error: no container with name or ID "hermes-agent" found: no such container

[github-actions]

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py

---

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

[github-actions]

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py
tests/hermes_cli/test_setup.py

---

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

[github-actions]

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py
tests/hermes_cli/test_setup.py

---

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

[alt-glitch]

@nousr thanks for testing! Both issues are now addressed in the latest push (79e8cd12):

1. atomicwrites build failure — This was because the branch predated #7488 (mautrix migration). Now rebased on main which includes that fix, so nix build works cleanly.

2. Podman "no container with name or ID" error — This is a Podman rootful vs rootless namespace issue. The NixOS systemd service runs the container as root, but podman ps / podman exec from your regular user only sees user-owned containers (unlike Docker, which has group-based socket access).

The CLI now probes whether the runtime can see the container. If it can't, it tries sudo -n (passwordless sudo). If that works, all exec commands go through sudo transparently. If neither works, you get a clear error message with the exact NixOS config to add:

Error: container 'hermes-agent' not found via podman.

The NixOS service runs the container as root. Your user cannot
see it because podman uses per-user namespaces.

Fix: grant passwordless sudo for podman:

  security.sudo.extraRules = [{
    users = [ "your-user" ];
    commands = [{ command = "/run/current-system/sw/bin/podman"; options = [ "NOPASSWD" ]; }];
  }];

Or run: sudo hermes chat

Add this to your NixOS config and rebuild:

security.sudo.extraRules = [{
  users = [ "nousr" ];
  commands = [{
    command = "/run/current-system/sw/bin/podman";
    options = [ "NOPASSWD" ];
  }];
}];

After that, hermes chat should work transparently — the CLI auto-detects it needs sudo and uses it.

3. "unable to find user hermes" — Also fixed. The exec function now uses subprocess.run instead of os.execvp, so it can detect and retry on docker/podman exit codes 125-127 (container not ready, user not found, etc.). This handles the race condition during container startup where the entrypoint hasn't created the hermes user yet.

[alt-glitch]

@BugBot review

[github-actions]

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py
tests/hermes_cli/test_setup.py

---

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

[alt-glitch]

@BugBot review

[github-actions]

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py
tests/hermes_cli/test_setup.py

---

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

[github-actions]

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py
tests/hermes_cli/test_setup.py

---

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

[alt-glitch]

@BugBot review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit e793c70. Configure here.}