Hermes Docker Compose Setup
Docker Compose setup and troubleshooting for self-hosting Hermes Agent with persistent ~/.hermes storage, safe provider/API key handling, UID-aware volumes, gateway uptime, container logs, and protected dashboard access.
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
- ✓Protected dashboard/Web UI route for health checks
- ✓UID-aware volume ownership checks
- ✓Container boot config migration awareness
- ✓MCP env/header auth checks
- ✓v0.16 surface-release reminder: verify dashboard/admin exposure and remote backend access after container updates
- ✓Dashboard/Web UI check: keep port 9119 private, use --no-open/--port on servers, and verify Telegram/Discord delivery outside the container UI
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.
Recent Hermes Docker fixes make config migrations run during container boot, reject unsupported arbitrary UID starts with clearer guidance, and repair UID-remap ownership handling. If a Docker install fails after an update, update the image first, preserve the Hermes home volume, then inspect ownership and env propagation before rebuilding from scratch.
For Docker Compose installs, the dashboard should be treated as a private admin endpoint. Map it only when you know the host, port, firewall, and authentication boundary; then verify the real workflow with `docker exec ... hermes gateway status`, logs, and one Telegram/Discord message.
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.
Update to the latest Hermes image or checkout, keep the mounted Hermes home intact, run hermes doctor inside the container, and inspect UID/ownership plus provider/MCP environment variables before changing config.
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.