Running Hermes Agent in Docker

The official Hermes container separates the immutable application tree from persistent agent state. Configuration, credentials, sessions, memory, skills, cron jobs, hooks, and logs live in a mounted data directory while the image can be replaced during upgrades.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/docker

State and supervision

Mount a dedicated host directory at /opt/data. The installed application under /opt/hermes is treated as immutable, while normal agent-managed changes stay under the data mount. In gateway mode, current images use s6-overlay to supervise the gateway and optional dashboard processes.

Publish only the ports you need. The messaging gateway does not require the OpenAI-compatible API port unless another client must reach it. A non-loopback dashboard or API surface needs deliberate authentication and network controls; localhost, an SSH tunnel, or a private VPN is a safer default.

Deployment checklist

Mount one durable data directory at /opt/data.
Back up the data directory before image upgrades.
Run as the documented unprivileged user and align host volume ownership.
Set a restart policy for an always-on gateway.
Publish only required ports.
Require authentication on every non-loopback management surface.
Add sufficient shared memory when browser tools use Playwright.
Avoid running two gateway containers against the same data directory.

Pitfalls

Treating the container filesystem as persistent state.
Publishing the dashboard or API server without a working auth gate.
Running administrative commands as root and creating unreadable profile files.
Using localhost to reach a model server that actually runs on the host or another container.
Assuming container restart proves the gateway, model, and messaging adapters are healthy.

Verification steps

Restart the container and confirm profiles, sessions, skills, and config survive.
Inspect docker logs and the per-profile Hermes logs.
Run hermes version and hermes doctor inside the container.
Verify the gateway status for every enabled profile.
Probe only the intentionally published health or API endpoints.
Confirm non-loopback dashboard access requires authentication.
Stop and recreate the container from the same data mount, then repeat a harmless end-to-end message.