hermes - 💡(How to fix) Fix [Bug]: Docker permission failure on Unraid (UID 99) — s6-overlay breaks HERMES_UID remap

Bug Description

Authorship disclosure: This bug report was drafted with the assistance of Hermes Agent (NousResearch/hermes-agent, v2026.5.16, model GLM-5.1 via Z.ai). The technical analysis, logs, and recovery steps were verified by the human operator. The core findings (s6-overlay vs entrypoint.sh/gosu UID remap breakdown) are factual and reproducible.

When updating from tagged release v2026.5.16 to the main branch image on Unraid (UID 99), the container fails to start with PermissionError: [Errno 13] on gateway_state.json. The main branch replaced the entrypoint.sh/gosu privilege management with s6-overlay, which does not correctly handle UID remapping for HERMES_UID=99 (the Unraid default).

This is a regression — v2026.5.16 (which includes commit 14c9f72 removing USER hermes from Dockerfile) works correctly on Unraid.

Steps to Reproduce

1. Run Hermes Agent on Unraid 7.2.4 with volume mount /mnt/user/appdata/hermes-agent/ → /opt/data (owned by UID 99 / GID 100)
2. Set HERMES_UID=99, HERMES_GID=100 in Docker template
3. Pull nousresearch/hermes-agent:main (post-v2026.5.16, 1082+ commits ahead)
4. Start container
5. Observe: container enters boot loop with PermissionError: [Errno 13] on gateway_state.json
6. Attempt --user 0:0 workaround → container boots but .env is not read ("No messaging platforms enabled")

Expected Behavior

Container starts normally with HERMES_UID=99, same as v2026.5.16:

• entrypoint.sh runs as root → usermod -u 99 → chown -R → gosu hermes → gateway runs
• All config, .env, and state files are accessible

Actual Behavior

With main image:

• s6-overlay's stage2-hook handles UID remap, but fails for UID 99
• PermissionError: [Errno 13] on gateway_state.json
• With --user 0:0: container starts but .env not read (platforms not detected)
• With chown -R 10000:10000: same permission issues persist

Affected Component

Setup / Installation, Configuration (config.yaml, .env, hermes setup)

Messaging Platform (if gateway-related)

No response

Debug Report

# Container boot attempts show gateway exit (non-zero) repeatedly
# gateway-exit-diag.log shows success=false pattern
# gateway_state.json: PermissionError [Errno 13]

# After rolling back to v2026.5.16:
# Container starts normally with same config/volume

Operating System

Unraid 7.2.4 (Slackware-based NAS OS)

Python Version

No response

Hermes Version

nousresearch/hermes-agent:main (post-v2026.5.16, ~1082 commits ahead)

Additional Logs / Traceback (optional)

**Key finding from Dockerfile comparison:**

v2026.5.16 (working):

COPY --chmod=0755 --from=gosu_source /gosu /usr/local/bin/
USER root
# entrypoint.sh runs as root, does usermod/chown, then gosu drop

Root Cause Analysis (optional)

The main branch replaced the init system between v2026.5.16 and now:

The s6-overlay stage2-hook does not correctly handle the case where HERMES_UID=99 (or any non-10000 UID) combined with NAS volume mounts where the host directory is owned by UID 99.

Related issues (same root cause):

• #13731 — Unraid UID 99 (this exact case)
• #15290 — UGreen NAS UGOS Pro
• #15832 — Dockerfile USER hermes bypass
• #15865 — Custom UID/GID with -u flag
• #16480 — root-owned config via docker exec

Proposed Fix (optional)

1. Short-term: Document --user 0:0 workaround for Unraid/NAS users in Docker docs
2. Medium-term: Add early detection in s6-overlay stage2-hook if $HERMES_HOME is not writable, with clear error message pointing to documentation
3. Long-term: Ensure s6-overlay stage2-hook handles arbitrary HERMES_UID values the same way entrypoint.sh/gosu did in v2026.5.16
4. Testing: Add CI matrix with UID 99 (Unraid), UID 1000 (Synology), UID 10000 (default)

Recovery Steps (for affected users)

1. Stop the container
2. Revert Repository to nousresearch/hermes-agent:v2026.5.16
3. Fix permissions on host: chown -R 99:100 /mnt/user/appdata/hermes-agent/
   • CRITICAL: Do NOT chmod 644 recursively — destroys execute permissions on binaries
4. Start container
5. Verify: docker logs Hermes-Agent | grep -E "(Changing|Dropping)"

Are you willing to submit a PR for this?

I can help test PRs or release candidates on Unraid before shipping, using a dedicated standby instance (Hermes Guardião).

Are you willing to submit a PR for this?

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