Run the official Hermes Agent image when you want a container-managed gateway with persistent data. You do not need a native Hermes installation first. You do need a working Docker engine, a model provider, and a data volume you can back up.
This guide covers the whole application container. If Hermes already runs on your host and only its commands need isolation, use the Docker terminal backend guide instead.
Quick answer#
Use nousresearch/hermes-agent:latest or :stable, mount your chosen data directory at /opt/data, run setup once, then start gateway run. Check the version and provider from inside that running container. Keep /opt/hermes unchanged; update the image rather than installing packages into its bundled environment. The Compose walkthrough covers the longer setup. For managed operation, compare FlyHermes and self-hosting.
Whole-agent container or terminal-only sandbox?#
The image in this guide runs the Hermes process tree inside a container. Setting terminal.backend: docker in an agent running on your host is narrower: it isolates shell and file operations, not the host agent process, code-execution child, MCP subprocesses, plugins or hooks. The official security policy, section 2.2, checked November 20, 2026, requires whole-process wrapping for untrusted input or shared production use.
Containment still depends on what you expose. Review bind mounts, shared volumes, network access and credentials. Do not mount the host Docker socket as a shortcut. Profiles inside a shared container remain one trust envelope; separate untrusted tenants need separate OS users or appropriately configured whole-agent containers, not another profile name. See the server hardening checklist for the access checks and the self-hosting decision guide for ownership trade-offs. We have not performed a container-escape or tenant-isolation test here.
One shared home hub does not require one container per client#
If several computers should use the same agent, connect them to the intended server backend and profile. Do not create a new Hermes container on each client merely to display the shared agent. The Desktop connection documentation places sessions and memory on the machine that owns that profile.
For the whole-agent image, the official Docker guide places user state in the host directory mounted at /opt/data. Record that host-side path or volume name, the running image digest and the intended profile in the recovery inventory. A copy of the image is not a backup of the state, and an identically named empty volume on another host is not your original workspace.
Before moving a home hub, stop its writers during the protected state copy, restore to the intended destination and verify a harmless session and file before switching clients. Keep only the intended gateway active for each messaging token; do not run both copies as an improvised high-availability pair. This is migration guidance, not a tested multi-node deployment recipe.
Sources checked October 19, 2026. The home, VPS and managed comparison helps choose where the state should live before you decide how to package it.
Choose the image before copying commands#
The official Docker documentation distinguishes these tags:
latestandstablefollow the image accepted by the stable release gate. A commit on the main branch does not automatically update them.mainis the development image. Use it deliberately for testing, not as an assumed repair for every production failure.- A version tag identifies a stable release. A digest pins the exact image; record it before an upgrade if you need reproducible rollback.
A Desktop version label and a container version label are not enough to identify the runtime that handled a failed request. Record the Desktop build separately, the selected remote connection, the running container's image ID, and the CLI version inside it. Pulling a tag changes the local image reference; it does not replace an already running container.
The image's Python environment follows its own pyproject.toml and uv.lock. It uses a curated set of extras rather than the native Desktop bundle's full extras, and it does not contain the Electron Desktop app. A missing adapter or import therefore deserves an image/dependency check before you replace a bot token.
First setup without a second Hermes installation#
Use SSH rather than a browser-based VPS console for pasted commands. Some provider consoles corrupt punctuation in volume arguments or credentials. The commands below assume a new installation and an unused hermes container name. If this host already runs a Hermes gateway, stop and identify its data directory before reusing it.
mkdir -p "$HOME/.hermes"
docker run -it --rm \
-v "$HOME/.hermes:/opt/data" \
nousresearch/hermes-agent:stable setup
Complete provider and gateway setup interactively. Keep credentials in the mounted .env or your secret-management system, not in an image, public Compose file, or support screenshot. Never run two gateway containers against the same data directory.
For a chat-only gateway, you can start without publishing an HTTP port:
docker run -d \
--name hermes \
--restart unless-stopped \
-v "$HOME/.hermes:/opt/data" \
nousresearch/hermes-agent:stable gateway run
The current official image uses s6 supervision for the gateway and optional dashboard. Docker's restart policy and the inner service supervisor have different jobs. A container showing Up is still not proof that the model or chat platform works.
On Docker Desktop, also read the storage warning below before moving existing session data into this mount.
Verify the running image, not a fresh temporary container#
These commands inspect the container named hermes. Replace that name if yours differs. They show identity and paths without dumping its environment variables.
docker inspect --format '{{.Config.Image}} {{.Image}}' hermes
docker exec hermes hermes --version
docker exec hermes python3 --version
docker exec hermes hermes config path
docker exec hermes hermes config env-path
docker exec hermes hermes doctor
docker exec hermes hermes gateway status
docker logs --tail 80 hermes
Keep logs private until you have removed tokens, message content and personal paths. A command such as docker run --rm ... --version checks a newly created container; it cannot prove which image your existing gateway is running.
Then request one harmless answer from the provider:
docker exec hermes hermes chat -q \
"Reply with docker-check-1 only. Do not use tools."
This request can incur model usage. Verify provider routing from configuration and logs, not from a model's claim about its own identity. Finally, send one message yourself in the exact Telegram chat or Discord channel you intend to use and check for the reply there. These are acceptance checks for your deployment, not a claim that we ran a bot on your behalf.
Diagnose an import error before reinstalling everything#
If the container starts but one platform never appears, save the first startup exception and the exact missing module name. Compare the running image with the release you intended to deploy. Telegram starting successfully does not prove that Discord's adapter loaded.
- An import or unexpected-argument error points to runtime/package compatibility. Capture the complete traceback privately before changing configuration.
- A CLI model request failing with an authentication or quota error belongs in the provider troubleshooting guide.
- A connected adapter that receives messages but never replies belongs in gateway troubleshooting.
- A terminal tool that cannot see a host file may be correctly sandboxed. Use the Docker/Discord filesystem guide; do not expose all credentials to repair one missing directory.
Do not install all optional extras, run a blanket package upgrade, or edit /opt/hermes as a generic fix. The published install tree is immutable. If your workload needs an extra dependency, build and test a derived image, or use a documented external tool path. Record the dependency and Python constraints so the next image replacement does not silently remove the fix.
Keep state separate from the image#
The persistent /opt/data directory holds config, secrets, sessions, memories, skills, profiles, cron definitions and logs. /opt/hermes holds the application. Mounting over the latter can hide the shipped code and bundled environment.
A persistent mount also needs suitable filesystem behavior. Current official docs warn that SQLite WAL shared-memory coordination is unsafe across some VM-backed bind mounts, including virtiofs and 9p/drvfs. A fresh database on a detected affected mount uses rollback journaling. An existing WAL database is flagged rather than converted while writers may still be active.
If hermes doctor reports this condition, back up the data and follow the official offline database procedure. Stop every process using the database before conversion, or migrate carefully to a native Docker volume. Do not delete state.db, its WAL, or shared-memory files as a troubleshooting shortcut. A named volume is a different storage location; attaching an empty one does not migrate your old data.
The Docker troubleshooting guide covers ownership, vision, gateway and persistence failures in more detail.
Add the dashboard without exposing an admin port#
Self-hosted Hermes WebUI includes real browser Chat through PTY/WebSocket, as well as configuration and monitoring. It is not limited to a read-only status page. See the WebUI guide for that interface.
Enable the supervised dashboard with HERMES_DASHBOARD=1 only after choosing its access policy. The dashboard normally binds to 0.0.0.0 inside the official container and requires an authentication provider on a non-loopback bind. Publishing 127.0.0.1:9119:9119 restricts the host-facing port, but does not change that internal bind or remove the authentication requirement. Keep Basic Auth behind a trusted network or VPN; use the documented OAuth/OIDC setup for appropriate public deployments.
Port 9119 is the dashboard/Remote Gateway surface. Port 8642 belongs to the optional OpenAI-compatible API server. Do not publish either simply because a copied example contains it. Keep credentials, TLS and proxy trust explicit; use the Compose reference for the operational checklist.
Update with a tested rollback path#
Before replacing a working container, record its image ID or digest, back up /opt/data, and keep the previous tested image available. Preserve the Compose file or equivalent run options. Do not run hermes update against the immutable application tree.
For the Compose service named hermes, the replacement commands are:
docker compose pull hermes
docker compose up -d --no-deps --force-recreate hermes
Expect a service interruption. Repeat the running-image checks, doctor, provider request and exact-channel reply test afterward. If you roll back an image, check state/config compatibility too: a previous image is not a substitute for a consistent backup. Do not run docker compose down -v or a broad Docker prune as part of this procedure.
Connect Ollama across the container boundary#
When Ollama runs on a Mac or Windows host, use http://host.docker.internal:11434/v1. When it is a service on the same Compose network, use http://ollama:11434/v1. Inside the Hermes container, localhost means that container, not your laptop.
Query the chosen endpoint's /models route from inside Hermes before changing model settings. Copy the returned model ID exactly. The Ollama setup guide covers context and tool-call checks after networking works.
Decide whether you want to operate this stack#
Docker gives you control over the image, filesystem and network. You still own backups, authentication, updates, provider access and recovery when a gateway stops replying. Native installation can be simpler for host integrations; the Docker versus native guide compares the boundaries.
Choose FlyHermes when managed operation is the reason you are looking for hosting. Choose self-hosting when those infrastructure choices are part of the work you want to control. Browser access alone does not distinguish them.