Guides Platform

Appearance

Docker 部署 Hermes Agent：固定源码版本、消息网关与本地 Dashboard ​

Hermes Agent 是 Nous Research 开源的 AI Agent，提供 CLI/TUI、消息网关、工具、Skills、记忆和定时任务等能力。本文按官方发布 tag v2026.8.27（项目版本 0.20.6）整理 Linux Docker 部署，正式路径是仓库自带的 Docker Compose 源码构建。

这条路径适合单机自托管、开发测试和个人工作站。官方 Linux Compose 没有固定的远程镜像，而是从源码构建 hermes-agent；首次构建会安装 Python、Node、Playwright、SQLite 修复库和多组依赖，耗时与磁盘需求没有在官方文件中给出。本文只完成了官方资料和配置静态核对，当前环境未能连接 Docker daemon，因此不会把运行结果写成实测成功。

部署结论 ​

项目本文采用的值
GitHub 地址NousResearch/hermes-agent
项目版本v2026.8.27，项目版本 0.20.6
Linux 官方镜像官方 Compose 使用 build: . 构建本地 hermes-agent；没有核验到可替代源码构建的固定 Linux 镜像 tag
官方镜像未发布固定 Linux 镜像；官方 Linux 路径使用源码构建
正式部署官方 docker-compose.yml，gateway + dashboard
快速体验不提供 docker run：正式路径依赖源码构建、两个服务、共享配置和首次 setup
适用范围单机自托管、开发测试、个人工作站；不是高可用集群方案
主机架构Dockerfile 明确处理 amd64、arm64 的 s6-overlay 构建分支；本文未实际构建验证
最低资源官方未给出 CPU、内存和磁盘下限；构建包含 Playwright、编译工具和多组依赖，应预留充足磁盘与网络
对外端口Linux 使用 host network；dashboard 默认 127.0.0.1:9119，消息平台端口由启用的 gateway 决定
持久化位置宿主机 ~/.hermes -> 容器 /opt/data
依赖服务无独立数据库或 Redis；模型、消息平台和工具服务按配置访问外部 API
验证范围官方仓库/tag/Compose/Dockerfile 核对；Compose 结构静态核对；未构建镜像、未启动容器
资料核对日期2026-08-28

Linux 与 Windows 的官方 Compose 不是同一条运行路径：Linux 文件从源码构建并使用 host network；Windows 文件引用 nousresearch/hermes-agent:latest 并显式映射 dashboard 端口。本文只讲固定 tag 的 Linux 源码构建，避免把漂移的 latest 当成可复现版本。

运行结构 ​

gateway 负责 Hermes 的消息网关和后台 Agent 进程；dashboard 提供本机 Web 控制面。两个服务共享 /opt/data，其中包含配置、认证信息、记忆和其他 Hermes 用户数据。host network 意味着容器直接使用宿主机网络命名空间，端口隔离弱于普通 bridge 网络，必须保持 dashboard 的本地监听。

Mermaid 流程图
查看源码
flowchart LR
  User[浏览器或消息平台] --> Dashboard[dashboard\n127.0.0.1:9119]
  Telegram[Telegram / Discord / Slack 等] --> Gateway[gateway\nhermes gateway]
  Dashboard --> Data[(~/.hermes\n/opt/data)]
  Gateway --> Data
  Gateway --> Models[模型与工具 API]

准备条件 ​

  • Linux 主机或 Linux 虚拟机，已安装 Docker Engine 和 Compose v2；Docker Desktop 也可以提供 Linux 容器运行时。
  • 能访问 GitHub、Docker 基础镜像仓库、PyPI/Node 依赖源和 Dockerfile 中的 SQLite/s6 下载地址。
  • 主机磁盘和构建缓存足够；官方没有给出最低值，不应按“小型镜像”预估。
  • 不要让 9119 被其他程序占用；Linux host network 下，端口冲突直接发生在宿主机。
bash
docker --version
docker compose version
docker info --format '{{.Architecture}}'

检查 dashboard 端口：

bash
lsof -nP -iTCP:9119 -sTCP:LISTEN

没有 lsof 时使用 ss -lntp | grep ':9119'。不要为了释放端口直接终止不明进程。

获取固定版本源码 ​

使用 tag 而不是 main，这样 Dockerfile、Compose、Python 依赖和 CLI 行为来自同一个版本：

bash
mkdir -p "$HOME/apps/hermes-agent"
cd "$HOME/apps/hermes-agent"
git clone --branch v2026.8.27 --depth 1 https://github.com/nousresearch/hermes-agent.git src
cd src
git describe --tags --always

预期输出应包含 v2026.8.27。如果所在网络无法访问 GitHub，先解决 Git/代理问题；不要把未核验的镜像地址替换进 Compose。

官方 Compose 配置 ​

v2026.8.27 的 Linux 官方文件包含两个服务。建议保留仓库原文件，不要删除 /init 入口、UID/GID 环境变量或 host network：

yaml
services:
  gateway:
    build: .
    image: hermes-agent
    container_name: hermes
    restart: unless-stopped
    network_mode: host
    volumes:
      - ~/.hermes:/opt/data
    environment:
      - HERMES_UID=${HERMES_UID:-10000}
      - HERMES_GID=${HERMES_GID:-10000}
    command: ["gateway", "run"]

  dashboard:
    image: hermes-agent
    container_name: hermes-dashboard
    restart: unless-stopped
    network_mode: host
    depends_on:
      - gateway
    volumes:
      - ~/.hermes:/opt/data
    environment:
      - HERMES_UID=${HERMES_UID:-10000}
      - HERMES_GID=${HERMES_GID:-10000}
    command: ["dashboard", "--host", "127.0.0.1", "--no-open"]

这个配置没有把 API key 写入 Compose。Hermes 的 provider、模型、消息平台凭据和工具设置写入共享的 ~/.hermes，首次 setup 时在交互终端输入。不要把 .env、auth.json 或导出的配置提交到 Git。

构建镜像并初始化 ​

先让 Compose 使用当前宿主机用户的 UID/GID。官方 Dockerfile 会在启动阶段调整容器用户并处理 /opt/data 权限：

bash
export HERMES_UID="$(id -u)"
export HERMES_GID="$(id -g)"
mkdir -p "$HOME/.hermes"

docker compose config
docker compose build --pull

docker compose config 应输出两个服务且没有 YAML 错误；docker compose build --pull 会执行官方 Dockerfile 的多阶段构建。构建失败时先查看网络、磁盘和 BuildKit 日志，不要改成未固定版本的第三方镜像。

首次 setup 写入共享配置目录：

bash
docker compose run --rm gateway setup

按向导选择模型 provider、默认模型和需要的工具。API key 只在交互输入或通过受控环境变量提供，不要把真实值写进文章或 Compose 文件。需要启用消息平台时，再运行官方 CLI 的网关向导：

bash
docker compose run --rm gateway gateway setup

向导完成后，检查 ~/.hermes 的属主和权限；其中可能包含模型和消息平台凭据。

启动服务 ​

bash
docker compose up -d
docker compose ps

预期是 hermes 和 hermes-dashboard 处于运行状态。dashboard 默认只监听本机，打开 http://127.0.0.1:9119/；不要直接把命令改为 --host 0.0.0.0 --insecure。需要远程管理时，使用 SSH 隧道：

bash
ssh -N -L 9119:127.0.0.1:9119 user@example-host

然后在本地浏览器访问 http://127.0.0.1:9119/。公网部署还需要反向代理认证、TLS、来源限制和独立备份策略，本文不把 host network 视为公网安全边界。

安全边界 ​

  • Linux Compose 使用 host network，容器端口直接进入宿主机网络命名空间。保持 Dashboard 监听 127.0.0.1，远程管理使用 SSH 隧道。
  • ~/.hermes 包含模型与消息平台凭据、配置和记忆。目录权限只授予运行 Hermes 的宿主机用户，备份也按敏感数据管理。
  • 不要启用 --insecure --host 0.0.0.0。确需公网入口时，在应用前增加认证、TLS、来源限制和访问日志，并单独评估消息平台回调端口。
  • Compose 中不保存 API key；首次 setup 在受控终端完成，日志和截图不得包含 token、chat ID 或 webhook 地址。

验证部署结果 ​

容器状态 ​

bash
docker compose ps

确认 hermes 和 hermes-dashboard 没有反复重启。若状态为 Exited，进入日志检查，不要先删除 ~/.hermes。

Dashboard 响应 ​

bash
curl -fsS -o /dev/null -w 'dashboard_http=%{http_code}\n' http://127.0.0.1:9119/

能得到 HTTP 状态码且浏览器可以打开页面，才算 dashboard 入口通过；具体状态码以当前版本实际输出为准。

日志与配置 ​

bash
docker compose logs --tail=100 gateway
docker compose logs --tail=100 dashboard
docker compose exec gateway hermes config get model.default

日志中不应出现持续重启、认证失败或依赖安装失败。hermes config get 应返回已配置的模型值；如果为空，重新执行 docker compose run --rm gateway setup。

消息网关 ​

消息平台不是仅凭容器运行就能证明可用。完成对应平台的 gateway setup 后，从已允许的账号发送一条测试消息，确认 gateway 收到事件、调用模型并返回响应。不要把真实 token、chat ID 或 webhook 地址写入日志、截图或文章。

持久化 ​

停止并重新创建容器后检查配置仍在：

bash
docker compose up -d --force-recreate
docker compose exec gateway hermes config get model.default

配置仍能读取，说明 ~/.hermes -> /opt/data 绑定关系生效。模型 provider 的真实调用和消息历史仍需按具体平台单独验收。

日常运维 ​

bash
docker compose ps
docker compose logs --tail=100 gateway
docker compose logs --tail=100 dashboard
docker compose restart gateway dashboard

docker compose down 只停止并移除容器，不会删除宿主机 ~/.hermes。不要给该命令增加卷删除参数来期待清理配置；该项目的关键数据是 bind mount，不是 Compose 命名卷。

备份与恢复 ​

Hermes 的配置、认证信息、记忆和消息平台设置位于宿主机 ~/.hermes。停止服务后备份该目录和固定版本的 Compose 文件；恢复时先停容器，再解压回同一路径并检查权限：

bash
docker compose stop
tar -czf "$HOME/hermes-backup-$(date +%F).tar.gz" -C "$HOME" .hermes
tar -tzf "$HOME/hermes-backup-$(date +%F).tar.gz" | head
docker compose up -d

恢复前先保留当前 ~/.hermes 的副本，并确认归档内容只包含预期的 .hermes/ 路径。然后停服务、解压同一份备份并重新检查权限：

bash
cd "$HOME/apps/hermes-agent/src"
docker compose stop
tar -tzf "$HOME/hermes-backup-2026-08-28.tar.gz" | head
tar -xzf "$HOME/hermes-backup-2026-08-28.tar.gz" -C "$HOME"
chmod 700 "$HOME/.hermes"
docker compose up -d
docker compose exec gateway hermes config get model.default

把示例日期替换成实际归档日期。若目录属主与 HERMES_UID/HERMES_GID 不一致，先修正权限再启动；不要在未核对归档内容时直接覆盖当前配置。

升级前保留当前 Git commit、镜像构建缓存和备份归档。回滚时切回已验证的 commit，重新构建并启动，再执行配置读取和消息网关验收；Compose 的卷删除参数也不会替你清理 bind mount，手工删除 ~/.hermes 会直接丢失配置和记忆。

总结 ​

Hermes Agent 的 Linux Docker 路径适合单机自托管：固定 Git tag、使用官方 Compose 从源码构建，先运行 setup，再启动 gateway 和本地 dashboard。由于 host network、外部模型和消息平台凭据都在部署边界内，公开访问前必须增加 TLS、认证、来源限制和备份策略。

参考资料 ​

全部公开文章由同一个站点构建和发布。

Guides Platform