hermes agent —— Docker

Docker 与 Hermes 代理有两种截然不同的交集方式：

1. 在 Docker 中运行 Hermes —— 代理本身在容器内运行（本页面的主要焦点）。
2. 以 Docker 作为终端后端 —— 代理在您的宿主机上运行，但在一个单一的、持久的 Docker 沙箱容器中执行每一条命令。该沙箱在工具调用、/new 以及子代理的整个 Hermes 进程生命周期中始终存在（参见 配置 → Docker 后端）。

本页面涵盖选项 1。容器将所有用户数据（配置、API 密钥、会话、技能、记忆）存储在从宿主机挂载到 /opt/data 的单一目录中。镜像本身是无状态的，可以通过拉取新版本进行升级，而不会丢失任何配置。

快速入门

如果您是第一次运行 Hermes 代理，请在宿主机上创建一个数据目录，并以交互方式启动容器来运行设置向导：

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

这将带您进入设置向导，它会提示您输入 API 密钥并将其写入 ~/.hermes/.env。您只需执行一次此操作。强烈建议在此阶段为网关配置一个可配合使用的聊天系统（如 Telegram、Discord 等）。

以网关模式运行

配置完成后，可以在后台运行容器作为持久化的网关（支持 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 兼容 API 服务器 和健康检查端点。如果您仅使用聊天平台（Telegram、Discord 等），该端口是可选的；但如果您希望控制面板或外部工具能够访问网关，则必须开放此端口。

注意：API 服务器受 API_SERVER_ENABLED=true 控制。若要在容器内将其暴露到 127.0.0.1 之外，还需要设置 API_SERVER_HOST=0.0.0.0 以及 API_SERVER_KEY（至少 8 个字符 —— 可以使用 openssl rand -hex 32 生成一个）。示例：

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -e API_SERVER_ENABLED=true \
  -e API_SERVER_HOST=0.0.0.0 \
  -e API_SERVER_KEY=your_api_key_here \
  -e API_SERVER_CORS_ORIGINS='*' \
  nousresearch/hermes-agent gateway run

在连接互联网的机器上开放任何端口都存在安全风险。除非您了解相关风险，否则不应执行此操作。

运行控制面板 (Running the dashboard)

内置的 Web 控制面板（Dashboard）作为可选的侧边进程，在与网关相同的容器内运行。设置 HERMES_DASHBOARD=1 并同时暴露端口 9119 和网关的 8642：

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

入口脚本（Entrypoint）在执行主命令之前，会在后台启动 hermes dashboard（以非 root 用户 hermes 身份运行）。在 docker logs 中，控制面板的输出带有 [dashboard] 前缀，方便与网关日志区分。

环境变量	描述	默认值
HERMES_DASHBOARD	设置为 1（或 true / yes）以随主命令启动控制面板	(未设置 — 不启动控制面板)
HERMES_DASHBOARD_HOST	控制面板 HTTP 服务器的绑定地址	0.0.0.0
HERMES_DASHBOARD_PORT	控制面板 HTTP 服务器的端口	9119
HERMES_DASHBOARD_TUI	设置为 1 以在浏览器中显示 Chat 选项卡（通过 PTY/WebSocket 嵌入 hermes --tui）	(未设置)

为了让宿主机能够通过发布的端口访问控制面板，必需使用默认值 HERMES_DASHBOARD_HOST=0.0.0.0；在这种情况下，入口脚本会自动向 hermes dashboard 传递 --insecure 参数。如果您希望将控制面板限制为仅限容器内访问（例如位于边车容器的反向代理之后），请将其覆盖为 127.0.0.1。

信息

控制面板侧边进程 不具备监控（Supervised）机制 —— 如果它崩溃，直到容器重启前它都将保持关闭状态。目前不支持将其作为独立容器运行：控制面板的网关活跃度检测功能需要与网关进程共享 PID 命名空间。

以交互方式运行 (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/ 目录，并包含以下内容：

路径	内容
.env	API 密钥和机密信息
config.yaml	所有 Hermes 配置
SOUL.md	代理的性格/身份
sessions/	对话历史
memories/	持久化记忆库
skills/	已安装的技能
cron/	计划任务定义
hooks/	事件钩子
logs/	运行时日志
skins/	自定义 CLI 皮肤

重要

切勿针对同一个数据目录同时运行两个 Hermes 网关 (gateway) 容器 —— 会话文件和记忆库并非为并发写入访问而设计。

多配置文件支持 (Multi-profile support)

Hermes 支持 多配置文件 (multiple profiles) —— 即独立的 ~/.hermes/ 目录，允许您在单次安装下运行彼此独立的代理（拥有不同的 SOUL、技能、记忆、会话和凭据）。在 Docker 下运行时，不建议使用 Hermes 内置的多配置文件功能。

相反，推荐的模式是 一个配置文件对应一个容器，每个容器将各自的主机目录绑定挂载为 /opt/data：

# 工作配置文件 (Work profile)
docker run -d \
  --name hermes-work \
  --restart unless-stopped \
  -v ~/.hermes-work:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

# 个人配置文件 (Personal profile)
docker run -d \
  --name hermes-personal \
  --restart unless-stopped \
  -v ~/.hermes-personal:/opt/data \
  -p 8643:8642 \
  nousresearch/hermes-agent gateway run

为什么在 Docker 中选择独立容器而非多配置文件：

• 隔离性 —— 每个容器都有独立的文件系统、进程表和资源限制。一个配置文件的崩溃、依赖变更或异常会话不会影响另一个。
• 独立的生命周期 —— 可以分别对每个代理进行升级、重启、暂停或回滚（执行 docker restart hermes-work 不会触碰 hermes-personal）。
• 清晰的端口和网络分离 —— 每个网关绑定各自的主机端口，不存在聊天平台或 API 服务器之间串扰的风险。
• 更简单的心理模型 —— 容器即配置文件。备份、迁移和权限管理都遵循绑定挂载的目录，无需额外记忆 --profile 标志。
• 规避并发写入风险 —— 前文关于 “切勿针对同一个数据目录运行两个网关” 的警告，同样适用于单个容器内的多个配置文件。

在 Docker Compose 中，这只需为每个配置文件声明一个服务，并区分 container_name、volumes 和 ports：

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

  hermes-personal:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-personal
    restart: unless-stopped
    command: gateway run
    ports:
      - "8643:8642"
    volumes:
      - ~/.hermes-personal:/opt/data

环境变量转发 (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 示例

对于同时包含网关和控制面板的持久化部署，使用 docker-compose.yaml 会更加方便：

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "8642:8642"   # 网关 API
      - "9119:9119"   # 控制面板 (仅在 HERMES_DASHBOARD=1 时可访问)
    volumes:
      - ~/.hermes:/opt/data
    environment:
      - HERMES_DASHBOARD=1
      # 取消以下注释以转发特定的环境变量，而非使用 .env 文件：
      # - 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"

使用 docker compose up -d 启动，并使用 docker compose logs -f 查看日志。控制面板的输出带有 [dashboard] 前缀，因此可以轻松地从网关日志中过滤出来。

资源限制 (Resource limits)

Hermes 容器需要适度的资源。推荐的最低配置如下：

资源	最低要求	推荐配置
内存	1 GB	2–4 GB
CPU	1 核	2 核
磁盘 (数据卷)	500 MB	2 GB 以上（随会话/技能增长）

浏览器自动化（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

Dockerfile 的作用

官方镜像基于 debian:13.4 构建，包含以下内容：

• Python 3 以及所有 Hermes 依赖项 (uv pip install -e ".[all]")
• Node.js + npm（用于浏览器自动化和 WhatsApp 桥接）
• Playwright 与 Chromium (npx playwright install --with-deps chromium --only-shell)
• ripgrep, ffmpeg, git, 和 tini 作为系统工具
• docker-cli —— 以便容器内运行的代理可以驱动宿主机的 Docker 守护进程（需绑定挂载 /var/run/docker.sock 以开启此功能），用于 docker build、docker run、容器检查等。
• openssh-client —— 允许在容器内使用 SSH 终端后端。SSH 后端会调用系统的 ssh 二进制文件；如果没有此组件，容器化安装中的该功能会静默失败。
• WhatsApp 桥接器 (scripts/whatsapp-bridge/)

入口脚本 (docker/entrypoint.sh) 在首次运行时引导数据卷：

• 创建目录结构（sessions/, memories/, skills/ 等）
• 如果不存在 .env，则复制 .env.example → .env
• 如果缺失，则复制默认的 config.yaml
• 如果缺失，则复制默认的 SOUL.md
• 使用基于清单（manifest）的方法同步内置技能（保留用户编辑）
• 当 HERMES_DASHBOARD=1 时，可选地启动 hermes dashboard 作为后台侧边进程（参见 运行控制面板 部分）
• 然后使用您传递的任何参数运行 hermes

重要

除非您在命令链中保留了 /opt/hermes/docker/entrypoint.sh，否则请勿覆盖镜像的入口点（Entrypoint）。入口脚本会在创建网关状态文件之前，将 root 权限降级为 hermes 用户。在官方镜像中，默认拒绝以 root 身份启动 hermes gateway run，因为这可能会在 /opt/data 中留下 root 拥有的文件，从而破坏后续控制面板或网关的启动。只有在您有意接受该风险时，才设置 HERMES_ALLOW_ROOT_GATEWAY=1。

升级 (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 作为执行环境时（并非指上述运行代理的方法，而是指代理在 Docker 沙箱中执行命令时 —— 参见 配置 → Docker 后端），Hermes 会在所有工具调用中复用同一个长效容器，并自动将技能目录（~/.hermes/skills/）以及技能声明的任何凭据文件作为只读卷绑定挂载到该容器中。技能脚本、模板和引用文件在沙箱内无需手动配置即可使用。由于容器在 Hermes 进程的整个生命周期内持续存在，您安装的任何依赖项或写入的文件都会保留到下一次工具调用。

SSH 和 Modal 后端也会进行同样的同步 —— 在执行每条命令之前，技能和凭据文件会通过 rsync 或 Modal 的挂载 API 进行上传。

连接本地推理服务器 (vLLM, Ollama 等)

在 Docker 中运行 Hermes 时，如果您的推理服务器（vLLM、Ollama、text-generation-inference 等）也运行在宿主机或其他容器中，网络配置需要格外注意。

Docker Compose (推荐方式)

将两个服务置于同一个 Docker 网络中。这是最可靠的方法：

services:
  vllm:
    image: vllm/vllm-openai:latest
    container_name: vllm
    command: >
      --model Qwen/Qwen2.5-7B-Instruct
      --served-model-name my-model
      --host 0.0.0.0
      --port 8000
    ports:
      - "8000:8000"
    networks:
      - hermes-net
    deploy:
      resources:
        reservations:
          devices:
            - capabilities: [gpu]

  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

networks:
  hermes-net:
    driver: bridge

然后，在您的 ~/.hermes/config.yaml 中，使用 容器名称 作为主机名：

model:
  provider: custom
  model: my-model
  base_url: http://vllm:8000/v1
  api_key: "none"

关键点

• 使用容器名称 (vllm) 作为主机名 —— 不要使用 localhost 或 127.0.0.1，因为它们在容器环境中指向的是 Hermes 容器自身。
• model 的值必须与传递给 vLLM 的 --served-model-name 一致。
• 将 api_key 设置为任何非空字符串（vLLM 要求有该请求头，但默认不验证其内容）。
• base_url 结尾 不要 包含斜杠。

独立 Docker 运行 (非 Compose)

如果您的推理服务器直接运行在宿主机上（非 Docker 环境），请在 macOS/Windows 上使用 host.docker.internal，或在 Linux 上使用 --network host：

macOS / Windows:

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

config.yaml

model:
  provider: custom
  model: my-model
  base_url: http://host.docker.internal:8000/v1
  api_key: "none"

Linux (主机网络模式):

docker run -d \
  --name hermes \
  --network host \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

config.yaml

model:
  provider: custom
  model: my-model
  base_url: http://127.0.0.1:8000/v1
  api_key: "none"

使用 --network host 时，-p 标志将被忽略 —— 容器的所有端口都会直接暴露在宿主机上。

验证连接

在 Hermes 容器内部，确认推理服务器是否可达：

docker exec hermes curl -s http://vllm:8000/v1/models

您应该看到列出所提供模型的 JSON 响应。如果失败，请检查：

1. 两个容器是否在同一个 Docker 网络中 (docker network inspect hermes-net)。
2. 推理服务器是否监听在 0.0.0.0 而非 127.0.0.1。
3. 端口号是否匹配。

Ollama

Ollama 的配置方式相同。如果 Ollama 运行在宿主机上，请使用 host.docker.internal:11434 (macOS/Windows) 或 127.0.0.1:11434 (Linux 配合 --network host)。如果 Ollama 运行在同一个 Docker 网络的独立容器中：

model:
  provider: custom
  model: llama3
  base_url: http://ollama:11434/v1
  api_key: "none"

故障排除 (Troubleshooting)

容器立即退出 (Container exits immediately)

检查日志：docker logs hermes。常见原因：

• 缺失或无效的 .env 文件 —— 请先以交互模式运行以完成设置。
• 如果运行并暴露了端口，可能存在端口冲突。

“权限拒绝” 错误 (“Permission denied” errors)

容器的入口脚本通过 gosu 将权限降级为非 root 的 hermes 用户（UID 10000）。如果宿主机的 ~/.hermes/ 属于不同的 UID，请设置 HERMES_UID/HERMES_GID 以匹配您的宿主机用户，或者确保数据目录是可写的：

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          # 最近的日志
docker run -it --rm nousresearch/hermes-agent:latest version     # 验证版本
docker stats hermes                    # 资源占用情况