Hermes Docker Compose Setup
Docker Compose setup for self-hosting Hermes Agent with persistent ~/.hermes storage, safe provider/API key handling, gateway uptime, and container logs.
Quick answer
Use Docker Compose after the base Hermes CLI works: persist the Hermes home directory, pass provider/API keys through env or mounted config, add a restart policy, and verify hermes doctor plus gateway logs inside the container before sending production traffic.
Use Docker Compose when Hermes should run continuously on a VPS or home server. The critical details are persistent Hermes home storage, externalized secrets, a restart policy, and a smoke test that proves the CLI and gateway work inside the container.
Features
- ✓Persistent ~/.hermes volume
- ✓Provider/API key env handling
- ✓Gateway restart policy
- ✓Container logs and health checks
- ✓Docker terminal backend links
Why this tool matters
Docker Compose is a deployment wrapper, not a substitute for provider setup. Configure one model provider first, then move the same Hermes home into a persistent container volume so config.yaml, .env, sessions, memory, and skills survive restarts.
Do not confuse Docker Compose with the Docker terminal backend. Compose runs the agent as a service; the terminal backend lets a local Hermes session execute shell commands in isolated containers. Many Docker support issues disappear when those two paths are separated.
For gateway workflows, a green container status is not enough. Run hermes doctor, hermes gateway status, and a real Telegram or Discord message test from inside the container before calling the deployment healthy.
Best use cases
FAQ
Persist the Hermes home directory that contains config.yaml, .env, sessions, memory, and skills. Otherwise restarts and rebuilds can erase the state Hermes needs.
Keep secrets in an environment file, mounted config, or secret manager. Do not bake provider keys or bot tokens into images or public compose files.
No. Docker Compose runs Hermes as a long-lived service. The Docker terminal backend isolates shell commands from a local Hermes session.
Run hermes doctor, a hermes chat -q smoke test, hermes gateway status if gateways are enabled, and inspect docker compose logs for the Hermes service.