May 25May 25 This is the support thread for the Hermes Agent Unraid Docker template.Template: https://raw.githubusercontent.com/medzin/docker-templates/main/medzin/hermes-agent.xmlHermes Agent is a self-improving AI agent by Nous Research. This template runs the official nousresearch/hermes-agent container in gateway mode with the dashboard enabled and API server disabled by default.Quick SetupAfter installing the container, open the Unraid container console and run:/opt/hermes/.venv/bin/hermes setupAfter setup completes, restart the container from the Unraid Docker page.This container restart is required even if setup already restarts the gateway. The Unraid console runs as root, so setup may create config files owned by root:root. Restarting the container lets the Docker entrypoint apply the configured HERMES_UID and HERMES_GID ownership.Official DocsDocker: https://hermes-agent.nousresearch.com/docs/user-guide/docker/Quickstart: https://hermes-agent.nousresearch.com/docs/getting-started/quickstart/Telegram: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram/ Edited May 26May 26 by medzin Updated Quick Setup instrictions to restart the container.
May 26May 26 In case anyone else runs into the issue to get chat working I had to run this from the container consolechown -R 99:99 /opt/hermes/ui-tui
May 26May 26 Author Thanks for reporting this. That helped identify the actual issue.The container console runs commands as root, so the setup flow can create or update files with root:root ownership. Restarting the gateway from inside Hermes is not enough in that case, because it does not re-run the container entrypoint.I updated the main post to make this clearer: after running the setup commands, restart the whole container from the Unraid Docker page. That lets the entrypoint apply the configured HERMES_UID / HERMES_GID ownership again.The template defaults are HERMES_UID=99 and HERMES_GID=100, so a manual chown 99:99 should not normally be needed with the updated instructions.
May 26May 26 I feel like there's something I'm missing, I'm trying to update from the webui and the log says the update completes and to restart the gateway, but restarting the gateway crashes the container with no log output and the updates don't seem to persist a container restart.
May 26May 26 Author Thanks for the follow-up. This looks like a Docker/runtime limitation rather than something wrong with your setup.The Unraid template runs the official Hermes Docker image. The persistent appdata path is /opt/data, but the application itself lives under /opt/hermes inside the container image. Because of that, I would avoid using the WebUI self-update flow for this Docker template. If the update modifies files under /opt/hermes, those changes are not part of appdata and may not survive container recreation/image updates. Also, restarting the gateway from inside Hermes can stop the foreground gateway process, which makes Docker think the container exited.For Unraid, the safer update path is:Update the Docker image from Unraid.Restart the container from the Unraid Docker page.Run setup/migration commands again only if the official Hermes docs say they are needed.
May 28May 28 I just had an issue with the Hermes-Agent from the template by martial. I cannot find the official support thread for that one. I wonder if this one is better?I hit an issue with the Hermes Agent Unraid template where the container would start and then immediately die with errors like:/opt/hermes/docker/stage2-hook.sh: not found No module named hermes_cli.container_boot /opt/hermes/docker/main-wrapper.sh: not found The issue ended up being the hermes_shared_volume docker named volume mounted to /opt/hermes.The template intentionally uses a shared docker volume for /opt/hermes, but mine had stale/broken contents, so it was masking the actual application files from the image.Fix was:bash docker stop Hermes-Agent docker rm Hermes-Agent docker volume rm hermes_shared_volumeThen recreate the container from the Unraid template.The volume gets repopulated correctly from the image on first boot and Hermes starts normally again. Edited May 28May 28 by AndyLively
June 1Jun 1 @medzin hi guy...tks for this container...1. When I ran and configured Telegram with this command /opt/hermes/.venv/bin/hermes setup, it gives a permission error and no longer accepts messages in TelegramSorry, I encountered an error (PermissionError).[Errno 13] Permission denied: '/opt/data/pairing/telegram-approved.json'Try again or use /reset to start a fresh session.2. The WebUI doesn't open....anyone else having this problem? http://myip:9119/ Edited June 1Jun 1 by Braulio Dias Ribeiro
June 3Jun 3 I was able to get the webui working by adding another port mapping @Braulio Dias Ribeiro Im getting permission issues today with this container. Going to look into it
June 3Jun 3 Author Thanks for the reports - I've tracked down both issues and pushed a template update. If you reinstall/force-update the template from Community Apps you'll get the new defaults; existing installs need a couple of one-time fixes below.Quick background on what was going wrongThe Hermes image only accepts a runtime UID/GID of 1000 or higher. The template was shipping Unraid's usual 99 / 100, which the image silently rejects - so it fell back to UID 10000 while your appdata stayed owned by 99:100. That mismatch is what caused PermissionError: [Errno 13] ... /opt/data/pairing/telegram-approved.json.The dashboard, when bound to 0.0.0.0 (needed for LAN access), turns on an OAuth login gate that has no provider configured in the self-hosted image - so it refuses to start and nothing listens on :9119.(Full technical write-up / upstream bug: https://github.com/NousResearch/hermes-agent/issues/38070)Fix 1 - Telegram permission errorStop the container.On the Unraid host (terminal), fix ownership of the appdata folder so it matches the runtime user:chown -R 10000:10000 /mnt/cache/appdata/hermes-agent The pairing subfolder is the one that actually breaks, so make sure the -R covers it.Make sure HERMES_UID / HERMES_GID are 10000 (the new template default). Leave them at 10000 unless you have a specific host user ≥1000 you want to match.Start the container.Also - when configuring Telegram, don't run /opt/hermes/.venv/bin/hermes setup from the console. Calling that path directly runs as root and writes root-owned files into the volume, which re-breaks pairing. Use the supported wrapper instead, which drops to the right user automatically:docker exec Hermes-Agent hermes setup (Or just set TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS in the template - no console setup needed.)Fix 2 - WebUI won't open on :9119The updated template adds a new variable, HERMES_DASHBOARD_INSECURE=1, which lets the dashboard bind on the LAN. If you're on the old template, add it manually (Add another Variable → key HERMES_DASHBOARD_INSECURE, value 1).⚠️ Heads-up: with this on, the dashboard has no authentication - anyone on your network who can reach http://<ip>:9119 has full control. That's fine on a trusted home LAN, but do not port-forward it to the internet. If you need remote access, put it behind a reverse proxy with auth or a VPN/Tailscale.After applying both, the bot should accept messages again and the WebUI should load. Let me know if anything's still off and I'll dig in.
June 3Jun 3 8 hours ago, medzin said:Thanks for the reports - I've tracked down both issues and pushed a template update. If you reinstall/force-update the template from Community Apps you'll get the new defaults; existing installs need a couple of one-time fixes below.Quick background on what was going wrongThe Hermes image only accepts a runtime UID/GID of 1000 or higher. The template was shipping Unraid's usual 99 / 100, which the image silently rejects - so it fell back to UID 10000 while your appdata stayed owned by 99:100. That mismatch is what caused PermissionError: [Errno 13] ... /opt/data/pairing/telegram-approved.json.The dashboard, when bound to 0.0.0.0 (needed for LAN access), turns on an OAuth login gate that has no provider configured in the self-hosted image - so it refuses to start and nothing listens on :9119.(Full technical write-up / upstream bug: https://github.com/NousResearch/hermes-agent/issues/38070)Fix 1 - Telegram permission errorStop the container.On the Unraid host (terminal), fix ownership of the appdata folder so it matches the runtime user:chown -R 10000:10000 /mnt/cache/appdata/hermes-agent The pairing subfolder is the one that actually breaks, so make sure the -R covers it.Make sure HERMES_UID / HERMES_GID are 10000 (the new template default). Leave them at 10000 unless you have a specific host user ≥1000 you want to match.Start the container.Also - when configuring Telegram, don't run /opt/hermes/.venv/bin/hermes setup from the console. Calling that path directly runs as root and writes root-owned files into the volume, which re-breaks pairing. Use the supported wrapper instead, which drops to the right user automatically:docker exec Hermes-Agent hermes setup (Or just set TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS in the template - no console setup needed.)Fix 2 - WebUI won't open on :9119The updated template adds a new variable, HERMES_DASHBOARD_INSECURE=1, which lets the dashboard bind on the LAN. If you're on the old template, add it manually (Add another Variable → key HERMES_DASHBOARD_INSECURE, value 1).⚠️ Heads-up: with this on, the dashboard has no authentication - anyone on your network who can reach http://<ip>:9119 has full control. That's fine on a trusted home LAN, but do not port-forward it to the internet. If you need remote access, put it behind a reverse proxy with auth or a VPN/Tailscale.After applying both, the bot should accept messages again and the WebUI should load. Let me know if anything's still off and I'll dig in.Ah, yes... I changed to this new configuration and it worked... thank you very much for your help... gratitude
June 3Jun 3 @medzin It is giving a reading error:Why Firecrawl doesn't work:- Hermes code loads .env from /opt/hermes/.env- Your .env is in /opt/data/.env- Therefore, FIRECRAWL_API_URL never enters the environmentWhat I found now:- /opt/data/.env exists (24KB, with your configuration)- /opt/hermes/.env does not exist- FIRECRAWL_API_URL is not in the active environment
June 4Jun 4 Author @Braulio Dias Ribeiro This looks like a recently fixed Hermes Docker issue rather than an Unraid template path issue.Hermes Docker stores config and secrets in /opt/data, and the current image correctly loads /opt/data/.env. The bug was that s6-overlay could drop HERMES_HOME before gateway run, causing Hermes to look in the wrong location.Upstream fix:https://github.com/NousResearch/hermes-agent/pull/32412Related issue:https://github.com/NousResearch/hermes-agent/issues/33004I validated the current nousresearch/hermes-agent:latest image and confirmed:- HERMES_HOME=/opt/data- /opt/data/.env is loaded- FIRECRAWL_API_URL becomes visible to gateway.run- /opt/hermes/.env does not need to existPlease force-update/pull the latest Hermes image and recreate/start the container with the same appdata path. If the issue still happens after updating, please share the image digest/version and container logs.Hermes is also moving very quickly right now, so Docker behavior can change between image builds. If something looks inconsistent with the docs, the first thing to try is usually pulling the latest image and recreating the container while keeping the same appdata path.
June 24Jun 24 I just tried to configure the gateway with Photon (iMessage) - however I get the following error message:[5/5] Installing Node sidecar deps (spectrum-ts)... $ cd /opt/hermes/plugins/platforms/photon/sidecar && /usr/local/bin/npm ci npm error code EACCES npm error syscall mkdir npm error path /opt/hermes/plugins/platforms/photon/sidecar/node_modules npm error errno -13 npm error Error: EACCES: permission denied, mkdir '/opt/hermes/plugins/platforms/photon/sidecar/node_modules' npm error at async mkdir (node:internal/fs/promises:858:10) npm error at async /usr/local/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js:638:20 npm error at async Promise.allSettled (index 0) npm error at async [reifyPackages] (/usr/local/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js:334:11) npm error at async Arborist.reify (/usr/local/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js:149:5) npm error at async CI.exec (/usr/local/lib/node_modules/npm/lib/commands/ci.js:100:5) npm error at async Npm.exec (/usr/local/lib/node_modules/npm/lib/npm.js:207:9) npm error at async module.exports (/usr/local/lib/node_modules/npm/lib/cli/entry.js:74:5) { npm error errno: -13, npm error code: 'EACCES', npm error syscall: 'mkdir', npm error path: '/opt/hermes/plugins/platforms/photon/sidecar/node_modules' npm error } npm error npm error The operation was rejected by your operating system. npm error It is likely you do not have the permissions to access this file as the current user npm error npm error If you believe this might be a permissions issue, please double-check the npm error permissions of the file and its containing directories, or try running npm error the command again as root/Administrator. npm error A complete log of this run can be found in: /opt/data/.npm/_logs/2026-06-24T20_24_42_432Z-debug-0.log npm ci failed — falling back to: /usr/local/bin/npm install npm error code EACCES npm error syscall mkdir npm error path /opt/hermes/plugins/platforms/photon/sidecar/node_modules npm error errno -13 npm error Error: EACCES: permission denied, mkdir '/opt/hermes/plugins/platforms/photon/sidecar/node_modules' npm error at async mkdir (node:internal/fs/promises:858:10) npm error at async /usr/local/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js:638:20 npm error at async Promise.allSettled (index 0) npm error at async [reifyPackages] (/usr/local/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js:334:11) npm error at async Arborist.reify (/usr/local/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js:149:5) npm error at async Install.exec (/usr/local/lib/node_modules/npm/lib/commands/install.js:150:5) npm error at async Npm.exec (/usr/local/lib/node_modules/npm/lib/npm.js:207:9) npm error at async module.exports (/usr/local/lib/node_modules/npm/lib/cli/entry.js:74:5) { npm error errno: -13, npm error code: 'EACCES', npm error syscall: 'mkdir', npm error path: '/opt/hermes/plugins/platforms/photon/sidecar/node_modules' npm error } npm error npm error The operation was rejected by your operating system. npm error It is likely you do not have the permissions to access this file as the current user npm error npm error If you believe this might be a permissions issue, please double-check the npm error permissions of the file and its containing directories, or try running npm error the command again as root/Administrator. npm error A complete log of this run can be found in: /opt/data/.npm/_logs/2026-06-24T20_24_42_792Z-debug-0.log npm install failed ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✓ Messaging platforms configured! Restart the gateway to pick up changes? [Y/n]: It seems that it tries to write in the image in /opt/hermes/... - is there a fix or a workaround to that?
June 27Jun 27 On 6/24/2026 at 4:42 PM, COLUMBUS said:I just tried to configure the gateway with Photon (iMessage) - however I get the following error message:[5/5] Installing Node sidecar deps (spectrum-ts)... $ cd /opt/hermes/plugins/platforms/photon/sidecar && /usr/local/bin/npm ci npm error code EACCES npm error syscall mkdir npm error path /opt/hermes/plugins/platforms/photon/sidecar/node_modules npm error errno -13 npm error Error: EACCES: permission denied, mkdir '/opt/hermes/plugins/platforms/photon/sidecar/node_modules' npm error at async mkdir (node:internal/fs/promises:858:10) npm error at async /usr/local/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js:638:20 npm error at async Promise.allSettled (index 0) npm error at async [reifyPackages] (/usr/local/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js:334:11) npm error at async Arborist.reify (/usr/local/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js:149:5) npm error at async CI.exec (/usr/local/lib/node_modules/npm/lib/commands/ci.js:100:5) npm error at async Npm.exec (/usr/local/lib/node_modules/npm/lib/npm.js:207:9) npm error at async module.exports (/usr/local/lib/node_modules/npm/lib/cli/entry.js:74:5) { npm error errno: -13, npm error code: 'EACCES', npm error syscall: 'mkdir', npm error path: '/opt/hermes/plugins/platforms/photon/sidecar/node_modules' npm error } npm error npm error The operation was rejected by your operating system. npm error It is likely you do not have the permissions to access this file as the current user npm error npm error If you believe this might be a permissions issue, please double-check the npm error permissions of the file and its containing directories, or try running npm error the command again as root/Administrator. npm error A complete log of this run can be found in: /opt/data/.npm/_logs/2026-06-24T20_24_42_432Z-debug-0.log npm ci failed — falling back to: /usr/local/bin/npm install npm error code EACCES npm error syscall mkdir npm error path /opt/hermes/plugins/platforms/photon/sidecar/node_modules npm error errno -13 npm error Error: EACCES: permission denied, mkdir '/opt/hermes/plugins/platforms/photon/sidecar/node_modules' npm error at async mkdir (node:internal/fs/promises:858:10) npm error at async /usr/local/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js:638:20 npm error at async Promise.allSettled (index 0) npm error at async [reifyPackages] (/usr/local/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js:334:11) npm error at async Arborist.reify (/usr/local/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js:149:5) npm error at async Install.exec (/usr/local/lib/node_modules/npm/lib/commands/install.js:150:5) npm error at async Npm.exec (/usr/local/lib/node_modules/npm/lib/npm.js:207:9) npm error at async module.exports (/usr/local/lib/node_modules/npm/lib/cli/entry.js:74:5) { npm error errno: -13, npm error code: 'EACCES', npm error syscall: 'mkdir', npm error path: '/opt/hermes/plugins/platforms/photon/sidecar/node_modules' npm error } npm error npm error The operation was rejected by your operating system. npm error It is likely you do not have the permissions to access this file as the current user npm error npm error If you believe this might be a permissions issue, please double-check the npm error permissions of the file and its containing directories, or try running npm error the command again as root/Administrator. npm error A complete log of this run can be found in: /opt/data/.npm/_logs/2026-06-24T20_24_42_792Z-debug-0.log npm install failed ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✓ Messaging platforms configured! Restart the gateway to pick up changes? [Y/n]: It seems that it tries to write in the image in /opt/hermes/... - is there a fix or a workaround to that?same issue here
June 27Jun 27 Author Yes, this is a known issue with the Hermes Agent Docker image when running the container as a non-root user. The only workaound it so run the conainer as a root. Similar GitHub issues:https://github.com/NousResearch/hermes-agent/issues/50981https://github.com/NousResearch/hermes-agent/issues/49569
June 28Jun 28 How can I run the container as root? As I see it, it always falls back to the hermes user with 10000:10000
June 29Jun 29 Author My mistake, I apologize. If I recall correctly, Hermes refuses to run as root and will fall back to UID 10000 regardless of your configuration. Therefore, the only workaround for now is to use a custom Docker image instead of the official one, as outlined in this comment: https://github.com/NousResearch/hermes-agent/issues/49569#issuecomment-4760137144
Thursday at 09:49 PM4 days Ok got it working now - it seems that photon is not 100% implemented right now in Hermes Agent.To make it working for now I added the following parameters to the template:Extra Parameters: --entrypoint /bin/shPost Arguments: -lc 'rm -rf /opt/hermes/plugins/platforms/photon/sidecar/node_modules && chown -R hermes:hermes /opt/hermes/plugins/platforms/photon/sidecar && su -s /bin/sh hermes -c "cd /opt/hermes/plugins/platforms/photon/sidecar && npm install --unsafe-perm=true" && exec /init /opt/hermes/docker/main-wrapper.sh gateway run'This way the problematic directory in the immutable /opt/hermes/ gets it's permissions straightened for every reboot and then also removes and reinstalls the photon sidecar every boot.The only problem now is that the connection to the photon servers is a bit finicky and has lots of reconnects, which as I belief right now results at some point in a sort of ban from the photon server as it will not forward my messages to hermes agent after a couple of reconnects.
Join the conversation
You can post now and register later. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.