How-To Guide
Fix missing files in Hermes Discord without exposing credentials
Separate the Discord gateway from the Docker tool sandbox, check the active profile, and mount only the files a task needs without exposing all Hermes credentials.
Quick answer
A Discord reply and a terminal command can run in different environments. Check where the gateway runs and which terminal backend it uses before changing mounts. The full Hermes application uses /opt/data for state; a Docker tool sandbox should receive only the task directories it needs.
If Discord replies but a file command cannot find your host configuration, that does not prove the gateway lost its credentials. The command may be running in a separate sandbox. Start with the whole-agent Docker guide or the terminal backend guide, depending on what you deployed.
$49/mo or $39/mo billed yearly · AI included · 14‑day guarantee
Before you start:
- ☑Access to the account and environment that starts the gateway
- ☑The existing container or service name and active Hermes profile
- ☑A specific task directory you intend to expose, with a backup before writable access
Steps
- 1
Identify the gateway environment
If the whole gateway runs in the official container named hermes, run
docker exec hermes hermes config path,docker exec hermes hermes config env-pathanddocker exec hermes hermes gateway status. For a native gateway, run the equivalenthermescommands as the service account. Add the existing-p PROFILEselection when applicable; do not print the .env contents. The profiles guide explains separate state directories. - 2
Check the effective terminal backend
Inspect
terminal.backendin that profile configuration and anyTERMINAL_ENVoverride in the service environment. Docker here controls tool execution; it does not move an already running Discord gateway. If you deliberately change to local, commands run with the host account's access. That is a change in security boundary, not a harmless file-access workaround. - 3
Mount the task folder, not all Hermes credentials
For a Docker terminal backend, add a narrow
terminal.docker_volumesentry such as/absolute/path/to/notes:/workspace/notes:roto the existing terminal block. Replace the source with your real directory. Keep:rofor reading; grant write access only when the task needs it and you accept changes to those host files. Do not mount the whole .hermes directory or Docker socket to solve one missing file. See the security guide. - 4
Keep application persistence separate
If the gateway itself runs in the official image, its run/Compose configuration mounts the data directory at
/opt/data. That is separate fromterminal.docker_volumes. Changing a tool mount does not repair a missing application volume. Use the Compose walkthrough and preserve existing state before replacement. - 5
Apply the change and verify the actual sandbox
Current Docker backend docs describe profile- and environment-scoped reuse. With no explicit shared-container key, changing mount arguments creates a fresh matching sandbox rather than silently attaching to the old environment. An explicit shared key changes those rules. Save needed work before lifecycle changes and verify the resulting mounts; a gateway restart alone is not proof. Ask the agent to read one harmless file at
/workspace/notesand confirm it cannot write to the read-only mount. - 6
Test the intended Discord conversation
Send a harmless request yourself in the intended channel or thread. Confirm both the reply and the allowed file read. If no adapter starts, inspect the first startup exception and running image before changing Discord permissions. If it connects but stops receiving events, use Discord setup diagnostics; if inference or delivery fails, use gateway troubleshooting.
Pro Tips
- 💡Keep an Obsidian vault or other task data in its own explicit mount, not nested in the Hermes credential directory.
- 💡Read the official Docker backend configuration for the lifecycle supported by your version. A fresh session is not always a fresh container.
- 💡Use managed hosting if gateway upkeep is the burden you want to remove. Self-hosted WebUI also has PTY/WebSocket browser Chat; the choice is who maintains the runtime.
Troubleshooting
❌ Discord replies but the terminal cannot find config.yaml
✅ Check whether the terminal runs in a separate Docker sandbox. Configuration access is not required for most tasks; inspect profile paths from the operator environment rather than mounting all credentials into the sandbox.
❌ The gateway reports no bot token
✅ Check the gateway service's active profile and env path, not just the tool container. A missing token, wrong profile or unloaded adapter needs different repair. Do not expose secrets in a chat transcript.
❌ A read-only notes mount rejects a write
✅ That is expected. Confirm whether writing is actually required before removing :ro, and back up the host directory first.
❌ An old sandbox still appears after a restart
✅ Check the effective backend settings, environment label and any explicit shared-container key. Persistent containers can survive Hermes process restarts; verify actual mounts before assuming the new configuration took effect.
FAQ
Should I mount my whole .hermes directory into the Discord tool sandbox?
No, not as a generic repair. That directory can contain provider keys, bot tokens and private session history. Mount only the task directory needed. The full application container uses /opt/data for its own persistent state; that is a different boundary.
Does a missing config file inside the tool sandbox mean Discord lost its token?
No. A working gateway can hold its configuration outside the tool sandbox. Check the gateway account and profile paths separately from the environment used by terminal tools.
Can I use Hermes Discord without Docker?
Yes. A native Hermes gateway can connect to Discord. Switching terminal execution to local gives commands host access, so make that decision deliberately rather than using it as a blanket fix.
Does restarting the gateway always create a fresh Docker sandbox?
No. Current defaults can reuse a sandbox across Hermes process restarts. Mount/image changes normally select a new environment when no shared-container key is set; explicit sharing requires additional care. Verify the mounted paths in the actual execution container.