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:stable with gateway run, restart: unless-stopped, and persistent storage at /opt/data. If enabling the dashboard, configure authentication for its non-loopback container listener and protect the host access path. A private tunnel alone does not remove that authentication requirement. 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.
Command map
docker inspect --format '{{.Config.Image}} {{.Image}}' hermesRecord the image reference and immutable image ID of the existing container. Replace hermes if your container has another name.
Do not dump the full container environment into a public issue.
docker exec hermes hermes --versionRead the CLI version inside the running gateway container, not a new temporary container.
docker compose up -d --no-deps --force-recreate hermesAfter backing up state and pulling the intended image, replace only the service named hermes.
This interrupts service. Preserve the data mount and repeat the reply test after replacement.
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
- ✓Host or sidecar Ollama connectivity with an inside-container /v1/models check
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.
Image replacement: latest and stable follow the stable release gate; main is the development channel. Pulling an image does not replace the running container. Record the running image ID or digest, back up /opt/data, recreate the service, and repeat provider plus exact-channel checks. Retain the previous tested image and a compatible state backup for rollback.
Local inference adds a network boundary. Use host.docker.internal:11434/v1 for host Ollama on macOS/Windows, or ollama:11434/v1 for a Compose sidecar. Never validate only from the host shell; query the endpoint from the Hermes container and copy the exact model ID.
For the dashboard inside the official container, publish 9119 only to the private path that needs it and enable HERMES_DASHBOARD=1. After startup, use the Web UI resource banner and System page to catch low-memory, low-disk, or suspected OOM evidence, then verify one real gateway delivery after container recreation.
Before choosing Compose, use the Hermes Agent Docker vs native install guide to separate whole-agent containers from the Docker terminal backend. Native is the simpler first-run path; Compose is the deliberate image, volume, network, and supervision path.
Verify the running service before an upgrade. Use docker compose ps to identify it, then inspect its image ID and run hermes --version inside that container. Matching Desktop and Docker display versions alone do not establish runtime compatibility. Preserve the first import or unexpected-argument traceback privately instead of guessing which dependency to reinstall.
The image has curated Python extras, not the entire native Desktop bundle. Do not repair missing adapters by modifying /opt/hermes or blindly installing all extras. Build a tested derived image for additional dependencies and document its constraints.
Host-loopback publishing and container binding are separate. Publishing 127.0.0.1:9119:9119 limits host access but does not change the dashboard's usual 0.0.0.0 bind inside the container; its authentication requirement still applies. Self-hosted WebUI includes PTY/WebSocket Chat. Port 8642 is a separate optional API surface.
On VM-backed bind mounts, inspect doctor warnings about SQLite WAL before reusing old state. A native named volume can avoid that filesystem boundary, but attaching an empty volume does not migrate existing sessions. Stop all database users and follow the official offline procedure rather than removing WAL files.
Best use cases
Related Hermes Agent guides
Docker installation and running-image checks
Set up the official image and distinguish runtime failures from provider errors.
Step-by-step Compose setup
Configure persistence, ports and local-model networking.
Docker terminal backend
Isolate tool execution without confusing it with the gateway container.
Discord sandbox file access
Mount only task files instead of exposing the whole credential directory.
Managed versus self-hosted operation
Decide who owns updates, backups and runtime recovery.
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.
Capture the first error and running image identity, verify profile paths and doctor inside that container, then plan a tested image replacement if needed. Preserve /opt/data; do not blindly upgrade packages in the immutable application tree.
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.
Use host.docker.internal:11434/v1 for host Ollama on macOS/Windows or ollama:11434/v1 on a shared Compose network, then verify /v1/models from inside Hermes.
Publish port 9119 to a private or authenticated route and set HERMES_DASHBOARD=1 for the supervised gateway container. Keep /opt/data persistent, then verify the dashboard plus one real channel delivery after recreation.
Use native Hermes for the shortest path and easiest host integrations. Use Compose when your team wants an image-managed application with persistent /opt/data, explicit networking, supervised gateway lifecycle, and tested container replacement. See the Docker-vs-native guide for the full decision.
No. Pull changes the local image reference. Recreate the Hermes service to use it, preserving /opt/data, then verify the running image ID, provider request and real channel reply. Keep a tested rollback image and compatible state backup.