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.
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.
- 💡Use the pricing page to compare the real cost of VPS, provider spend, dashboard security, and weekly maintenance against a managed setup.
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.
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.