Hermes Agent in Docker

Several ranking tutorials mix these up. If you only want the agent's commands sandboxed, you don't need to containerize Hermes; see the official Configuration → Docker Backend docs. The rest of this page is about running Hermes itself in a container.

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

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    volumes:
      - ~/.hermes:/opt/data

$docker compose up -d
$docker compose logs -f
$docker exec -it hermes hermes          # chat inside the running container

• A gateway with no ports published is enough for Telegram, Discord, and other chat platforms: they connect outward. Publish ports only for the API server or dashboard (below).
• Nous Portal sign-in works inside the container: run hermes setup --portal once and the token persists in the volume.
• The docs warn against pasting these commands into browser-based VPS consoles, which can mangle :, @, and =. Use SSH.
• Images are built for amd64 and arm64. Tags: latest/stable (release-gated), main (development builds), and versioned tags; use an image digest for an exact pin.

/opt/data is the container's HERMES_HOME — the single source of truth. It holds .env (API keys), config.yaml, SOUL.md, state.db and sessions, memories/, skills/, cron/, profiles/, logs/, and home/ (the HOME that tool subprocesses such as git and ssh see). The application under /opt/hermes is read-only to the runtime user.

• Permissions: processes run as UID 10000. If your host directory belongs to another user, set HERMES_UID/HERMES_GID (or PUID/PGID) to match. Don't make the directory world-readable — it contains credentials.
• Backups: back up this directory with hermes backup run inside the container, not by copying state.db on its own — see Hermes backup and restore.
• Tools you apt install inside a running container disappear when it is recreated. The docs suggest npx/uvx, a derived image, or a sidecar container for durable tools.

Hermes keeps sessions in SQLite (/opt/data/state.db) in WAL mode by default. WAL needs shared memory that stays consistent between processes, and bind mounts that cross a VM boundary don't provide it: virtiofs (Docker Desktop and Podman on macOS, OrbStack) and 9p/drvfs (Docker Desktop on Windows). The official docs say concurrent writers on those mounts can silently corrupt the database while it still passes an integrity check. A Linux host with a normal bind mount is not affected.

• Since v2026.9.14 (v0.21.3) a new database on such a mount is created in rollback mode automatically, with a warning.
• An existing WAL database on such a mount is not converted live; every process logs an error and hermes doctor flags it.
• NFS, SMB, and generic FUSE mounts are not detected — set database.journal_mode: delete yourself on those.

# Option A: named volume (lives on the Docker VM's own filesystem; WAL works)
$docker run ... -v hermes-data:/opt/data nousresearch/hermes-agent gateway run
$
# Option B: keep the bind mount, convert once with every Hermes process stopped
$docker exec hermes python3 -c "import sqlite3; print(sqlite3.connect('/opt/data/state.db').execute('PRAGMA journal_mode=DELETE').fetchone()[0])"
# then in /opt/data/config.yaml:
#   database:
#     journal_mode: delete

A named volume is not a folder you can open in Finder or Explorer; reach its files through the container (docker exec) or docker cp. Background on the wider state.db problems in v0.21.0–v0.21.1 is on the backup page.

Browser automation (Playwright/Chromium) needs more shared memory than Docker's default. The official troubleshooting fix is --shm-size=1g on docker run, or in Compose:

services:
  hermes:
    shm_size: "1g"

The Docker guide's recommended minimums for the container are 1 GB RAM and 1 CPU core without browser tools, and at least 2 GB with them (2–4 GB recommended); its Compose example caps the container at 4 GB and 2 CPUs.

Never run two Hermes gateway containers against the same data directory. The docs say session and memory stores are not designed for concurrent writers from separate containers. To run several agents, use profiles inside one container:

$docker exec hermes hermes profile create research   # gets its own supervised gateway
$docker exec hermes hermes -p research gateway start
$docker exec hermes hermes gateway status

• The image runs s6-overlay as PID 1. Each profile gets its own supervised gateway that restarts within seconds if it crashes, with rotated logs at logs/gateways/<profile>/current.
• After a container restart or image upgrade, every gateway whose last state was running comes back; only one you stopped with hermes gateway stop stays down.
• docker exec hermes hermes … automatically drops from root to the runtime user, so files it writes stay readable by the gateway.
• Separate containers per profile still make sense for per-workload memory limits, different image versions, or network separation — each with its own data directory.
• Don't override the image's entrypoint: skipping s6's /init breaks setup and leaves zombie processes. If you must, add init: true.

Inside the container the dashboard binds 0.0.0.0 by default so a published port can reach it. Any non-loopback bind requires an auth provider, and without one the dashboard refuses to start. The old --insecure escape hatch is gone; HERMES_DASHBOARD_INSECURE is now ignored. The docs tie that change to a June 2026 campaign in which scanners reached exposed dashboards and planted SSH-key backdoors through the agent.

$docker compose pull
$docker compose up -d
$
# or without Compose
$docker pull nousresearch/hermes-agent:latest
$docker rm -f hermes
$docker run -d --name hermes --restart unless-stopped -v ~/.hermes:/opt/data nousresearch/hermes-agent gateway run

• On start, the new image migrates config.yaml automatically and writes timestamped backups of config.yaml and .env first. Set HERMES_SKIP_CONFIG_MIGRATION=1 to inspect before it does.
• Recreating is safe for your data because it lives in the volume; it discards anything installed into the container by hand.
• Images built before late August 2026 could lock the runtime user out of /opt/hermes (every docker exec fails with Permission denied). Pulling a current image fixes it.
• Taking a backup before a major version jump costs one command.

Docker is one of three documented ways to run Hermes on a server; provisioning, firewalling, and choosing between Docker and a native install with a systemd service are covered in the VPS guide. On a Linux VPS the SQLite bind-mount trap above does not apply.

To reach Ollama or another inference server from inside the container, use host.docker.internal on macOS/Windows, host networking on Linux, or a shared Compose network with the service name (for example http://ollama:11434/v1). Requirements for the model itself are on Hermes local models.