Hermes Agent Docker Compose Setup for Self-Hosting
Run Hermes Agent with Docker Compose using persistent volumes, safe environment variables, restart policies, gateway logs, and Discord/Telegram checks.
Quick answer
A good Hermes Docker Compose setup persists ~/.hermes, passes secrets through env or mounted files, runs a smoke test before starting gateways, and checks logs after every restart. Community support data shows Docker, install, gateway, and Discord failures are one of the highest-volume troubleshooting clusters.
Use this page when you want a self-hosted Hermes service that survives SSH logout, server reboot, or container rebuilds. If you only need isolated shell execution from a local Hermes session, use the Docker terminal backend guide instead.
Managed cloud · API costs included · Skill library · Cancel anytime
Before you start:
- ☑Docker Engine and docker compose installed
- ☑A working Hermes config and provider/API key outside Docker
- ☑A decision on which gateways, cron jobs, or web UI should stay always-on
- ☑A safe place for .env/config files that will not be committed
Steps
- 1
Verify Docker and Compose
Run docker --version and docker compose version before changing Hermes configuration.
- 2
Prove Hermes works outside Docker
Run hermes doctor and one hermes chat -q smoke test locally so provider errors are not confused with container errors.
- 3
Create persistent Hermes storage
Mount ~/.hermes or a named volume to the container Hermes home so config, .env, memory, sessions, and skills survive restarts.
- 4
Pass secrets through env or mounted files
Keep provider keys and bot tokens in .env/config files, not in Docker images or committed compose files.
- 5
Start with a restart policy
Use docker compose up -d with an unless-stopped style restart policy for always-on gateway or cron workflows.
- 6
Run gateway and log checks
Inside the container, run hermes doctor, hermes gateway status, and docker compose logs -f for the Hermes service.
- 7
Separate container failures from provider failures
Inside the container, run hermes config path, hermes config env-path, hermes doctor, and one small hermes chat -q smoke test before debugging Telegram, Discord, cron, or MCP.
Pro Tips
- 💡Run hermes doctor and one hermes chat -q smoke test before blaming Docker.
- 💡Persist the Hermes home directory so memory, sessions, skills, and config survive rebuilds.
- 💡Use a narrower gateway profile for Discord, Telegram, or Slack bots than your full local coding profile.
- 💡If VPS/Docker maintenance is not worth it, use FlyHermes as the managed path.
- 💡Recent buyer-language searches mention VPS prompts freezing, dashboard unreachable, and Telegram/Discord gateway confusion; treat those as signals that the managed path may be cheaper than more container debugging.
- 💡Use the pricing page to compare the real cost of VPS, provider spend, dashboard security, and weekly maintenance against a managed setup.
- 💡If the real goal is dashboard visibility, Telegram/Discord uptime, or browser/mobile access without VPS upkeep, compare FlyHermes before expanding self-hosted infrastructure.
- 💡Use the Hermes dashboard/Web UI as a status checkpoint, but verify success with the real command, channel message, cron delivery, or deployed URL that matters.
Troubleshooting
❌ Container starts but Hermes forgets config or memory
✅ Mount ~/.hermes or a named persistent volume to the container Hermes home. A stateless container will lose config, sessions, memory, and skills on rebuild.
❌ Discord or Telegram works locally but not in Docker
✅ Verify bot tokens, allowed IDs, and gateway env vars are present inside the container, then inspect docker compose logs for the Hermes service.
❌ Gateway restarts in a loop
✅ Run hermes doctor inside the container, check provider keys, and temporarily disable gateways until a basic chat smoke test passes.
❌ The dashboard is reachable from the internet
✅ Do not expose the Web UI directly without auth, HTTPS, firewall rules, and a reverse proxy. Treat it as an admin interface.
❌ Gateway works on host but fails in Docker
✅ Check mounted ~/.hermes paths, env-file loading, UID/GID ownership, exposed ports, and whether a stale host gateway is still polling the same platform token.
FAQ
What should I persist in Docker Compose?
Persist the Hermes home directory containing config.yaml, .env, sessions, memory, and skills. Otherwise Hermes can lose the state that makes it useful.
Should API keys go in docker-compose.yml?
No. Use an env file, mounted config, Docker secrets, or your host secret manager. Do not commit provider keys or bot tokens.
Is Docker Compose the same as the Docker terminal backend?
No. Docker Compose runs Hermes as a long-lived service. The Docker terminal backend isolates shell commands from a local Hermes session.
Why prioritize Docker troubleshooting?
Recent community evidence showed install/update/docker/windows as one of the largest support clusters, with gateway and Discord failures often overlapping container setup.
Should I debug Hermes Docker before provider or gateway settings?
Yes. First prove the container can read the mounted Hermes home, secrets, PATH, and provider config with hermes doctor and one small hermes chat -q run. Then restart gateway/platform checks. Otherwise Docker volume or UID errors can masquerade as provider or bot failures.