hermes-web-ui Documentation

File: README.md Copy Chapter

Core Capabilities Copy Chapter

Features Copy Chapter

AI Chat Copy Section

• Real-time chat streaming over Socket.IO /chat-run; chat runs execute through the Hermes agent bridge
• Multi-session management — create, rename, delete, switch between sessions
• Self-built session database — local SQLite storage for Web UI sessions; Hermes state.db remains a read-only source for Hermes history APIs
• Session grouping by source (Telegram, Discord, Slack, etc.) with collapsible accordion
• Active session indicator — live sessions pin to top with spinner icon
• Sessions sorted by latest message time
• Markdown rendering with syntax highlighting and code copy
• Tool call detail expansion (arguments / result)
• Profile-scoped file uploads, clipboard image/file paste, and workspace attachments
• File download support — download uploaded files and agent-generated files by resolved path across local, Docker, SSH, and Singularity backends
• Inline previews for generated HTML, PDF, DOCX, PPTX, XLSX, CSV, images, Markdown, and source files
• Session search — Ctrl+K search across the Web UI local session database; read-only Hermes history sessions are not included
• Session categories, message references, compression progress, and durable background delegation results
• Profile-aware model selector — discovers models available to the signed-in account through authorized Hermes profiles
• Per-session model display badge and context token usage

Platform Channels Copy Section

Unified configuration for 10 platforms in one page:

• Credential management writes to ~/.hermes/.env
• Channel behavior settings write to ~/.hermes/config.yaml
• Per-platform configured/unconfigured status detection

Usage Analytics Copy Section

• Total token usage breakdown (input / output)
• Session count with daily average
• Estimated cost tracking & cache hit rate
• Model usage distribution chart
• 30-day daily trend (bar chart + data table)

Scheduled Jobs Copy Section

• Create, edit, pause, resume, delete cron jobs
• Trigger immediate execution
• Cron expression quick presets

Kanban Copy Section

• Profile-aware Kanban board for planning and tracking agent work
• Task creation, updates, and status movement from the dashboard
• Shared with the same local Web UI state and authentication model

Visual Workflows Copy Section

• Vue Flow canvas for Hermes, Codex, and Claude Code nodes with file/image attachments
• Directed edges, structured conditions, success/failure routes, loops, and approval gates
• Import/export for portable workflow definitions and profile-aware workspaces
• Run budgets, deadlines, stop/rerun controls, and persisted execution history
• Frozen run snapshots, node conversations, edge decisions, and evidence playback on the canvas

Model Management Copy Section

• Auto-discover models from credential pool (~/.hermes/auth.json)
• Fetch available models from each provider endpoint (/v1/models)
• Add, update, and delete providers (preset and custom OpenAI-compatible)
• OAuth/device flows for OpenAI Codex, Nous Portal, xAI, Claude, and GitHub Copilot
• Provider URL auto-detection for non-v1 API versions (e.g. /v4)
• Provider-level model grouping, visible-model controls, aliases, refresh, and default switching
• Separate STT and TTS provider catalogs under Models

Multi-Profile Copy Section

• Create, rename, delete, and switch between Hermes profiles
• Clone existing profile or import from archive (.tar.gz)
• Export profile for backup or sharing
• Profile-scoped configuration, cache, uploads, sessions, jobs, usage, memory, skills, plugins, providers, and model visibility
• Account-bound profile access: super administrators can manage every profile; regular administrators only see and use profiles assigned to their account

File Browser Copy Section

• Browse files on remote backends (local, Docker, SSH, Singularity)
• Upload, download, rename, copy, move, and delete files
• Store uploaded files under the selected/requested Hermes profile while keeping downloads path-based for agent-generated artifacts outside the upload directory
• Create directories
• Preview and edit supported files with syntax highlighting, then attach workspace files back to a chat

Group Chat Copy Section

• Multi-agent chat rooms with real-time messaging via Socket.IO
• @mention routing — mention an agent to trigger a contextual reply
• Context compression — automatic conversation summarization when history exceeds token threshold
• Typing status and reply progress indicators
• Room creation, deletion, and invite code management
• Agent management — add/remove agents from rooms with per-agent profiles
• SQLite message persistence
• Mobile responsive with collapsible sidebar

Coding Agents Copy Section

• Install, configure, launch, and monitor Claude Code and Codex from the dashboard
• Built-in coding-agent terminal, session history, workspace selection, images, and file diffs
• Dedicated proxy routes and API modes for provider/model compatibility
• Standalone desktop chat windows and persisted output/reasoning metadata

Desktop Agent Browser Copy Section

• Desktop-only multi-tab browser that agents can navigate through the managed MCP server
• Isolated browser profiles, per-tab control leases, proxy settings, downloads, cookies, and permissions
• Accessibility snapshots, screenshots, console logs, and page annotations for agent-assisted browsing

Skills & Memory Copy Section

• Browse and search installed skills
• View skill details and attached files
• Install and manage Skill Bundles with profile-aware usage statistics
• User notes, persistent Ekko Agent memory, and profile-scoped memory management
• Interactive Journey graph for skill/memory relationships, category filtering, detail inspection, and playback

Theme Customization Copy Section

• Light/dark mode, interface style, base font size, text color, and active color
• Per-account background images and live preview across the workspace

Logs Copy Section

• View agent / server / error logs
• Filter by log level, log file, and keyword
• Structured log parsing with HTTP access log highlighting

Admin & Runtime Management Copy Section

• Device and LAN peer views for local-network discovery and peer tooling
• MCP manager for the managed hermes-studio server, profile injection, and api / browser / devices / use toolsets
• Runtime version and version-preview tooling for testing newer builds in isolation
• Performance monitor views for super administrators

Authentication Copy Section

• Token-based auth (auto-generated on first run or set via AUTH_TOKEN env var)
• Username/password login with account management in Settings
• Default bootstrap credentials are admin / 123456; users are prompted after login to change the default username and password
• Super administrators can manage users and profile bindings; regular administrators can manage their own account details

CLI maintenance commands:

# Delete persisted login IP lock records
hermes-web-ui clear-login-locks

# Delete login locks and restart the running Web UI process
hermes-web-ui clear-login-locks --restart

# Create or reset the default super administrator login to admin / 123456
hermes-web-ui reset-default-login

clear-login-locks removes ${HERMES_WEB_UI_HOME:-~/.hermes-web-ui}/.login-lock.json. If the server is running, restart it to clear in-memory lock state. reset-default-login updates the Web UI account database; if an admin user already exists, its password is reset to 123456 and the account is enabled as a super administrator.

Settings Copy Section

• Display (streaming, compact mode, reasoning, cost display)
• Agent (max turns, timeout, tool enforcement)
• Memory (enable/disable, char limits)
• Session reset (idle timeout, scheduled reset)
• Privacy (PII redaction)
• Model settings (default model & provider)
• Profile and provider configuration

Voice / TTS / STT Copy Section

• Manage voice providers under Models → STT and Models → TTS; existing Settings → Voice links redirect there.
• TTS adapters: Edge, OpenAI-compatible, MiMo, Doubao, ElevenLabs, Gemini, xAI, Mistral, MiniMax, and DeepInfra.
• STT adapters: Browser, OpenAI-compatible, Doubao, Groq, Mistral, xAI, ElevenLabs, and DeepInfra.
• Use editable turn-based voice input from the chat mic, or open the full-screen real-time voice stage for a continuous voice-focused experience.
• Provider keys and MiMo voice-clone audio stay server-side; the browser receives only masked secret status.
• Starting a new voice turn stops current assistant playback first, but does not implicitly cancel an active agent run.
• For supported settings, security notes, and current non-goals, see docs/voice-dialogue.md.
• The real-time stage does not claim simultaneous full-duplex listen/speak; telephony and always-on wake-word listening remain out of scope.

Web Terminal Copy Section

• Integrated terminal powered by node-pty and @xterm/xterm
• Multi-session support — create, switch between, and close terminal sessions
• Real-time keyboard input and PTY output streaming via WebSocket
• Window resize support

Desktop App & Updates Copy Section

• Native Electron shell for Windows, macOS, and Linux
• Bundles the Web UI runtime and starts the local Hermes Studio server automatically
• Uses Cloudflare download endpoints for desktop auto-update metadata and assets first
• Falls back to GitHub Releases latest assets if the Cloudflare update feed is unavailable
• Windows upgrades attempt to close an existing Hermes Studio process before replacing files

Quick Start Copy Chapter

Desktop App (Recommended) Copy Section

Download the latest Hermes Studio desktop installer from
GitHub Releases.

Desktop builds are published for macOS, Windows, and Linux, with separate
architecture assets where applicable. The desktop app bundles the Web UI
runtime and stores Hermes Agent data in the native Hermes location:

• Windows: %LOCALAPPDATA%\hermes (falls back to %APPDATA%\hermes)
• macOS/Linux: ~/.hermes

The desktop wrapper stores its own Web UI state separately in
~/.hermes-web-ui unless HERMES_WEB_UI_HOME is set.

After the packaged desktop app starts, it installs managed command shims so the
desktop app, bundled Hermes Agent CLI, and bundled Web UI CLI do not conflict:

Use hermes-studio cli -h for Hermes Agent CLI help and
hermes-studio web -h for Web UI CLI help. hermes-studio-mcp defaults to the
api toolset; choose browser, devices, or use to keep the exposed MCP
surface focused on the current task.

Desktop auto-updates read the latest feed from
https://download.ekkolearnai.com/latest first. If that endpoint is
unavailable, the updater falls back to
https://github.com/EKKOLearnAI/hermes-studio/releases/latest/download.

npm Copy Section

npm install hermes-web-ui
hermes-web-ui start

Open http://localhost:8648

Docker Compose Copy Section

Single-container deployment with integrated Hermes Agent:

# Use pre-built image (Recommended)
WEBUI_IMAGE=ekkoye8888/hermes-web-ui docker compose up -d

# Or build from source
docker compose up -d --build

docker compose logs -f hermes-webui

Open http://localhost:6060

• Persistent Hermes data is stored in ./hermes_data
• Web UI auth token is stored in ./hermes_data/hermes-web-ui/.token
• On first run with auth enabled, the token is printed to container logs
• All runtime settings are environment-variable driven in docker-compose.yml

For detailed notes and troubleshooting, see docs/docker.md.

Hermes Agent Runtime Discovery Copy Section

When Web UI starts backend chat features, it prefers a source checkout that
contains run_agent.py such as ~/.hermes/hermes-agent. If no source checkout
is found, it falls back to the Python environment used by the installed
hermes command, then the system Python. This supports both source installs
and package installs such as pip install hermes-agent.

Web UI Environment Variables Copy Chapter

These variables configure Hermes Web UI, its local Hermes runtime integration, and development/preview helpers. Provider API keys and Hermes Agent settings are normally managed through Hermes profiles; environment variables here are process-level overrides.

CLI Commands Copy Section

Add --no-open to start or client when no browser should open.

restart, update, and upgrade stop the Agent Bridge broker by default so restarted or updated servers do not reuse stale Python bridge processes. Set HERMES_AGENT_BRIDGE_STOP_ON_SHUTDOWN=0 before restarting only when you explicitly want to keep the bridge broker and running bridge sessions alive.

update / upgrade first attempt npm cache clean --force, then run npm install hermes-web-ui@latest and restart. Cache cleanup is best-effort; if it fails, the updater continues with the install.

Auto Configuration Copy Section

On startup the BFF server automatically:

• Initializes Web UI data directories, local databases, and bundled skills
• Starts the Hermes agent bridge used by /chat-run
• Opens a browser on successful startup unless --no-open is set

Development Copy Chapter

git clone https://github.com/EKKOLearnAI/hermes-studio.git
cd hermes-web-ui
npm install
npm run dev

• Frontend: http://localhost:8649
• BFF Server: http://localhost:8647

npm run build   # outputs to dist/

See DEVELOPMENT.md for project development guidelines.

Architecture Copy Chapter

Browser → BFF (Koa, :8648) → Socket.IO /chat-run
                ↓
        Hermes agent bridge → Hermes Agent runtime
                ↓
           Hermes CLI / profiles
           profile config.yaml    (channel/provider behavior)
           profile auth.json      (credential pool)
           Tencent iLink API      (WeChat QR login)

The frontend is designed with multi-agent extensibility — all Hermes-specific code is namespaced under hermes/ directories (API, components, views, stores), making it straightforward to add new agent integrations alongside.

The BFF layer handles Socket.IO chat streaming, the Hermes agent bridge, profile-aware file upload and path-based download (multi-backend: local/Docker/SSH/Singularity), session CRUD, account- and profile-scoped management, config/credential management, WeChat QR login, model discovery, skills/memory/plugin management, TTS/STT, coding-agent proxies, MCP/runtime management, log reading, and static file serving.

Tech Stack Copy Chapter

Frontend: Vue 3 + TypeScript + Vite + Naive UI + Pinia + Vue Router + vue-i18n + SCSS + markdown-it + highlight.js

Backend: Koa 2 (BFF server) + node-pty (web terminal)

License Copy Chapter

BSL-1.1

The license covers Hermes Studio, the former Hermes Web UI name, the
hermes-web-ui npm package and CLI, desktop applications, firmware, release
artifacts, documentation, and associated files in this repository.

File: docs/docker.md Copy Chapter

Docker Compose Guide

This repository ships an environment-variable driven Docker Compose setup.

Quick Start Copy Chapter

Pull pre-built image (Recommended) Copy Section

WEBUI_IMAGE=ekkoye8888/hermes-web-ui docker compose up -d
docker compose logs -f hermes-webui

Open: http://localhost:6060

Build from source Copy Section

docker compose up -d --build
docker compose logs -f hermes-webui

Services Copy Chapter

This compose file runs a single service:

• hermes-webui — Web UI dashboard with integrated Hermes Agent runtime (pre-built image or built from source)

The Web UI container is built on the nousresearch/hermes-agent base image and uses the Hermes CLI / agent bridge runtime for chat execution. By default it performs startup gateway checks/autostart for profiles, but no Hermes gateway ports are exposed by this compose setup.

Environment Variables Copy Chapter

All key runtime settings are configured from compose variables.

Override variables directly from shell:

PORT=16060 docker compose up -d

Or create a .env file in the project root:

WEBUI_IMAGE=ekkoye8888/hermes-web-ui
PORT=6060

Data Persistence Copy Chapter

• Hermes data persists in ./hermes_data, mapped to /home/agent/.hermes in the container.
• Web UI data persists in ./hermes_data/hermes-web-ui/, mapped to /home/agent/.hermes-web-ui in the container.
• The auth token is auto-generated on first run and printed to container logs.
• Deleting the token file and restarting will generate a new one.

Port Mapping Copy Chapter

No Hermes gateway ports are exposed by this compose setup.

Code Runtime Behavior Copy Chapter

• Hermes CLI binary comes from HERMES_BIN env (packages/server/src/services/hermes-cli.ts).
• If HERMES_BIN is not provided, code falls back to hermes in PATH.
• Profile-specific chat runs are handled through the Hermes agent bridge. The selected/requested profile is authorized per account and passed with runtime requests; switching the frontend Hermes Profile does not restart the bridge or clear other running tasks.
• Docker is a managed gateway runtime: Web UI checks profile gateways on startup, but it does not run a periodic gateway recovery loop.

Common Operations Copy Chapter

Recreate:

docker compose up -d --force-recreate

View auth token:

docker compose logs hermes-webui | grep token
# or
cat ./hermes_data/hermes-web-ui/.token

Stop:

docker compose down

File: README_zh.md Copy Chapter

核心能力 Copy Chapter

功能特性 Copy Chapter

AI 聊天 Copy Section

• 聊天前端通过 Socket.IO /chat-run 实时流式更新；聊天运行通过 Hermes agent bridge 执行
• 多会话管理 — 创建、重命名、删除、切换会话
• 自建会话数据库 — Web UI 会话使用本地 SQLite；Hermes state.db 仅作为只读来源用于 Hermes 历史 API
• 按来源分组会话（Telegram、Discord、Slack 等），可折叠手风琴面板
• 活跃会话实时指示器 — 正在进行的会话置顶并显示旋转图标
• 按最新消息时间排序会话列表
• Markdown 渲染，支持语法高亮和代码复制
• 工具调用详情展开（参数 / 结果）
• 按 Profile 隔离的文件上传、剪贴板图片/文件粘贴和工作区附件
• 文件下载支持 — 按解析后的路径下载用户上传文件和 Agent 生成文件，兼容 local、Docker、SSH、Singularity 等多种 terminal backend
• 可直接预览 Agent 生成的 HTML、PDF、DOCX、PPTX、XLSX、CSV、图片、Markdown 和源码文件
• 会话搜索 — Ctrl+K 搜索 Web UI 本地会话库；不包含只读 Hermes 历史会话
• 会话分类、消息引用、压缩进度和可持久恢复的后台委派结果
• 按账号授权 Profile 汇总模型选择器 — 只展示当前账号可访问的 Hermes Profile 中可用的模型
• 每个会话显示模型标签和上下文 Token 用量

平台渠道 Copy Section

在一个页面统一配置 10 个平台：

• 凭证管理写入 ~/.hermes/.env
• 渠道行为设置写入 ~/.hermes/config.yaml
• 每个平台已配置/未配置状态检测

用量分析 Copy Section

• Token 总用量明细（输入 / 输出）
• 会话数及日均统计
• 预估费用追踪及缓存命中率
• 模型使用分布图
• 30 天每日趋势（柱状图 + 数据表格）

定时任务 Copy Section

• 创建、编辑、暂停、恢复、删除 Cron 任务
• 立即触发执行
• Cron 表达式快捷预设

Kanban Copy Section

• 按 Profile 管理的 Kanban 看板，用于规划和跟踪 Agent 工作
• 可在仪表盘中创建任务、更新任务并移动状态
• 复用 Web UI 本地状态和认证体系

可视化工作流 Copy Section

• 基于 Vue Flow 的画布，支持 Hermes、Codex 和 Claude Code 节点以及文件/图片附件
• 支持有向连线、结构化条件、成功/失败路由、循环和审批门
• 工作流定义可导入/导出，并支持按 Profile 管理工作区
• 支持运行预算、截止时间、停止、重跑和持久化执行历史
• 可在画布回放冻结的运行快照、节点对话、路径选择和执行证据

模型管理 Copy Section

• 从凭证池自动发现模型（~/.hermes/auth.json）
• 从每个 Provider 端点获取可用模型（/v1/models）
• 添加、更新、删除 Provider（预设和自定义 OpenAI 兼容）
• 支持 OpenAI Codex、Nous Portal、xAI、Claude 和 GitHub Copilot 的 OAuth/设备授权
• Provider URL 自动检测，支持非 v1 API 版本（如 /v4）
• Provider 级模型分组、可见模型控制、别名、刷新和默认模型切换
• 在模型页分别管理 STT 与 TTS Provider

多配置文件 Copy Section

• 创建、重命名、删除、切换 Hermes 配置文件（Profile）
• 克隆现有配置文件或从归档导入（.tar.gz）
• 导出配置文件用于备份或分享
• 按 Profile 隔离配置、缓存、上传、会话、任务、用量、记忆、技能、插件、Provider 和模型可见性
• 账号绑定 Profile 权限：超级管理员可以管理全部 Profile；普通管理员只能查看和使用分配给自己的 Profile

文件浏览器 Copy Section

• 浏览远程后端文件（local、Docker、SSH、Singularity）
• 上传、下载、重命名、复制、移动和删除文件
• 上传文件保存到当前选择/请求的 Hermes Profile 目录下；下载按真实路径解析，支持下载上传目录外的 Agent 产物
• 创建目录
• 预览和编辑支持的文件并提供语法高亮，还可把工作区文件附加回聊天

群聊 Copy Section

• 多 Agent 聊天房间，通过 Socket.IO 实时通信
• @提及路由 — 提及 Agent 触发上下文回复
• 上下文压缩 — 历史消息超过 Token 阈值时自动摘要压缩
• 输入状态和回复进度指示器
• 房间创建、删除和邀请码管理
• Agent 管理 — 添加/移除房间中的 Agent，支持独立 Profile
• SQLite 消息持久化
• 移动端响应式布局，可折叠侧边栏

Coding Agents Copy Section

• 在仪表盘中安装、配置、启动和监控 Claude Code 与 Codex
• 内置 Coding Agent 终端、会话历史、工作区选择、图片输入和文件 Diff
• 提供独立代理路由和 API 模式，适配不同 Provider/模型
• 支持桌面独立聊天窗口，并持久化输出和 reasoning 元数据

桌面 Agent 浏览器 Copy Section

• 桌面端多标签浏览器，Agent 可通过托管 MCP Server 进行导航和交互
• 支持隔离浏览器 Profile、标签控制租约、代理、下载、Cookie 和权限管理
• 支持可访问性快照、截图、控制台日志和页面标注

技能与记忆 Copy Section

• 浏览和搜索已安装的技能
• 查看技能详情和附件
• 安装和管理 Skill Bundles，并查看按 Profile 统计的技能用量
• 用户笔记、Ekko Agent 持久记忆和按 Profile 管理的记忆
• 学习轨迹关系图，支持技能/记忆关系、分类筛选、详情查看和播放

主题自定义 Copy Section

• 支持明暗模式、界面风格、基础字号、文字颜色和选中颜色
• 支持按账号保存背景图片，并在整个工作区实时预览

日志 Copy Section

• 查看 Agent / Server / Error 日志
• 按日志级别、日志文件和关键词过滤
• 结构化日志解析，HTTP 访问日志高亮

管理与运行时 Copy Section

• 设备和局域网 Peer 页面，用于本地网络发现和 Peer 工具能力
• MCP 管理器，用于托管的 hermes-studio Server、Profile 自动注入和 api / browser / devices / use 工具集
• Runtime Version 和 Version Preview 工具，用于隔离测试新版本
• 面向超级管理员的性能监控视图

认证 Copy Section

• 基于 Token 的认证（首次运行自动生成或通过 AUTH_TOKEN 环境变量设置）
• 用户名/密码登录，并在设置页提供账户管理
• 默认登录名/密码为 admin / 123456；登录后会提示尽快修改默认账户和密码
• 超级管理员可以管理用户和 Profile 绑定；普通管理员只能管理自己的账户信息

CLI 维护命令：

# 删除持久化的登录 IP 锁记录
hermes-web-ui clear-login-locks

# 删除登录锁并重启正在运行的 Web UI 进程
hermes-web-ui clear-login-locks --restart

# 创建或重置默认超级管理员登录名/密码为 admin / 123456
hermes-web-ui reset-default-login

clear-login-locks 会删除 ${HERMES_WEB_UI_HOME:-~/.hermes-web-ui}/.login-lock.json。如果服务正在运行，需要重启服务才能清理内存中的锁定状态。reset-default-login 会更新 Web UI 账户数据库；如果已存在 admin 用户，则会把密码重置为 123456，并启用为超级管理员账户。

设置 Copy Section

• 显示（流式输出、紧凑模式、推理过程、费用显示）
• Agent（最大轮次、超时时间、工具强制执行）
• 记忆（启用/禁用、字符限制）
• 会话重置（空闲超时、定时重置）
• 隐私（PII 脱敏）
• 模型设置（默认模型 & Provider）
• Profile 和 Provider 配置

语音 / TTS / STT Copy Section

• 在模型 → STT 和模型 → TTS 中管理语音 Provider；旧的设置 → 语音入口会跳转到这里。
• TTS 适配器：Edge、OpenAI 兼容、MiMo、豆包、ElevenLabs、Gemini、xAI、Mistral、MiniMax、DeepInfra。
• STT 适配器：浏览器、OpenAI 兼容、豆包、Groq、Mistral、xAI、ElevenLabs、DeepInfra。
• 可在聊天输入框使用可编辑的回合制语音输入，也可打开全屏实时语音舞台进入连续的语音交互体验。
• Provider Key 和 MiMo 音色复刻音频保存在服务端，浏览器只接收脱敏后的 Secret 状态。
• 开始新的语音输入会先停止 Assistant 播放，但不会隐式取消正在执行的 Agent Run。
• 支持的设置项、安全边界和当前非目标范围见 docs/voice-dialogue.md。
• 实时语音舞台不代表同时听说的全双工通话；电话接入和常驻唤醒词监听仍不在当前范围。

Web 终端 Copy Section

• 集成终端，基于 node-pty 和 @xterm/xterm
• 多会话支持 — 创建、切换、关闭终端会话
• 通过 WebSocket 实时传输键盘输入和 PTY 输出
• 支持窗口大小调整

桌面应用与自动更新 Copy Section

• Windows、macOS 和 Linux 原生 Electron 桌面壳
• 内置 Web UI 运行时，并自动启动本地 Hermes Studio 服务
• 桌面自动更新优先使用 Cloudflare 下载端点获取更新元数据和安装包
• 如果 Cloudflare 更新源不可用，会回退到 GitHub Releases latest 资源
• Windows 升级时会先尝试关闭已有 Hermes Studio 进程，再替换文件

快速开始 Copy Chapter

桌面应用（推荐） Copy Section

从 GitHub Releases
下载最新的 Hermes Studio 桌面安装包。

桌面版会发布 macOS、Windows 和 Linux 构建；适用时会区分不同 CPU 架构。
桌面应用内置 Web UI 运行时，Hermes Agent 数据会保存到原生 Hermes 目录：

• Windows：%LOCALAPPDATA%\hermes（找不到时回退到 %APPDATA%\hermes）
• macOS/Linux：~/.hermes

桌面壳自身的 Web UI 状态会单独保存到 ~/.hermes-web-ui，除非设置了
HERMES_WEB_UI_HOME。

打包后的桌面应用启动后，会安装受管命令 shim，避免桌面应用、内置 Hermes Agent CLI
和内置 Web UI CLI 的命令互相冲突：

使用 hermes-studio cli -h 查看 Hermes Agent CLI 帮助，使用
hermes-studio web -h 查看 Web UI CLI 帮助。hermes-studio-mcp 默认暴露
api 工具集；按任务选择 browser、devices 或 use，可以缩小 MCP 暴露面。

桌面自动更新会优先读取 https://download.ekkolearnai.com/latest。
如果该端点不可用，更新器会回退到
https://github.com/EKKOLearnAI/hermes-studio/releases/latest/download。

npm 安装 Copy Section

npm install hermes-web-ui
hermes-web-ui start

打开 http://localhost:8648

Docker Compose Copy Section

单容器部署，内置 Hermes Agent 运行时：

# 使用预构建镜像（推荐）
WEBUI_IMAGE=ekkoye8888/hermes-web-ui docker compose up -d

# 或从源码构建
docker compose up -d --build

docker compose logs -f hermes-webui

打开 http://localhost:6060

• Hermes 持久化数据目录：./hermes_data
• Web UI 认证 Token 存储在 ./hermes_data/hermes-web-ui/.token
• 首次启动并开启认证时，Token 会打印到容器日志中
• 运行参数全部由 docker-compose.yml 环境变量驱动

更详细的说明与排错见：docs/docker.md

Hermes Agent 运行时发现 Copy Section

Web UI 启动后端聊天能力时，会优先使用包含 run_agent.py 的源码目录，例如
~/.hermes/hermes-agent。如果找不到源码目录，会退回到已安装 hermes 命令所使用
的 Python 环境，再退到系统 Python。因此源码安装和 pip install hermes-agent 这类
包安装方式都可以兼容。

Web UI 环境变量 Copy Chapter

这些变量用于配置 Hermes Web UI、本地 Hermes runtime 集成以及开发/预览辅助能力。Provider API Key 和 Hermes Agent 相关设置通常仍通过 Hermes profile 管理；这里列出的变量是进程级覆盖项。

CLI 命令 Copy Section

如不希望自动打开浏览器，可在 start 或 client 后添加 --no-open。

restart、update 和 upgrade 默认会停止 Agent Bridge broker，避免重启或更新后的服务复用旧 Python bridge 进程。只有明确希望保留 broker 和正在运行的 bridge session 时，才在重启前设置 HERMES_AGENT_BRIDGE_STOP_ON_SHUTDOWN=0。

update / upgrade 会先尝试执行 npm cache clean --force，再执行 npm install hermes-web-ui@latest 并重启。缓存清理是 best-effort；如果清理失败，只提示 warning，升级安装会继续执行。

自动配置 Copy Section

启动时 BFF 服务器会自动：

• 初始化 Web UI 数据目录、本地数据库和内置技能
• 启动 /chat-run 使用的 Hermes agent bridge
• 启动成功后自动打开浏览器；设置 --no-open 时跳过

开发 Copy Chapter

git clone https://github.com/EKKOLearnAI/hermes-studio.git
cd hermes-web-ui
npm install
npm run dev

• 前端：http://localhost:8649
• BFF 服务器：http://localhost:8647

npm run build   # 构建输出到 dist/

项目开发规范见：DEVELOPMENT.md。

架构 Copy Chapter

浏览器 → BFF (Koa, :8648) → Socket.IO /chat-run
                ↓
        Hermes agent bridge → Hermes Agent runtime
                ↓
           Hermes CLI / profiles
           profile config.yaml    (渠道/Provider 配置)
           profile auth.json      (凭证池)
           腾讯 iLink API         (微信扫码登录)

前端采用 多 Agent 可扩展架构 — 所有 Hermes 相关代码都按命名空间组织在 hermes/ 目录下（API、组件、视图、Store），可以方便地并行接入新的 Agent。

BFF 层负责：Socket.IO 聊天流式推送、Hermes agent bridge、按 Profile 隔离的上传和按路径解析的下载（多 Backend 支持：local/Docker/SSH/Singularity）、会话 CRUD、分账户分 Profile 管理、配置/凭证管理、微信扫码登录、模型发现、技能/记忆/插件管理、TTS/STT、Coding Agent 代理、MCP/Runtime 管理、日志读取和静态文件服务。

技术栈 Copy Chapter

前端： Vue 3 + TypeScript + Vite + Naive UI + Pinia + Vue Router + vue-i18n + SCSS + markdown-it + highlight.js

后端： Koa 2（BFF 服务器）+ node-pty（Web 终端）

许可证 Copy Chapter

BSL-1.1

该许可证覆盖 Hermes Studio、原 Hermes Web UI 名称、hermes-web-ui npm 包和
CLI、桌面应用、固件、发布产物、文档以及本仓库内的关联文件。