Run Hermes Agent with Docker

Direct answer

Run Hermes Agent in a container by mounting a host directory at /opt/data and starting the published nousresearch/hermes-agent image. The volume is the whole story: configuration, credentials, sessions, memories, and skills all live there. Publish ports only when something outside the host must reach the container, and update by replacing the image — hermes update is not supported for container installs.

Checked against Hermes Agent v0.20.5 on August 25, 2026. Re-check when the image name, the container data path, the published ports, or the dashboard authentication requirement changes.

When Docker is the right Hermes Agent path

Choose the container path when at least one of these is true:

You want the agent's filesystem reach separated from your host by default.
You are deploying to a server and want a reproducible runtime.
You need several isolated instances on one machine.

Choose a host install instead when you want the agent to work directly on files already on your machine, or when in-place hermes update matters to you.

Container prerequisites

A working Docker installation, with your user able to talk to the daemon.
A host directory for state. ~/.hermes is the documented default mount source.
Documented resource guidance: 2–4 GB of memory (1 GB minimum), 2 CPU cores (1 minimum), and 2 GB or more of disk. Browser automation needs at least 2 GB on its own.

Choose image/profile and deployment shape

Container deployment shapesShape = how the container is started and what it runs. State = where durable data lives. Exposure = which ports must be published for the shape to work.

Shape	Command	State	Exposure
One-off interactive setup	setup, with --rm	Host volume at /opt/data	None
Interactive CLI session	default entrypoint, with -it --rm	Host volume at /opt/data	None
Long-running gateway	gateway run, detached with a restart policy	Host volume at /opt/data	Only what you publish
Gateway plus browser dashboard	gateway run with HERMES_DASHBOARD=1	Host volume at /opt/data	Dashboard port, which then requires an authentication provider

Source: Nous Research Docker guide, checked 25 August 2026 against v0.20.5. The documented image is nousresearch/hermes-agent:latest, based on Debian 13.4 with Python 3.13 and Node.js 26.

The repository also ships a docker-compose.yml that builds the image locally and runs the gateway and dashboard as two services with network_mode: host. In that file the dashboard binds to 127.0.0.1 deliberately, and the comments warn against serving it on 0.0.0.0 without authentication in front of it.

Create persistent storage

Create the host directory before the first run, so the container does not create it with unexpected ownership:

bashAny Docker host

mkdir -p ~/.hermes

Expected result: The directory exists and is owned by your user.

Source: Nous Research Docker guide, checked 25 August 2026

Everything durable lives under that single mount at /opt/data: config.yaml, .env, auth.json, sessions, memories, skills, cron jobs, and logs. Back that directory up and you have backed up the deployment.

Configure providers and secrets

Run the interactive wizard once, in a throwaway container that writes to the persistent volume:

bashAny Docker host

docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent setup

Expected result: The setup wizard runs interactively and writes provider configuration into ~/.hermes on the host.

Source: Nous Research Docker guide, checked 25 August 2026

Keys can also be injected as environment variables, which override values in the .env file and are persisted to /opt/data/.env:

bashAny Docker host

docker run -it --rm -v ~/.hermes:/opt/data -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" nousresearch/hermes-agent

Expected result: The container starts with the provider credential available to the agent.

Placeholders only. Do not paste a real key into a shell command that lands in your history — prefer an env file with 0600 permissions, or your platform's secret store.

Source: Nous Research Docker guide, checked 25 August 2026

Start Hermes Agent

bashAny Docker host

docker run -d --name hermes --restart unless-stopped -v ~/.hermes:/opt/data -p 8642:8642 nousresearch/hermes-agent gateway run

Expected result: A detached container named hermes running the messaging gateway, restarting unless explicitly stopped.

Source: Nous Research Docker guide, checked 25 August 2026

Run any CLI command against the running container — commands drop to the non-root hermes user automatically:

bashAny Docker host

docker exec hermes hermes doctor

Expected result: The diagnostic report, produced inside the container against the mounted configuration.

Source: Nous Research Docker guide, checked 25 August 2026

Expose dashboard or gateway safely

Two ports matter: 8642 for the OpenAI-compatible API server, and 9119 for the browser dashboard. Neither should be published without a deliberate decision.

Publish nothing if you only use the container interactively. That is the safe default.
The API server requires a key. API_SERVER_KEY is mandatory for every deployment, including a loopback bind, because that endpoint exposes the full toolset, terminal included.
The dashboard requires an authentication provider when it binds beyond loopback — basic auth, OAuth, or OIDC environment variables. There is no unauthenticated escape hatch on a public bind.
Prefer a tunnel over a public port. An SSH tunnel to 127.0.0.1:9119 gives you remote access without an internet-facing service.

The Docker guide's own summary is worth repeating: opening any port on an internet-facing machine is a security risk. Controls, threat model, and the hosted baseline belong to secure container deployment.

Apply the security baseline before publishing any port

Verify persistence and tools

Check all four before you rely on the deployment:

docker exec hermes hermes doctor reports a healthy configuration.
Files appear in ~/.hermes on the host after a session — that proves the mount works.
Recreating the container preserves sessions and configuration.
A task that uses a tool actually shows the tool call, not just an answer.

bashAny Docker host

docker logs -f hermes

Expected result: Streaming container logs; use them to confirm the gateway started and to read startup errors.

Source: Nous Research Docker guide, checked 25 August 2026

Update, back up, and roll back

Container installs update by replacement, not in place.

bashAny Docker host

docker pull nousresearch/hermes-agent:latest

Expected result: The newer image is downloaded; the running container still uses the old one until it is recreated.

Source: Nous Research Docker guide and Platform Support, checked 25 August 2026

Then recreate the container with the same volume and flags. With Compose the equivalent is docker compose pull followed by docker compose up -d.

Back up first. Copy or snapshot ~/.hermes before recreating. It contains credentials, so protect the copy.
Roll back by recreating the container from a previously pulled image tag against the same volume.
Do not run hermes update in a container. Platform Support documents that Docker installs do not support it.

Fix Docker failures

Container-specific failure pathsRead one row left to right: the symptom names the component to suspect, the check tests it, and the expected result tells you whether to stop or move on.

Symptom	Suspect component	Check	Expected result	If it still fails
Container exits immediately	Entrypoint or command arguments	docker logs hermes	A startup error naming the failing service	Confirm the entrypoint was not overridden and the volume is mounted at /opt/data
Configuration resets on every run	Volume mount	ls ~/.hermes on the host after a session	config.yaml and session files present on the host	Re-check the -v ~/.hermes:/opt/data argument and directory ownership
Dashboard refuses to start on a public bind	Dashboard authentication	Confirm a basic-auth, OAuth, or OIDC provider is configured	The dashboard starts with authentication enforced	Bind to loopback and reach it through an SSH tunnel instead
Browser tool crashes or times out in the container	Shared memory and container RAM	docker stats hermes while the task runs	Memory stays within the limit; at least 2 GB available	Restart the container with --shm-size=1g and a higher memory limit
State looks corrupted or duplicated	Two gateways sharing one data directory	docker ps for a second container on the same volume	Exactly one gateway per data directory	Stop the duplicate, then restore the data directory from backup

Source: Nous Research Docker guide, checked 25 August 2026 against v0.20.5.

Failures that are not container-specific — provider authentication, configuration validation, model errors — belong to Docker troubleshooting, which isolates by component.

Choosing where that container should run — your machine, a server you manage, or a managed backend — is a separate decision covered by the hosting decision guide.