fix(docker): don't run as root, use virtualenv, install matrix deps by m0n5t3r · Pull Request #5811 · NousResearch/hermes-agent

m0n5t3r · 2026-04-07T10:31:15Z

What does this PR do?

Running as root is not recommended, this adds gosu and the entry point uses it to drop root privileges after ensuring $HERMES_HOME is owned by the correct UID; I also added provisions for setting the hermes user UID to a custom value (for users who would prefer to mount a local directory instead of a docker volume to /opt/data and want easy access to it)
pip install without a virtualenv is not recommended either; apart from this, the dependencies for matrix were not installed (they're excluded from [all] because they break things on mac, but the docker is Debian); I added uv to handle the venv bits
downloading chromium for playwright during build does nothing (it gets downloaded to /opt/data/.cache, which then has a volume mounted on top of it so the original files are no longer visible); I moved that step to the entry point

there is some overlap with #4444, but the end result should be a combination of the two: non-root + virtualenv + some install steps moved to the entrypoint (because it turns out npx playwright install chromium will put files in /opt/data, which then has a volume mounted on top of it, so they disappear...)

Related Issue

N/A

Type of Change

🐛 Bug fix (non-breaking change that fixes an issue)
✨ New feature (non-breaking change that adds functionality)
🔒 Security fix
📝 Documentation update
✅ Tests (adding or improving test coverage)
♻️ Refactor (no behavior change)
🎯 New skill (bundled or hub)

Changes Made

Dockerfile: install chromium dependencies, because we'll run playwright as a user; also install git, the doctor complains about it missing
Dockerfile: create non-root hermes user
Dockerfile: create virtualenv, run pip install from it
entrypoint.sh: activate virtualenv

How to Test

build image
run container

Checklist

check htop, hermes should be running as a non-root user, assuming there's no other breakage in the code :)

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)
[N/A] I've run pytest tests/ -q and all tests pass
[N/A] I've added tests for my changes (required for bug fixes, strongly encouraged for features)
I've tested on my platform: Ubuntu 24.04, Docker 29.2.1

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

…encies

AvivAbachi · 2026-04-10T23:21:17Z

Changing a user can be a bit tricky if there’s an existing volume.
It needed to be fixed by using chown as root on the existing volume.

m0n5t3r · 2026-04-11T04:38:23Z

yeah, that's why I didn't mark this ready yet, I wanted to test it for a while; I think I'll add gosu and do both altering the user ID if we have some environment variables to do so (just so yo don't get "I don't have a name" when dropping into the container as a user, if you specify your user id in the compose file) and chown -R to ensure permissions are okay.

- Add gosu for runtime privilege dropping from root to hermes user - Support HERMES_UID/HERMES_GID env vars for host mount permission matching - Switch to debian:13.4-slim base image - Use uv venv instead of pip install --break-system-packages - Pin uv and gosu multi-stage images with SHA256 digests - Set PLAYWRIGHT_BROWSERS_PATH to /opt/hermes/.playwright so build-time chromium install survives the /opt/data volume mount - Keep procps for container debugging Based on work by m0n5t3r in PR #5811. Stripped to hardening-only changes (non-root, virtualenv, slim base); matrix deps, fonts, xvfb, and entrypoint playwright download deferred to follow-up.

teknium1 · 2026-04-12T07:53:27Z

Merged via PR #8226. Your commit was cherry-picked onto current main with your authorship preserved in git log. Thanks for the hardening work @m0n5t3r — non-root execution, virtualenv, and the Playwright path fix all landed.

…ch#5811) - Add gosu for runtime privilege dropping from root to hermes user - Support HERMES_UID/HERMES_GID env vars for host mount permission matching - Switch to debian:13.4-slim base image - Use uv venv instead of pip install --break-system-packages - Pin uv and gosu multi-stage images with SHA256 digests - Set PLAYWRIGHT_BROWSERS_PATH to /opt/hermes/.playwright so build-time chromium install survives the /opt/data volume mount - Keep procps for container debugging Based on work by m0n5t3r in PR NousResearch#5811. Stripped to hardening-only changes (non-root, virtualenv, slim base); matrix deps, fonts, xvfb, and entrypoint playwright download deferred to follow-up.

vision_analyze used Path('./temp_vision_images') — a relative path that resolved against cwd. Under Docker the image's WORKDIR is /opt/hermes, which is root-owned and only chmoded a+rX (read + traversal). Since #5811 landed (run as non-root hermes UID 10000, Apr 12), remote-URL vision calls fail with PermissionError on mkdir. Switch to get_hermes_dir('cache/vision', 'temp_vision_images'): resolves to $HERMES_HOME/cache/vision/ (= /opt/data/cache/vision/ in Docker — the user-owned volume mount). Existing installs with the old dir keep using it via the get_hermes_dir back-compat path; no migration needed. Only site in the codebase that stored runtime files via Path('./...'). Reported via Discord: https://juick.com/i/p/3089079.jpg → Telegram → gateway → [Errno 13] Permission denied: 'temp_vision_images'.

…arch#17719) vision_analyze used Path('./temp_vision_images') — a relative path that resolved against cwd. Under Docker the image's WORKDIR is /opt/hermes, which is root-owned and only chmoded a+rX (read + traversal). Since NousResearch#5811 landed (run as non-root hermes UID 10000, Apr 12), remote-URL vision calls fail with PermissionError on mkdir. Switch to get_hermes_dir('cache/vision', 'temp_vision_images'): resolves to $HERMES_HOME/cache/vision/ (= /opt/data/cache/vision/ in Docker — the user-owned volume mount). Existing installs with the old dir keep using it via the get_hermes_dir back-compat path; no migration needed. Only site in the codebase that stored runtime files via Path('./...'). Reported via Discord: https://juick.com/i/p/3089079.jpg → Telegram → gateway → [Errno 13] Permission denied: 'temp_vision_images'.

…ch#5811) - Add gosu for runtime privilege dropping from root to hermes user - Support HERMES_UID/HERMES_GID env vars for host mount permission matching - Switch to debian:13.4-slim base image - Use uv venv instead of pip install --break-system-packages - Pin uv and gosu multi-stage images with SHA256 digests - Set PLAYWRIGHT_BROWSERS_PATH to /opt/hermes/.playwright so build-time chromium install survives the /opt/data volume mount - Keep procps for container debugging Based on work by m0n5t3r in PR NousResearch#5811. Stripped to hardening-only changes (non-root, virtualenv, slim base); matrix deps, fonts, xvfb, and entrypoint playwright download deferred to follow-up.

…arch#17719) vision_analyze used Path('./temp_vision_images') — a relative path that resolved against cwd. Under Docker the image's WORKDIR is /opt/hermes, which is root-owned and only chmoded a+rX (read + traversal). Since NousResearch#5811 landed (run as non-root hermes UID 10000, Apr 12), remote-URL vision calls fail with PermissionError on mkdir. Switch to get_hermes_dir('cache/vision', 'temp_vision_images'): resolves to $HERMES_HOME/cache/vision/ (= /opt/data/cache/vision/ in Docker — the user-owned volume mount). Existing installs with the old dir keep using it via the get_hermes_dir back-compat path; no migration needed. Only site in the codebase that stored runtime files via Path('./...'). Reported via Discord: https://juick.com/i/p/3089079.jpg → Telegram → gateway → [Errno 13] Permission denied: 'temp_vision_images'.

…ch#5811) - Add gosu for runtime privilege dropping from root to hermes user - Support HERMES_UID/HERMES_GID env vars for host mount permission matching - Switch to debian:13.4-slim base image - Use uv venv instead of pip install --break-system-packages - Pin uv and gosu multi-stage images with SHA256 digests - Set PLAYWRIGHT_BROWSERS_PATH to /opt/hermes/.playwright so build-time chromium install survives the /opt/data volume mount - Keep procps for container debugging Based on work by m0n5t3r in PR NousResearch#5811. Stripped to hardening-only changes (non-root, virtualenv, slim base); matrix deps, fonts, xvfb, and entrypoint playwright download deferred to follow-up.

…arch#17719) vision_analyze used Path('./temp_vision_images') — a relative path that resolved against cwd. Under Docker the image's WORKDIR is /opt/hermes, which is root-owned and only chmoded a+rX (read + traversal). Since NousResearch#5811 landed (run as non-root hermes UID 10000, Apr 12), remote-URL vision calls fail with PermissionError on mkdir. Switch to get_hermes_dir('cache/vision', 'temp_vision_images'): resolves to $HERMES_HOME/cache/vision/ (= /opt/data/cache/vision/ in Docker — the user-owned volume mount). Existing installs with the old dir keep using it via the get_hermes_dir back-compat path; no migration needed. Only site in the codebase that stored runtime files via Path('./...'). Reported via Discord: https://juick.com/i/p/3089079.jpg → Telegram → gateway → [Errno 13] Permission denied: 'temp_vision_images'.

…ch#5811) - Add gosu for runtime privilege dropping from root to hermes user - Support HERMES_UID/HERMES_GID env vars for host mount permission matching - Switch to debian:13.4-slim base image - Use uv venv instead of pip install --break-system-packages - Pin uv and gosu multi-stage images with SHA256 digests - Set PLAYWRIGHT_BROWSERS_PATH to /opt/hermes/.playwright so build-time chromium install survives the /opt/data volume mount - Keep procps for container debugging Based on work by m0n5t3r in PR NousResearch#5811. Stripped to hardening-only changes (non-root, virtualenv, slim base); matrix deps, fonts, xvfb, and entrypoint playwright download deferred to follow-up.

…arch#17719) vision_analyze used Path('./temp_vision_images') — a relative path that resolved against cwd. Under Docker the image's WORKDIR is /opt/hermes, which is root-owned and only chmoded a+rX (read + traversal). Since NousResearch#5811 landed (run as non-root hermes UID 10000, Apr 12), remote-URL vision calls fail with PermissionError on mkdir. Switch to get_hermes_dir('cache/vision', 'temp_vision_images'): resolves to $HERMES_HOME/cache/vision/ (= /opt/data/cache/vision/ in Docker — the user-owned volume mount). Existing installs with the old dir keep using it via the get_hermes_dir back-compat path; no migration needed. Only site in the codebase that stored runtime files via Path('./...'). Reported via Discord: https://juick.com/i/p/3089079.jpg → Telegram → gateway → [Errno 13] Permission denied: 'temp_vision_images'.

m0n5t3r added 2 commits April 7, 2026 08:42

fix(docker): don't run as root, use virtualenv, install matrix depend…

142c11f

…encies

move the playwright install to the entrypoint

aa37257

m0n5t3r and others added 2 commits April 11, 2026 22:37

switch to uv, ensure correct permissions, drop root with gosu

fb65e7a

Merge branch 'main' into docker/no-root

e2310b3

m0n5t3r marked this pull request as ready for review April 11, 2026 19:59

Merge branch 'NousResearch:main' into docker/no-root

5690727

teknium1 mentioned this pull request Apr 12, 2026

fix(docker): run as non-root user, use virtualenv (salvage #5811) #8226

Merged

teknium1 closed this Apr 12, 2026

m0n5t3r deleted the docker/no-root branch April 14, 2026 06:29

teknium1 mentioned this pull request Apr 30, 2026

fix(vision): use HERMES_HOME-based cache dir instead of cwd #17719

Merged

Navigation Menu

fix(docker): don't run as root, use virtualenv, install matrix deps - #5811

fix(docker): don't run as root, use virtualenv, install matrix deps#5811
m0n5t3r wants to merge 5 commits into
NousResearch:mainfrom
m0n5t3r:docker/no-root

m0n5t3r commented Apr 7, 2026 •

edited

Loading

Uh oh!

AvivAbachi commented Apr 10, 2026

Uh oh!

m0n5t3r commented Apr 11, 2026

Uh oh!

teknium1 commented Apr 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

m0n5t3r commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Related Issue

Type of Change

Changes Made

How to Test

Checklist

Code

Documentation & Housekeeping

Uh oh!

AvivAbachi commented Apr 10, 2026

Uh oh!

m0n5t3r commented Apr 11, 2026

Uh oh!

teknium1 commented Apr 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

m0n5t3r commented Apr 7, 2026 •

edited

Loading