Tool
Hermes Docker Compose Setup for Self-Hosting
Use the official Hermes Agent Docker image with /opt/data persistence, s6-supervised gateways, authenticated dashboard access, logs, profiles, and safe updates.
Quick answer
Run `nousresearch/hermes-agent:latest` with `gateway run`, `restart: unless-stopped`, and a bind mount from host `~/.hermes` to container `/opt/data`. Enable the dashboard only with a private tunnel or configured authentication. Do not share one data volume between two gateway containers.
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
- ✓Official `nousresearch/hermes-agent:latest` image
- ✓Persistent host `~/.hermes` to container `/opt/data` mount
- ✓s6-supervised gateway and optional dashboard services
- ✓Immutable `/opt/hermes` application tree
- ✓Persistent profile gateway logs and boot audit log
- ✓One-container multi-profile supervision
- ✓Optional API/health port 8642
- ✓Optional authenticated dashboard port 9119
- ✓Restart-safe config, memory, sessions, skills, cron, hooks, and logs
- ✓Clear separation from the Docker terminal sandbox backend
Why this tool matters
The state contract: everything operators expect to survive belongs under `/opt/data`: `.env`, config, SOUL, profiles, sessions, memories, skills, cron, hooks, logs, skins, and subprocess home data. Back up the host mount, not the immutable image filesystem.
The supervision contract: the current official image uses s6-overlay. `gateway run` registers supervised gateway services and can supervise the dashboard alongside them. Docker restart policy keeps the container up; s6 restarts the inner services.
The network contract: chat gateways can run without publishing 8642. Publish API or dashboard ports only for a defined client, and authenticate non-loopback dashboard access. A raw public admin port is not a shortcut.
The profile contract: one container can host several Hermes profiles with separate state and supervised gateways. Separate containers are for stronger resource, image, network, or compliance isolation, never for concurrent writes to the same data directory.
The update contract: pull and recreate the image while retaining `/opt/data`, then rerun doctor, gateway status, logs, and one real channel test. Container recreation is routine; state replacement is not.
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.
The dashboard binds non-loopback inside the container. Current Hermes requires Basic Auth, Nous OAuth, or OIDC for that exposure; otherwise it stops with a configuration error. Use authenticated access or bind loopback behind SSH/Tailscale.
Use `docker logs -f hermes` for live output. The bind-mounted data directory also keeps per-profile logs under `~/.hermes/logs/gateways/<profile>/current` and boot reconciliation in `~/.hermes/logs/container-boot.log`.