hermes-agent-desktop

基于 LinuxServer.io Webtop (Debian KDE) + NousResearch/hermes-agent + Hermes WebUI 打包的一体化 Docker 镜像。

镜像地址

ghcr.io/comedy1024/hermes-agent-desktop:latest

功能特性

• 🖥️ Linux GUI 桌面 — 通过 noVNC 在浏览器中访问完整 Debian KDE 桌面环境
• 🤖 Hermes Agent — 自演化 AI Agent 框架，支持 OpenAI / Anthropic / DeepSeek / Ollama 等
• 🌐 Hermes WebUI — 社区最活跃的 Hermes Agent Web 管理界面（1.6k+ Stars）
• 🔧 全功能管理 — 流式聊天、文件浏览器、技能管理、记忆编辑、语音输入、7 种主题
• 🔗 CLI 会话桥接 — 终端和 WebUI 共享会话，无缝切换
• 🔒 官方镜像基础 — 基于 LinuxServer.io 官方维护镜像，安全可靠，多架构支持

端口说明

快速开始（本地运行）

docker run -d \
  --name hermes-agent \
  -p 3000:3000 \
  -p 3001:3001 \
  -p 8787:8787 \
  -p 8642:8642 \
  -v hermes-data:/config \
  ghcr.io/comedy1024/hermes-agent-desktop:latest

启动后：

1. 打开 http://localhost:8787 — Hermes WebUI 管理界面（首次配置 LLM API Key）
2. 打开 http://localhost:3000 — Linux KDE 桌面（noVNC）
3. http://localhost:8642 — Hermes Gateway OpenAI 兼容 API

常用环境变量

完整配置项请参考容器内的 /config/hermes-data/.env 模板文件。

数据持久化

所有配置、记忆、技能、会话日志均保存在 /config 目录下：

-v hermes-data:/config

目录结构：

/config/
├── hermes-data/
│   ├── .env           # 环境配置（API Keys、模型配置）
│   ├── config.yaml    # Hermes Agent 主配置
│   ├── SOUL.md        # Agent 人格定义
│   ├── memories/      # 长期记忆
│   ├── skills/        # 技能库（78 个预装）
│   ├── sessions/      # 会话记录
│   ├── logs/          # 运行日志
│   ├── workspace/     # 工作目录
│   └── .hermes/
│       └── webui-mvp/ # WebUI 状态与配置
└── logs/
    └── hermes-webui.log  # WebUI 服务日志

常见问题

如何设置桌面访问密码？

在 docker run 时传入 PASSWORD 环境变量：

docker run -d -e PASSWORD=your_password ...

配置 LLM 后报错 Hermes runtime returned an unexpected response

这是由于 Gateway 的用户白名单未配置导致的。编辑容器内的 .env 文件：

docker exec -it hermes-agent bash
nano /config/hermes-data/.env

添加：

# 允许所有用户访问（本地/私有部署）
GATEWAY_ALLOW_ALL_USERS=true

# 建议同时设置 API Key 以启用 session 保持
API_SERVER_KEY=your_random_secret_key

保存后在 WebUI 中重启 Gateway 即可。

HuggingFace Spaces 数据持久化

在 HF Spaces 设置中开启 Persistent Storage，然后在 Dockerfile 中重定向数据目录：

FROM ghcr.io/comedy1024/hermes-agent-desktop:latest

ENV HERMES_HOME=/data/hermes-data
ENV HERMES_WEBUI_STATE_DIR=/data/hermes-data/.hermes/webui-mvp
ENV HERMES_WEBUI_DEFAULT_WORKSPACE=/data/hermes-data

EXPOSE 7860

部署到 ModelScope Spaces

注意：本镜像基于 linuxserver/webtop，使用 s6-overlay 管理进程（必须以 PID 1 运行）。
从 v2026-04-16 起已内置 PID 1 兼容层（s6-init.sh），可自动适配云平台环境。

1. 在 ModelScope 创建一个新的创空间（SDK 选择 Docker）
2. 在创空间仓库中添加 Dockerfile 文件：

FROM ghcr.io/comedy1024/hermes-agent-desktop:latest

# ModelScope 创空间要求应用监听 7860 端口
# 我们将 noVNC 桌面映射到 7860（也可改为 8787 映射 WebUI）
EXPOSE 7860

1. 在创空间「设置」中添加所需环境变量（如 OPENAI_API_KEY）
2. 点击重启即可自动拉取镜像并部署

端口映射

创空间默认只暴露 7860 端口。你可以根据需要选择映射哪个服务：

如需同时访问桌面和 WebUI，建议使用 Docker 自行部署（见上方快速开始）。

常见问题

Q: 创空间启动报错 s6-overlay-suexec: fatal: can only run as pid 1

这是旧版本问题，从 v2026-04-16 起已修复。请拉取最新镜像。如果仍遇到此问题，
说明创空间的容器运行时使用了特殊的 PID 命名空间隔离。请确保使用最新版镜像，
其中包含 s6-init.sh PID 1 兼容层。

部署到 HuggingFace Spaces

在 Spaces 仓库中添加 Dockerfile 文件：

FROM ghcr.io/comedy1024/hermes-agent-desktop:latest

ENV HERMES_HOME=/data/hermes-data
ENV HERMES_WEBUI_STATE_DIR=/data/hermes-data/.hermes/webui-mvp
ENV HERMES_WEBUI_DEFAULT_WORKSPACE=/data/hermes-data

EXPOSE 7860
EXPOSE 8787
EXPOSE 8642

镜像构建

镜像通过 GitHub Actions 自动构建：

• push 到 main 分支时触发构建
• 每天 UTC 02:00（北京时间 10:00）定时检查上游更新（hermes-agent / hermes-webui / 基础镜像）
• 仅上游有变化时才构建，避免无意义重建
• 支持 linux/amd64 和 linux/arm64 双架构

构建流程

1. 基于 lscr.io/linuxserver/webtop:debian-kde（Debian 13 Trixie + KDE）
2. 使用 uv 安装 hermes-agent[all] 到 /opt/hermes-venv（CLI + WebUI 共享）
3. NodeSource 安装 Node.js 22 + npm（Playwright + WhatsApp bridge）
4. 设置桌面快捷方式、壁纸、开机自启
5. 推送多架构镜像到 ghcr.io

相关项目

• NousResearch/hermes-agent — Hermes Agent 上游
• nesquena/hermes-webui — Hermes WebUI 上游
• linuxserver/docker-webtop — Linux GUI 桌面基础镜像

License

本仓库遵循 MIT 协议，与上游 hermes-webui 保持一致。