Hermes Agent Docker Compose guide

Short answer

Use Docker Compose for Hermes Agent when you want the same data directory, ports, environment variables, and restart policy to be repeatable. Do not expose the API or dashboard to the internet until you understand authentication, CORS, and gateway allowlists.

The most important choice is the data mount. The official Docker docs describe a mounted directory at /opt/data; that directory contains persistent user data such as config, API keys, sessions, skills, and memories.

Minimal Compose template

This template binds the API port to localhost on the host. If you need external access, put an authenticated reverse proxy in front of it and revisit CORS and allowlists.

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    volumes:
      - ./data:/opt/data
    ports:
      - "127.0.0.1:8642:8642"
    environment:
      API_SERVER_ENABLED: "true"
      API_SERVER_HOST: "0.0.0.0"
      API_SERVER_KEY: "${API_SERVER_KEY}"

# Before first run:
# mkdir -p data
# export API_SERVER_KEY="$(openssl rand -hex 32)"
# docker compose up -d

Operating checklist

• Create ./data intentionally and include it in your backup plan.
• Generate API_SERVER_KEY outside the Compose file and do not commit .env with real secrets.
• Use localhost port binding first; add external access only after authentication and firewall review.
• Run docker compose logs --tail=100 hermes after startup and save sanitized errors.
• Back up ./data before docker compose pull and recreate.

Failure modes and fixes

Security notes

• Compose is not a security boundary by itself; Docker settings, mounts, ports, and secrets are the boundary.
• Do not mount your full home directory into the container.
• Treat the Hermes data directory as sensitive because it can hold provider configuration and session state.
• Do not publish logs until API keys, chat tokens, paths, and private prompts are scrubbed.

Direct answer

Docker Compose is useful when you want the official Docker run pattern in a repeatable service file. Use a dedicated data mount, bind ports locally by default, generate API keys outside the file, and back up the data directory before upgrades.

This page is part of Agent Guide's independent Hermes Agent cluster. It is source-backed and labelled when first-hand execution has not been run.

What this page does not cover

• It does not replace the official Hermes Agent documentation.
• It does not claim official affiliation with Nous Research.
• It does not claim first-hand testing unless the page explicitly says so.