Hermes Agent Docker Compose Setup with the Official Image

❌ The dashboard starts and immediately stops

✅ A dashboard bound beyond loopback requires an authentication provider. Configure Basic Auth, Nous OAuth, or OIDC, or bind to loopback and connect through SSH/Tailscale.

❌ State disappears after container recreation

✅ Verify the host directory is mounted exactly as ~/.hermes:/opt/data. Inspect the host path for config, sessions, memories, skills, cron, and logs before recreating again.

❌ Gateway is running but Telegram or Discord does not reply

✅ Check docker exec hermes hermes gateway status, current container logs, the active profile, token presence, allowed chats/channels, mention rules, and topic/thread routing. Then send an end-to-end test.

❌ Hermes works on the host but provider or MCP calls fail in Docker

✅ Run hermes config path, hermes config env-path, and hermes doctor inside the container. The host environment may have credentials or PATH entries that were never mounted or forwarded.

❌ Docker files are owned by the wrong UID

✅ Inspect ownership of host ~/.hermes and avoid arbitrary --user overrides unless the image explicitly supports them. Back up state before changing ownership.

❌ Port 8642 is open but the API does not respond

✅ The API server requires API_SERVER_ENABLED=true; non-loopback binding also requires API_SERVER_HOST=0.0.0.0 and an API_SERVER_KEY of at least eight characters. Do not expose it without a real need.

❌ The container says hermes update is unsupported

✅ Update the Docker image instead of the immutable application tree. Pull and recreate the service while keeping the host Hermes home mounted at /opt/data.

What is the official Hermes Agent Docker image?

Use nousresearch/hermes-agent:latest unless you deliberately pin a tested release tag. The official image stores mutable state in /opt/data and keeps the installed application under /opt/hermes immutable.

Where does Hermes Agent store data in Docker?

Mount host ~/.hermes to container /opt/data. It contains .env, config.yaml, SOUL.md, sessions, memories, skills, profile home directories, cron jobs, hooks, logs, and skins.

Do I need to publish port 8642?

No for chat-only gateways. Port 8642 is for the optional OpenAI-compatible API server and health endpoint. Enable and publish it only when an external client or dashboard workflow actually needs it.

Can I expose the Hermes dashboard directly to the internet?

Do not expose it without authentication and transport security. A non-loopback dashboard now fails closed unless Basic Auth, Nous OAuth, or OIDC is configured. SSH tunneling, Tailscale, or a trusted authenticated reverse proxy is safer.

Is running Hermes in Docker the same as the Docker terminal backend?

No. Full-container deployment runs Hermes, gateways, and optional dashboard inside the official image. terminal.backend: docker runs only tool commands in a hardened persistent sandbox while Hermes stays on the host.

Should each Hermes profile use a separate container?

Usually no. The official s6-based image supervises multiple profiles in one container. Use separate containers only when you need independent resource limits, image versions, networks, or credential blast radii.

When should I use FlyHermes instead of Docker?

Choose Docker for infrastructure control and custom networking. Choose FlyHermes when you want managed uptime, browser/mobile access, connected channels, and less responsibility for updates, authentication, backups, gateway recovery, and provider operations.

Do multiple Docker profiles need multiple dashboard ports?

No. One dashboard backend can serve co-located profiles. Multiple externally exposed OpenAI-compatible API servers are separate and require distinct profile-specific API ports.