Run Hermes Agent in Docker: setup, Compose and updates

The official image and your first run

The official image is nousresearch/hermes-agent on Docker Hub, built for both amd64 and arm64. Every release has its own version tag, and the one this guide is written against, v2026.9.24, exists on Docker Hub (checked 23 October 2026). In the current upstream build workflow, latest is a stable-release alias and pushes to the main branch update a separate main tag, so latest will move to newer releases over time. The examples below use the pinned tag so that what you run matches what you read; swap in a newer tag, or latest, when you deliberately want to upgrade. Tags with a -desktop suffix are a larger variant with a headed browser; the plain tags are the slim image.

Hermes keeps its state — settings, API keys, conversations, memory, skills — in one directory, mounted into the container at /opt/data. Create that directory on the host and run the setup wizard once, interactively:

mkdir -p ~/.hermes
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent:v2026.9.24 setup

The wizard saves your provider settings and credentials under the mounted Hermes data directory. You do this once; later containers pick the settings up from the same folder. The Hermes docs also suggest connecting a chat app at this stage, because the gateway is what makes the agent useful when you are not at the keyboard. If you are not sure which install route you need, how to install Hermes Agent compares Docker with the desktop app and the one-line installers.

One warning from the upstream docs: do not paste these commands into a browser-based VPS console. Some of them mangle characters such as : and @, which quietly corrupts the -v argument or a pasted key. Connect over SSH instead.

Run it in the background as a gateway

Once setup is done, start the container detached with the gateway run command. This is the process that connects Telegram, Discord, WhatsApp and the other chat apps and runs your scheduled jobs:

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

--restart unless-stopped brings the container back after it exits or after the Docker daemon or the host restarts, unless you explicitly stopped it. Inside the official image the gateway is also supervised by s6-overlay, so if the gateway process itself crashes it is restarted within a couple of seconds without the container going down.

Port 8642 is the gateway’s OpenAI-compatible API server and health endpoint. If you only use chat apps you can leave -p 8642:8642 out. Hermes turns the API server on when it finds a usable API_SERVER_KEY (at least 16 characters, and not a placeholder), and the official image generates one into .env if you have not set your own. By default it listens only inside the container, so to reach it from outside you also need API_SERVER_HOST=0.0.0.0 and the port published. openssl rand -hex 32 makes a good key. Hermes is blunt about the risk of opening ports on a machine that faces the internet: only do it if you understand it.

To chat in a terminal against the same data folder, run docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent:v2026.9.24. Do not run a second gateway container on that same folder, though: two gateways writing sessions and memory at once can damage them.

The same thing as a Compose file

This Compose file is adapted from the example in the Hermes docs. It runs the gateway and the web dashboard in one container, with the dashboard protected by a login and published only on the host’s own loopback address. It is an alternative to the docker run command above, not a second step: if you already started that container, stop and remove it first (docker rm -f hermes; your ~/.hermes folder is untouched) because both use the container name hermes:

services:
  hermes:
    image: nousresearch/hermes-agent:v2026.9.24
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "127.0.0.1:9119:9119"   # dashboard
    volumes:
      - ~/.hermes:/opt/data
    environment:
      - HERMES_DASHBOARD=1
      - HERMES_DASHBOARD_BASIC_AUTH_USERNAME=${DASH_USER}
      - HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=${DASH_PASSWORD}
      - HERMES_DASHBOARD_BASIC_AUTH_SECRET=${DASH_SECRET}
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"

Put DASH_USER, DASH_PASSWORD and DASH_SECRET (a long random string, openssl rand -hex 32 will do) in a .env file next to the Compose file, which Compose reads for the ${...} substitutions. Then run docker compose up -d and follow the output with docker compose logs -f. From your own computer, reach the dashboard with an SSH tunnel: ssh -L 9119:localhost:9119 user@your-server, then open http://localhost:9119.

Three details matter. The dashboard listens on 0.0.0.0 inside the container by default, and that is why a login is required: since mid-2026 Hermes will not serve the dashboard on any address other than loopback unless some form of authentication is set up, and it removed its old unauthenticated option after scanners found exposed dashboards. Setting HERMES_DASHBOARD_HOST=127.0.0.1 would not help here, because that is the container’s loopback and a published port cannot reach it. The 127.0.0.1: prefix keeps Docker from publishing the port on every network interface; Docker documents that guarantee for Engine 28.0.0 and newer, and older releases could expose such ports to other machines on the same network segment. And basic auth is meant for trusted networks, not for putting the dashboard on the open internet. If you do not need the dashboard, delete the HERMES_DASHBOARD and auth lines and the 9119 port.

The Hermes repository also ships its own docker-compose.yml, which builds from source, uses host networking and runs the dashboard as a second service bound to localhost. The example above is for people pulling the published image.

The data folder, permissions and file systems

/opt/data is the single source of truth. Hermes keeps its own state there and not in the image, so you can replace the container and the state stays. The folder contains:

• .env and config.yaml: your keys and all configuration.
• SOUL.md: the agent’s personality and identity.
• sessions/ and memories/: conversation history and long-term memory.
• skills/, cron/, hooks/ and logs/: installed skills, scheduled jobs, event hooks and runtime logs.

That promise covers what Hermes stores under /opt/data. Files the agent writes elsewhere in the container, and tools it installs with apt or similar, live in the container’s own layer and can be lost when you remove and recreate it. The upstream guidance is to keep any config or credentials for a tool under /opt/data, and to bake tools you need permanently into a derived image.

The first thing people hit is a permission error. The container drops to a non-root hermes user (UID 10000) to run the agent. If the host folder belongs to a different user, set HERMES_UID and HERMES_GID to that user’s IDs (the aliases PUID and PGID work too). The repository’s own Compose file is written around this and is started with HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -d. On a NAS such as Synology or unRAID, where the folder is a bind mount owned by a host user the container cannot change, setting PUID and PGID to that owner is the documented fix. Starting the gateway as root inside the official image is refused by default, because it can leave root-owned files that break later starts.

The second trap is the file system under the folder. Hermes keeps sessions in a SQLite database, state.db, in WAL mode, which needs shared memory to behave on every process that has the file open. Bind mounts that cross a virtual-machine boundary, as on Docker Desktop, Podman on Mac and OrbStack, can corrupt that database silently when several processes write to it. On those machines use a native named volume instead (-v hermes-data:/opt/data). If you already have a database on such a mount, the Hermes Docker docs describe an offline conversion: stop every Hermes process first. On a Linux server with a local disk this does not apply.

The installed application, /opt/hermes, is read-only to the agent at runtime, so a chat turn cannot edit Hermes’s own code. The agent’s self-improvement (skills, memory, plugins, config) is confined to the data folder.

Logs, restarts and common problems

The gateway’s output goes to docker logs -f hermes in real time, and to a rotated file at ~/.hermes/logs/gateways/default/current on the volume (10 archives of 1 MB). The file is the one that survives docker rm. Hermes’s own agent.log and errors.log sit in logs/, and docker exec hermes hermes logs --follow follows the agent log, and docker exec hermes hermes logs errors --follow follows the error log. For a quick check, docker stats hermes shows memory use.

On size, the docs give a floor of 1 GB of memory and 1 CPU core, and recommend 2 to 4 GB and 2 cores. Browser automation is the most memory-hungry feature, and with it switched on you should allow at least 2 GB. Plan on 2 GB or more of disk for the data folder, which grows as sessions and skills pile up.

Updating and backing up

Updating is a new image and a new container, because Hermes’s state lives outside the container. If you use the Compose file, edit the image tag, then run docker compose pull and docker compose up -d; every setting you saved in the file carries over. That is the safer route. With plain docker run, the new container only gets the flags you repeat, so keep your full command somewhere and reuse all of it, including any -p ports, UID and auth variables, memory limits and socket mounts. This is the setup command with a newer tag:

docker pull nousresearch/hermes-agent:<new-tag>
docker rm -f hermes
docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent:<new-tag> gateway run

On start, the container runs any needed settings migrations against your mounted config.yaml, and writes timestamped backups of config.yaml and .env first if it has to change them. Gateways that were running before the update start again by themselves. Because the example is pinned, an update is a deliberate change of tag.

Take a copy first. To back up the Hermes state stored in the mounted folder, stop all processes using it and archive ~/.hermes; back up any other files you rely on separately. Hermes also has its own command, which works while the agent is running because it copies the database safely:

docker exec hermes hermes backup
docker exec hermes hermes backup --quick --label "pre-upgrade"

The first makes a full zip of your configuration, skills, sessions and data. The second is a fast snapshot of just the critical state (config, database, .env, auth and cron jobs). Use -o to choose where the zip is written and make sure it ends up outside the container, for example under the mounted folder, then copy it off the machine. A backup on the same disk does not survive that disk failing.

The other use of Docker: a sandbox for the agent’s commands

Do not confuse running Hermes in Docker with the Docker terminal backend. The backend is a setting that makes the agent run every shell command inside a Docker container instead of directly on its host. You turn it on with:

hermes config set terminal.backend docker

Hermes starts one long-lived sandbox container and sends every terminal, file and code-execution call into it, so installed packages and files in /workspace carry over between tool calls. Setting terminal.container_persistent: false gives each conversation its own fresh sandbox instead. By default the container runs hardened: all Linux capabilities dropped except a few for package managers and privilege dropping, no privilege escalation, and size-limited temporary folders. A limit of 256 processes is applied when the host’s cgroup limits are available, and the no-new-privileges flag is left off if you turn on the terminal.docker_snap_compat option for snap-packaged Docker. Setting terminal.docker_network: false cuts all network access from the sandbox.

Two cautions from the upstream security page. First, the container is treated as the security boundary, so Hermes skips its dangerous-command approval prompts inside it, with two exceptions: the prompts stay on if you bind-mount host folders into the sandbox, and your own approvals.deny rules are enforced in every case. Second, anything you list in terminal.docker_forward_env is deliberately visible to code running in the sandbox, so keep that list short.

Combining the two is possible but takes a decision. The Hermes image includes the Docker command-line client, and you opt in to using the host’s Docker by mounting /var/run/docker.sock into the container. Anything that can talk to that socket can control Docker on the host, so treat that mount as handing over the machine.

When you would rather not run the container yourself

Everything above works, and for many people it is the right choice. It also leaves you with a small standing job: a host that stays up, patched and backed up, an image you remember to update, and a gateway you notice when it stops. Our self-hosting vs managed comparison goes through that trade honestly, including the cases where running it yourself wins.

On ReadyHermes, every agent gets a Docker container of its own on our servers, kept running around the clock. Scheduled jobs and chat apps keep working while your computer is off. We handle updates, and the Bot tools section of the workspace has a Backup tab and a Restore tab for your own copy of the agent. You use it from a browser workspace and from chat apps such as Telegram, WhatsApp, Discord and WeChat. A new agent is ready in about 10 seconds, and there is a 1-hour free trial.

Bot tools also has Files, SSH over Tailscale and an API endpoint, so a hosted agent is not a sealed box. What ReadyHermes does not do is run models on your computer or host your own local models on GPUs. For that, Docker on your own hardware is the right tool. To see what Hermes can do for work, start with Hermes Agent for business.