PR #12623: fix(docker): HERMES_UID and HERMES_GID usage in container + feature(docker): add new SYNC_CODE_DIR environment variable

• Repository: NousResearch/hermes-agent
• Author: mmartial
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/12623

Description (problem / solution / changelog)

What does this PR do?

The entrypoint contains runtime ownership/remap logic that only works correctly when the container starts as root. After the image build switched to running as hermes, that logic no longer had the privileges needed to honor HERMES_UID / HERMES_GID.

Separately, some downstream/containerized workflows need access to the exact Hermes source code shipped in the image so they can install it into their own virtualenv or consume files like requirements.txt from a mounted path.

This PR makes two Docker-focused changes:

1. Restores the intended HERMES_UID / HERMES_GID behavior by switching the image back to root before the runtime entrypoint executes.
2. Adds an optional SYNC_CODE_DIR environment variable that rsyncs the installed Hermes source tree to a writable external directory at container startup (to allow third party solutions to add hermes agent to their venv; example: Hermes WebUI)

Related Issue

I did not see an existing issue, and created one https://github.com/NousResearch/hermes-agent/issues/12696

I discovered the issue while trying to use HERMES_UID and HERMES_GID and found that they were not being respected (the intent was to provide an Unraid template for Hermes Agent, and the Hermes WebUI project; the second one would need the new feature to function)

The root cause is the USER hermes usage in the Dockerfile while the entrypoint.sh checks against id = 0 (ie the root user)

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)

Changes Made

• Dockerfile:

  • Installs rsync
  • Switches back to USER root after dependency installation so the entrypoint.sh can perform UID/GID and ownership setup correctly at runtime

• docker/entrypoint.sh

  • Adds optional SYNC_CODE_DIR support. If SYNC_CODE_DIR points to an existing writable directory, the entrypoint copies /opt/hermes into it with rsync (excludes runtime/build noise such as .venv, .git, __pycache__, *.pyc, *.pyo, and .playwright + uses --delete so the synced directory stays aligned with the source tree across restarts). Fails open: if the sync target is missing or not writable, container startup continues normally

Behavior: Default behavior is unchanged when SYNC_CODE_DIR is unset. The sync is best-effort and does not block container startup. This is mainly useful for bind-mounted development workflows and derived images that want to install Hermes into a separate venv.

How to Test

1. docker build -f Dockerfile --tag ha:test .
2. mkdir -p ../test/{data,src}
3. docker run --rm -it -e HERMES_UID=$(id -u) -e HERMES_GID=$(id -g) -v $(pwd)/../test/data:/test/data -e HERMES_HOME=/test/data -v $(pwd)/../test/src:/test/src -e SYNC_CODE_DIR=/test/src ha:test

Result:

Changing hermes UID to 1000
Changing hermes GID to 1000
Dropping root privileges
Running as 1000:1000 (hermes:hermes)
SYNC_CODE_DIR is set to /test/src, copying code there
Code copied to SYNC_CODE_DIR successfully (...
Syncing bundled skills into ~/.hermes/skills/ ...
  + dogfood
[...]
Done: 77 new, 0 updated, 0 unchanged. 77 total bundled.
[... followed by Hermes TUI access]

Local folders:

• ../test/data contains the hermes runtime (including config.yaml, ...) owned by user matching HERMES_UID and HERMES_GID
• ../test/src contains the content of /opt/hermes (without the .venv and other dropped files/folders) to support usage with 3rd party extensions more easily

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
  • only fix container build and usage, no hermes behavior
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
  • described in how to test, this is not a recursion issue, same comment as above re no change to hermes behavior
• I've tested on my platform: Ubuntu 24.04 w/ Docker

Documentation & Housekeeping

• [N/A] I've updated relevant documentation (README, docs/, docstrings) — or N/A
• [N/A] I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• [N/A] I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• [N/A] I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• [N/A] I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Changed files

• Dockerfile (modified, +4/-1)
• docker/entrypoint.sh (modified, +21/-0)

PR #12733: fix(docker): run entrypoint as root so HERMES_UID/HERMES_GID remapping works

• Repository: NousResearch/hermes-agent
• Author: kagura-agent
• State: closed | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/12733

Description (problem / solution / changelog)

Fixes #12696

The Dockerfile's final USER hermes directive meant the container always started as UID 10000, so the entrypoint's existing UID/GID remapping code (which requires root for usermod/groupmod) was always skipped.

Fix: Add USER root before the runtime section so the entrypoint runs as root, performs the UID/GID remapping if HERMES_UID/HERMES_GID are set, then drops privileges via gosu hermes.

Changed files

• Dockerfile (modified, +3/-0)