#Hermes Agent + WebUI Docker 部署指南（Alpine Linux）

单容器方案：WebUI 内置 Agent，无需另跑 Gateway，一键部署。

#环境要求

Alpine Linux（或其他 Linux，命令类似）
网络畅通（需拉 Docker 镜像和 git clone）

#1. 安装 Docker

apk add docker
rc-service docker start
rc-update add docker     # 开机自启

#2. 准备数据目录与 Agent 源码

WebUI 容器需要读取 Hermes Agent 的 Python 源码来安装依赖。必须提前 clone 到 ~/.hermes/ 下。

mkdir -p ~/.hermes ~/workspace
git clone https://github.com/NousResearch/hermes-agent.git ~/.hermes/hermes-agent

~/.hermes 是 Agent 的数据目录（配置、会话、记忆等）。
~/workspace 是默认工作区目录，可根据需要修改。

#3. 启动 WebUI 容器

docker run -d \
  --name hermes-webui \
  --restart unless-stopped \
  -v ~/.hermes:/home/hermeswebui/.hermes \
  -e HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui \
  -v ~/workspace:/workspace \
  -p 127.0.0.1:8787:8787 \
  ghcr.io/nesquena/hermes-webui:latest

参数说明：

参数	含义
`--restart unless-stopped`	退出后自动重启（除非手动停止），配合 Docker 开机自启实现容器随系统启动
`-v ~/.hermes:/home/hermeswebui/.hermes`	挂载数据目录，WebUI 读写配置、会话、记忆
`-e HERMES_WEBUI_STATE_DIR=...`	WebUI 状态目录（会话、项目等），放在 `~/.hermes/webui` 下统一管理
`-v ~/workspace:/workspace`	挂载工作区目录
`-p 127.0.0.1:8787:8787`	关键：只绑定本地回环地址，外部设备无法通过 IP 访问（安全）

#4. 首次启动与初始化

首次启动较慢，WebUI 会在容器内：

自动检测宿主 UID/GID 并调整容器用户权限
使用 uv 创建 Python 虚拟环境
安装 WebUI 自身依赖
从 /home/hermeswebui/.hermes/hermes-agent 读取 Agent 源码并安装其依赖
启动 HTTP 服务

# 实时查看启动日志
docker logs -f hermes-webui

看到以下输出即启动成功：

Hermes Web UI listening on http://0.0.0.0:8787

用浏览器打开 http://localhost:8787，进入首次配置向导（Onboarding Wizard），选择模型提供商并完成设置即可开始使用。

#5. 日常管理

docker logs -f hermes-webui   # 实时日志
docker restart hermes-webui   # 重启
docker stop hermes-webui      # 停止
docker start hermes-webui     # 启动

#常见问题

#Q: 为什么不用两个容器（Gateway + WebUI）？

单容器方案更简单：WebUI 容器内置了运行 Agent 的能力，不需要额外维护一个 hermes-agent 的 gateway 容器。两个容器共享 ~/.hermes 即可。

#Q: 为什么要把 Agent 源码 clone 到 `~/.hermes/` 下？

WebUI 容器启动时会在 /home/hermeswebui/.hermes/hermes-agent 和 /opt/hermes 两个路径查找 Agent 源码。挂载 ~/.hermes 后，容器内路径正好对应 /home/hermeswebui/.hermes/hermes-agent。缺少 Agent 源码会导致 WebUI 功能受限（无模型自动检测、无人格路由等）。

#Q: 如何让外部设备访问？

默认绑定了 127.0.0.1，外网无法直接访问。安全方式是通过 SSH 隧道：

ssh -N -L 8787:localhost:8787 你的服务器IP

然后在本地浏览器打开 http://localhost:8787。

如果确实需要对外暴露，修改 -p 0.0.0.0:8787:8787 并设置密码：

docker run -d \
  ...
  -e HERMES_WEBUI_PASSWORD=你的密码 \
  -p 8787:8787 \
  ...

#Q: 容器启动报 `Permission denied`？

通常是因为宿主目录权限和容器用户 UID 不匹配。root 用户下跑不需要设置 WANTED_UID/WANTED_GID，容器会自动从挂载卷的属主检测。如果还是报错，确保 ~/.hermes 可读写：

chmod -R u+rwX ~/.hermes

#架构图示

宿主机 ~/.hermes/          容器 hermes-webui
  ├── config.yaml     ──→  挂载到 /home/hermeswebui/.hermes/
  ├── hermes-agent/   ──→  Agent 源码，用于安装依赖
  ├── webui/          ──→  会话、项目等状态
  ├── profiles/       ──→  模型配置
  └── logs/           ──→  日志

WebUI 容器内部运行 uv pip install 安装 Agent 依赖，随后通过 Python 子进程启动 Agent，所有数据读写都在共享的 ~/.hermes 上进行。

#参考

Hermes Agent: https://github.com/NousResearch/hermes-agent
Hermes WebUI: https://github.com/nesquena/hermes-webui
Docker 镜像: ghcr.io/nesquena/hermes-webui:latest