nesquena / hermes-webui
nesquena/hermes-webui
Hermes WebUI：从网页或手机使用Hermes Agent的最佳方式。
项目概览
项目概述
Hermes WebUI 是 Hermes Agent 的自托管 Web 界面，目标是从浏览器或手机获得接近 Hermes CLI 的完整体验。它采用三栏布局：左侧为会话与导航，中间为聊天，右侧为工作区文件浏览；模型、Profile、工作区等控制集中在 composer footer，设置与会话工具集中在 Hermes Control Center。
项目使用 Python 标准库 HTTP 服务器加原生 JavaScript，没有构建步骤、没有前端框架、没有打包器。仓库元数据显示许可证为 MIT。最新 Release 为 v0.52.106（2026-07-29 发布）。
核心功能
聊天与 Agent 能力
- 通过 SSE 流式输出，令牌实时出现。
- 支持多 Provider 模型，动态模型下拉框来自已配置的密钥。
- 消息处理中可继续发送，自动排队。
- 可编辑任意历史用户消息并从该处重新生成，可一键重试最后一条回复。
- 工具调用卡片、子 Agent 委派卡片、Mermaid 图表、思考/推理展示、危险命令审批卡。
- SSE 断线自动重连，适合 SSH 隧道场景。
- 附件的上下文指示、令牌数、成本与填充条展示。
会话管理
- 创建、重命名、复制、删除、搜索会话；支持置顶、归档、项目分组、标签。
- 按今天/昨天/更早分组；可导出 Markdown 或 JSON、从 JSON 导入。
- 可生成公开只读分享链接。
- CLI 会话桥：可从 Hermes Agent 的 SQLite 存储中导入 CLI 会话。
工作区文件浏览器
- 目录树、面包屑、文本/Markdown/图片内联预览。
- 支持
workspace://path/to/file链接。 - 文件新建、编辑、删除、重命名、二进制下载。
- Git 检测：显示分支名与脏文件数。
语音输入
- 使用 Web Speech API 录音、实时中间转写、静音自动停止。
- 浏览器不支持时自动隐藏。
Profile 与设置
- Profile 创建、切换、删除；可从当前 Profile 克隆配置。
- 可指定本地端点 Base URL 与 API key 写入 Profile 的
config.yaml。 - 切 Profile 无需重启服务。
安全
- 可选密码认证，默认关闭；支持 Passkey/WebAuthn 与 OIDC。
- 签名 HMAC HTTP-only Cookie，24 小时 TTL。
- 安全响应头、20MB POST 上限、CDN 资源 SRI hash。
主题与移动端
- 主题轴为 system/dark/light，Skin 轴包含多个皮肤。
- 移动端有汉堡侧栏、滑出文件面板、44px 最小触控目标，桌面布局不变。
适用与不适用场景
适用场景
- 已经或打算使用 Hermes Agent 的用户。
- 自托管、重视数据与对话留在自己服务器上的场景。
- 需要通过浏览器或手机远程使用 Agent，且可接受 SSH 隧道或 Tailscale。
- 需要持久记忆、自托管 cron、跨会话技能、多消息平台接入的 Agent 工作流。
- 熟悉 Python 生态并希望 Web 界面与 CLI 功能对齐的用户。
不适用场景
- 没有安装 Hermes Agent 的环境：WebUI 只是浏览器界面，运行时、记忆、配置、cron 与凭据属于 Hermes Agent。
- 官方 bootstrap 不支持原生 Windows：建议使用 Linux、macOS 或 WSL2；社区有原生 Windows 方案但非官方。
- 双容器 Docker 部署中，从 WebUI 触发的工具运行在 WebUI 容器而非 Agent 容器，git/node 等工具可能缺失。
- 需要 WebUI 与 Hermes Agent 版本严格独立混用的场景：当前二者仍按 Release 配对测试，混用版本不受支持。
技术架构与依赖
- 后端：Python 标准库 HTTP 服务器，无 Web 框架。入口为
server.py，逻辑位于api/（auth、config、models、routes、streaming、workspace、onboarding、profiles 等）。 - 前端：
static/下的原生 HTML/CSS/JS，无框架、无打包器。主要模块包括ui.js、workspace.js、sessions.js、messages.js、panels.js、commands.js、boot.js。 - 状态目录：默认在
~/.hermes/webui/（POSIX），可通过HERMES_WEBUI_STATE_DIR覆盖。 - 运行时依赖：直接导入 Hermes Agent 的 Python 模块，并读取
HERMES_HOME配置；默认在进程内运行 Agent，不连接外部 Agent API 服务。 - 测试：约 11,500 个测试，覆盖约 1,150 个测试文件，CI 在 Python 3.11/3.12/3.13 上运行。
- Docker：提供单容器、双容器、三容器 Compose 文件，镜像基于
python:3.12-slim。 - Nix：提供 flake package 与 NixOS module。
- 仓库资料未提供完整的主依赖锁定清单；除 README 与文档中提到的内容外，更多依赖细节未给出。
安装与快速开始
本地启动
git clone https://github.com/nesquena/hermes-webui.git hermes-webui
cd hermes-webui
python3 bootstrap.py
也可以使用：
./start.sh
bootstrap.py 会检测 Hermes Agent，缺少时尝试运行官方安装脚本；创建或复用 Python 虚拟环境；启动 Web 服务并等待 /health；默认打开浏览器。
后台守护方式
./ctl.sh start
./ctl.sh status
./ctl.sh logs --lines 100
./ctl.sh restart
./ctl.sh stop
Docker 快速开始
git clone https://github.com/nesquena/hermes-webui
cd hermes-webui
cp .env.docker.example .env
# 如宿主 UID 不是 1000（例如 macOS），编辑 .env
docker compose up -d
# 打开 http://localhost:8787
Nix
nix shell github:nesquena/hermes-webui#default
手动启动
cd /path/to/hermes-agent
HERMES_WEBUI_PORT=8787 venv/bin/python /path/to/hermes-webui/server.py
健康检查：
curl http://127.0.0.1:8787/health
典型使用方法
- 完成首次启动后，在浏览器打开
http://127.0.0.1:8787。 - 首次运行会进入 onboarding 向导：选择 Provider、配置模型与工作区、可选设置密码。若向导提示去 CLI 完成，则运行
hermes model后刷新 WebUI。 - 在 composer 中开始对话；可使用
/唤起斜杠命令，例如/help、/clear、/model、/workspace、/usage、/theme。 - 在右侧工作区浏览文件，通过
workspace://链接在聊天中引用文件。 - 使用 Hermes Control Center 管理会话、任务（cron）、技能、记忆、Profile 与设置。
- 远程访问：默认只绑定
127.0.0.1，可用ssh -N -L 8787:127.0.0.1:8787 user@host建隧道；或配合 Tailscale 并将HERMES_WEBUI_HOST=0.0.0.0与HERMES_WEBUI_PASSWORD一起设置。 - Docker 多容器部署时，如需 cron 定时执行，需要同时运行 Hermes Gateway 守护进程，否则任务不会自动 tick。
配置与部署要点
主要环境变量（来自 README）：
| 变量 | 默认值 | 说明 |
|---|---|---|
HERMES_WEBUI_AGENT_DIR | 自动发现 | Hermes Agent 源码或已安装模块根路径 |
HERMES_WEBUI_PYTHON | 自动发现 | Python 可执行文件 |
HERMES_WEBUI_HOST | 127.0.0.1 | 绑定地址 |
HERMES_WEBUI_PORT | 8787 | 服务端口 |
HERMES_WEBUI_STATE_DIR | $HERMES_HOME/webui | 会话与状态存放位置 |
HERMES_WEBUI_DEFAULT_WORKSPACE | ~/workspace | 默认工作区 |
HERMES_WEBUI_PASSWORD | 未设置 | 设置后启用密码认证 |
HERMES_HOME | ~/.hermes | Hermes 状态基础目录 |
HERMES_WEBUI_CSP_CONNECT_EXTRA | 未设置 | 追加可信 connect-src 来源 |
HERMES_WEBUI_SSE_CHUNKED | 未设置 | 反代缓冲场景下使用 chunked SSE |
HERMES_WEBUI_EXTENSION_DIR 等 | 未设置 | 扩展注入相关配置 |
部署要点：
- WebUI 与 Hermes Agent 应视为 Release 配对，升级或固定版本时建议一起进行；版本错配不受支持。
- 远程暴露前必须启用密码认证；默认绑定 loopback。
- Docker 中
localhost指向容器自身，访问宿主机服务应使用host.docker.internal（Docker Desktop）或host.containers.internal（Podman）等地址。 - Docker 需关注 UID/GID 匹配；推荐使用官方 Compose 中的命名卷以避免权限问题。
- 双容器/三容器部署中，Agent 源码通过
hermes-agent-src卷共享；升级 Agent 镜像时需要删除该卷再重新创建。 - 默认聊天在 WebUI 进程内运行，
HERMES_API_URL只被 Tasks/cron 健康探测读取；如需外部端点的模型可作为自定义 OpenAI-compatible Provider 添加，或使用 Gateway 后端。 - 扩展机制会以完整 WebUI 会话权限执行脚本，只应启用可信来源的扩展。
限制、风险与许可证
- 许可证：仓库元数据显示为 MIT。仓库资料未提供除 MIT 之外的许可证或合规信息。
- 原生 Windows 未获官方 bootstrap 支持；社区方案存在已知限制，如 POSIX 风格路径、bash 假设工具可能不工作。
- WebUI 与 Hermes Agent 内部存在直接耦合（直接 import Agent 模块、读取状态布局），在稳定 API 边界工作完成前，升级不一致可能造成导入或行为漂移。
- 双容器 Docker 部署中，WebUI 触发工具运行在 WebUI 容器，不是 Agent 容器，这是架构性限制。
- 默认绑定
127.0.0.1，远程访问需要隧道或显式开放并配合认证。 - 扩展脚本具有完整会话权限，共享或多用户部署时应谨慎启用。
- 仓库资料未提供完整的已知漏洞清单、安全审计报告或供应链 SBOM 信息。
官方链接
- 仓库主页：https://github.com/nesquena/hermes-webui
- 最新 Release：https://github.com/nesquena/hermes-webui/releases/tag/v0.52.106
- Hermes Agent 官网：https://hermes-agent.nousresearch.com/
- 仓库内文档索引：README 中的 Docs 一节列有
docs/why-hermes.md、docs/troubleshooting.md、docs/docker.md、docs/remote-access.md、docs/onboarding.md、ARCHITECTURE.md、CHANGELOG.md等。
信息来源和分析时间
本指南仅基于所提供仓库内容生成，包括仓库元数据（owner、name、description、language、license、topics、latestRelease）以及 README 和仓库内文档。分析所用数据快照中的最新 Release 为 v0.52.106，发布于 2026-07-29。分析时间：基于该数据快照，未进行实时网络验证；如仓库后续变更，请以官方仓库为准。