Docker

Docker 与 Hermes Agent 的关系主要有两种：

1. 在 Docker 中运行 Hermes - 也就是 agent 本身运行在容器内（本页主要讨论这个场景）
2. 把 Docker 作为终端后端 - agent 运行在宿主机上，但命令在 Docker 沙箱中执行（见 Configuration → terminal.backend）

本页介绍的是第 1 种方式。容器会把所有用户数据（配置、API 密钥、会话、技能、记忆）统一存放在从宿主机挂载进来的 /opt/data 目录中。镜像本身是无状态的，因此你可以通过拉取新版本来升级，而不会丢失任何配置。

Quick start

如果这是你第一次运行 Hermes Agent，请先在宿主机上创建一个数据目录，然后以交互方式启动容器并运行 setup 向导：

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

这会进入 setup 向导。向导会提示你输入 API 密钥，并把它们写入 ~/.hermes/.env。这一步只需要做一次。此时也强烈建议顺便配置一个供网关使用的聊天平台。

Running in gateway mode

完成配置后，可以将容器作为持久化网关在后台运行（Telegram、Discord、Slack、WhatsApp 等）：

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

8642 端口用于暴露网关的 OpenAI-compatible API server 以及 health endpoint。如果你只使用聊天平台（如 Telegram、Discord），这个端口并不是必须的；但如果你想让 dashboard 或外部工具访问网关，就必须暴露该端口。

在面向互联网的机器上开放任何端口都存在安全风险。除非你明确理解相关风险，否则不要这样做。

Running the dashboard

内置的 Web dashboard 可以作为单独的容器，与网关并行运行。

如果要将 dashboard 作为独立容器运行，请把它指向网关的 health endpoint，这样它就能跨容器检测网关状态：

docker run -d \
  --name hermes-dashboard \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 9119:9119 \
  -e GATEWAY_HEALTH_URL=http://$HOST_IP:8642 \
  nousresearch/hermes-agent dashboard

请将 $HOST_IP 替换为运行网关容器的那台机器的 IP 地址（例如 192.168.1.100）；如果两个容器位于同一个 Docker 网络中，也可以直接使用网络主机名（见下方的 Compose example）。

Environment variable	Description	Default
GATEWAY_HEALTH_URL	网关 API 服务器的基础 URL，例如 http://gateway:8642	(unset — local PID check only)
GATEWAY_HEALTH_TIMEOUT	健康探测超时时间（秒）	3

如果没有设置 GATEWAY_HEALTH_URL，dashboard 会回退到本地进程检测；这种方式只有在网关与 dashboard 运行在同一容器或同一宿主机时才有效。

Running interactively (CLI chat)

如果你想针对已有的数据目录打开一个交互式聊天会话：

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

或者，如果你已经通过 Docker Desktop 等方式进入了一个正在运行的容器，也可以直接执行：

/opt/hermes/.venv/bin/hermes

Persistent volumes

/opt/data 卷是所有 Hermes 状态的唯一真实来源。它映射到宿主机的 ~/.hermes/ 目录，包含以下内容：

Path	Contents
.env	API 密钥和机密
config.yaml	所有 Hermes 配置
SOUL.md	agent 的个性 / 身份
sessions/	对话历史
memories/	持久化记忆存储
skills/	已安装技能
cron/	定时任务定义
hooks/	事件 hook
logs/	运行日志
skins/	自定义 CLI skin

注意

不要让两个 Hermes 网关 容器同时对着同一个数据目录运行。会话文件和记忆存储并不是为并发写入设计的。网关旁边单独运行一个 dashboard 容器是安全的，因为 dashboard 只会读取数据。

Environment variable forwarding

容器中的 API 密钥默认从 /opt/data/.env 读取。你也可以直接通过环境变量传入：

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  -e OPENAI_API_KEY="sk-..." \
  nousresearch/hermes-agent

直接传入的 -e 参数会覆盖 .env 中的值。这对 CI/CD 或 secrets manager 集成非常有用，尤其适合那些不希望把密钥落盘的场景。

Docker Compose example

如果你想持久化部署网关和 dashboard，一份 docker-compose.yaml 会很方便：

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "8642:8642"
    volumes:
      - ~/.hermes:/opt/data
    networks:
      - hermes-net
    # Uncomment to forward specific env vars instead of using .env file:
    # environment:
    #   - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    #   - OPENAI_API_KEY=${OPENAI_API_KEY}
    #   - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"

  dashboard:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-dashboard
    restart: unless-stopped
    command: dashboard --host 0.0.0.0
    ports:
      - "9119:9119"
    volumes:
      - ~/.hermes:/opt/data
    environment:
      - GATEWAY_HEALTH_URL=http://hermes:8642
    networks:
      - hermes-net
    depends_on:
      - hermes
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "0.5"

networks:
  hermes-net:
    driver: bridge

使用 docker compose up -d 启动，并通过 docker compose logs -f 查看日志。

Resource limits

Hermes 容器需要中等规模的资源，建议的最低配置如下：

Resource	Minimum	Recommended
Memory	1 GB	2–4 GB
CPU	1 core	2 cores
Disk (data volume)	500 MB	2+ GB（会随着 sessions / skills 增长）

浏览器自动化（Playwright / Chromium）是最耗内存的功能。如果你不需要浏览器工具，1 GB 通常已经够用；如果要启用浏览器工具，建议至少分配 2 GB。

你也可以直接在 Docker 中设置限制：

docker run -d \
  --name hermes \
  --restart unless-stopped \
  --memory=4g --cpus=2 \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

What the Dockerfile does

官方镜像基于 debian:13.4，其中包含：

• Python 3 及全部 Hermes 依赖（pip install -e ".[all]"）
• Node.js + npm（用于浏览器自动化和 WhatsApp bridge）
• Playwright 和 Chromium（npx playwright install --with-deps chromium）
• ripgrep 与 ffmpeg 等系统工具
• WhatsApp bridge（scripts/whatsapp-bridge/）

入口脚本 docker/entrypoint.sh 会在首次运行时初始化数据卷：

• 创建目录结构（sessions/、memories/、skills/ 等）
• 如果 .env 不存在，则复制 .env.example → .env
• 如果 config.yaml 缺失，则复制默认配置
• 如果 SOUL.md 缺失，则复制默认版本
• 通过基于 manifest 的方式同步内置技能（保留用户修改）
• 然后用你传入的参数执行 hermes

Upgrading

升级时只需要拉取新镜像并重建容器。你的数据目录不会受到影响。

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

或者使用 Docker Compose：

docker compose pull
docker compose up -d

Skills and credential files

当你把 Docker 用作执行环境时，也就是 agent 在 Docker 沙箱中执行命令，而不是像上文那样让整个 Hermes 跑在 Docker 中，Hermes 会自动把技能目录（~/.hermes/skills/）以及技能声明的凭据文件，以只读卷的形式 bind-mount 到容器中。这样一来，技能脚本、模板和引用文件就都能在沙箱内直接使用，无需手工配置。

SSH 和 Modal 后端也会执行类似同步：技能和凭据文件会在每次命令前，通过 rsync 或 Modal mount API 上传。

Troubleshooting

Container exits immediately

先查看日志：docker logs hermes。常见原因包括：

• .env 文件缺失或无效，此时请先以交互方式运行 setup
• 暴露端口时发生端口冲突

"Permission denied" errors

容器默认以 root 身份运行。如果你的宿主机 ~/.hermes/ 是由非 root 用户创建的，通常权限不会有问题。如果确实报错，请确认数据目录可写：

chmod -R 755 ~/.hermes

Browser tools not working

Playwright 需要共享内存。请在 Docker 命令中加入 --shm-size=1g：

docker run -d \
  --name hermes \
  --shm-size=1g \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

Gateway not reconnecting after network issues

--restart unless-stopped 能处理大多数临时故障。如果网关仍然卡住，请重启容器：

docker restart hermes

Checking container health

docker logs --tail 50 hermes          # Recent logs
docker run -it --rm nousresearch/hermes-agent:latest version     # Verify version
docker stats hermes                    # Resource usage