Bug Description

Prerequisites

• I have searched for existing issues that already report this problem
• I have checked the documentation
• This is a bug report for the Docker image

Description

Related Issues: #19788, #17636, #21457, #20500 While there are several Docker permission issues reported (see #19788 for entrypoint chown behavior, #17636 for plugin installation failures), this issue specifically addresses the build-time ownership of the Python virtual environment at /opt/hermes/.venv. The Dockerfile creates the venv as root:root, but only changes ownership of ui-tui and node_modules directories to the hermes user. This inconsistency prevents running the container as a non-root user (UID 10000).

Steps to Reproduce

Affected Version: nousresearch/hermes-agent:v2026.5.7 Test Case:

# Test with non-root user (UID 10000)
docker run --rm -u 10000:10000 nousresearch/hermes-agent:v2026.5.7 \
  touch /opt/hermes/.venv/test_write
# Result: Permission denied
# Exit code: 1
Verification:
docker run --rm -u 10000:10000 nousresearch/hermes-agent:v2026.5.7 \
  ls -la /opt/hermes/ | grep .venv
# Output:
# drwxr-xr-x 5 root root 4096 .venv
Dockerfile Analysis
File: https://github.com/NousResearch/hermes-agent/blob/main/Dockerfile
Lines 61-63:
USER root
RUN chmod -R a+rX /opt/hermes && \
    chown -R hermes:hermes /opt/hermes/ui-tui /opt/hermes/node_modules
Lines 68-69:
# ---------- Python virtualenv ----------
RUN uv venv && \
    uv pip install --no-cache-dir -e ".[all]"
The Bug:
1. Line 62-63: Only ui-tui and node_modules are chowned to hermes:hermes
2. Lines 68-69: The venv is created AFTER while still USER root
3. Result: /opt/hermes/.venv remains owned by root:root with 755 permissions

### Expected Behavior

The /opt/hermes/.venv directory should be owned by hermes:hermes (UID 10000) so the container can run as a non-root user without permission errors.


### Actual Behavior

Actual Behavior
- /opt/hermes/.venv is owned by root:root with 755 permissions
- The hermes user (UID 10000) cannot write to the virtual environment
- Python bytecode caching fails
- Plugin installations fail with permission denied

### Affected Component

Other

### Messaging Platform (if gateway-related)

_No response_

### Debug Report

```shell
-

Operating System

Docker

Python Version

No response

Hermes Version

v0.13.0

Additional Logs / Traceback (optional)

Additional Context
The comment at lines 69-71 mentions:
> "node_modules trees additionally need to be writable by the hermes user so the runtime npm install triggered by _tui_need_npm_install() succeeds (see #18800)"
The same logic applies to the Python venv - it needs to be writable by the hermes user for:
- Python bytecode caching
- Runtime package installations
- Plugin installations

Root Cause Analysis (optional)

1. Entrypoint Script Behavior The entrypoint script (/opt/hermes/docker/entrypoint.sh) performs the following actions when HERMES_UID is set:

• ✅ Changes the hermes user's UID if it differs from the current value
• ✅ Fixes ownership of $HERMES_HOME (default: /opt/data)
• ✅ Drops privileges using gosu to run as the hermes user
• ❌ Does NOT touch /opt/hermes/.venv - this directory remains owned by root:root Relevant code from entrypoint:

Only chowns HERMES_HOME (default /opt/data), NOT the install directory

if [ "$needs_chown" = true ]; then echo "Fixing ownership of $HERMES_HOME to hermes ($actual_hermes_uid)" chown -R hermes:hermes "$HERMES_HOME" 2>/dev/null ||
echo "Warning: chown failed (rootless container?) — continuing anyway" fi 2. Venv Ownership After Setting HERMES_UID Directory /opt/hermes/.venv /opt/data 3. Write Permission Test Results

• ❌ Writing to /opt/hermes/.venv as hermes user: Permission denied
• ✅ Writing to /opt/data as hermes user: SUCCESS

1. Process User Verification When the entrypoint runs with HERMES_UID=10000:

• The container starts as root
• Entrypoint changes hermes UID to 10000 (if different from default)
• Entrypoint chowns /opt/data to hermes:hermes
• Entrypoint uses gosu to drop privileges to hermes user
• Hermes process runs as UID 10000

Proposed Fix (optional)

Add USER hermes before creating the venv:

After line 80, add:

USER hermes

Lines 81-82 will now run as hermes user

RUN uv venv &&
uv pip install --no-cache-dir -e ".[all]"

Are you willing to submit a PR for this?

• I'd like to fix this myself and submit a PR