hermes-studio

Hermes Studio 中文

A desktop app, local runtime, and web console for Hermes Agent.
Chat with agents, build visual workflows, manage models and profiles,
browse the web, run coding agents, and keep everything local.

Download Hermes Studio Desktop · Documentation · npm install -g hermes-web-ui && hermes-web-ui start

Core Capabilities

Area	What Hermes Studio does
Agent chat	Runs Hermes Agent conversations with streaming responses, tool traces, generated-file previews, persistent local sessions, and standalone desktop chat windows.
Local control plane	Manages profiles, providers, models, credentials, memory, skills, plugins, logs, and runtime settings from one dashboard.
Automation	Builds executable visual workflows and configures platform channels, cron jobs, Kanban tasks, group-chat rooms, and MCP servers around the same Hermes profiles.
Workspace tools	Provides a file browser, web terminal, Desktop Agent Browser, voice input/output, coding-agent runners, device discovery, Journey graph, and performance views.
Distribution	Ships as a desktop app for Windows/macOS/Linux, an npm CLI package, and a Docker image.

Features

AI Chat

• 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

Unified configuration for 10 platforms in one page:

Platform	Features
Telegram	Bot token, mention control, reactions, free-response chats
Discord	Bot token, mention, auto-thread, reactions, channel allow/ignore lists
Slack	Bot token, mention control, bot message handling
WhatsApp	Enable/disable, mention control, mention patterns
Matrix	Access token, homeserver, auto-thread, DM mention threads
Feishu (Lark)	App ID / Secret, mention control
DingTalk	Client ID / Secret, mention control
QQBot	App ID / Secret, mention control
WeChat	QR code login (scan in browser, auto-save credentials)
WeCom	Bot ID / Secret

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

Usage Analytics

• 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

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

Kanban

• 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

• 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

• 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

• 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

• 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

• 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

• 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

• 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

• 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

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

Logs

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

Admin & Runtime Management

• 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

• 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

• 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

• 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

• 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

• 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

Desktop App (Recommended)

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:

Command	Description
hermes-studio	Open the Hermes Studio desktop app
hermes-studio cli ...	Run the bundled Hermes Agent CLI
hermes-studio web ...	Run the bundled hermes-web-ui command
hermes-studio -h	Show wrapper help
hermes-studio-mcp [api|browser|devices|use]	Run one managed Web UI MCP toolset

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

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

Open http://localhost:8648

Docker Compose

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

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

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.

Variable	Default	Description
PORT	8648	Web UI listen port.
BIND_HOST	0.0.0.0	Web UI bind host. Set :: explicitly for IPv6.
HERMES_WEB_UI_HOME	~/.hermes-web-ui	Web UI data home for auth token, credentials, logs, DB, and default uploads. HERMES_WEBUI_STATE_DIR is also supported as a compatibility alias.
HERMES_WEBUI_STATE_DIR	unset	Compatibility alias for HERMES_WEB_UI_HOME.
HERMES_WEB_UI_DISABLE_MCP_AUTOINJECT	unset	Disable startup injection of the managed hermes-studio MCP server into Hermes profile configs.
HERMES_WEB_UI_ALLOW_TRANSIENT_MCP_AUTOINJECT	unset	Allow managed MCP injection when HERMES_WEB_UI_HOME is under a temporary directory, such as Version Preview runtimes.
UPLOAD_DIR	$HERMES_WEB_UI_HOME/upload	Upload root override. Files are stored below profile-scoped subdirectories.
CORS_ORIGINS	same host only	Comma- or space-separated cross-origin allowlist for HTTP, Socket.IO, and WebSocket requests. Set * only when you intentionally need legacy wildcard CORS.
AUTH_TOKEN	auto-generated	Explicit bearer token. If unset, Web UI creates one under HERMES_WEB_UI_HOME.
AUTH_JWT_SECRET	AUTH_TOKEN	JWT signing secret override for username/password sessions.
HERMES_WEB_UI_AUTH_JWT_EXPIRES_IN	30d	Username/password session JWT lifetime. Accepts seconds or s/m/h/d suffixes, for example 12h or 7d.
PROFILE	default	Startup/default Hermes profile. Runtime requests use the profile selected by the frontend and authorized for the current account.
LOG_LEVEL	info	Server log level.
BRIDGE_LOG_LEVEL	$LOG_LEVEL or info	Bridge log level.
MAX_DOWNLOAD_SIZE	200MB	Maximum file download size.
MAX_EDIT_SIZE	10MB	Maximum editable file size.
WORKSPACE_BASE	current user's home directory	Base directory for workspace browsing.
HERMES_HOME	platform default	Hermes data home. Windows uses %LOCALAPPDATA%\hermes; macOS/Linux uses ~/.hermes.
HERMES_BIN	hermes	Custom Hermes CLI binary path.
HERMES_AGENT_ROOT	auto-discovered	Hermes Agent source checkout containing run_agent.py.
HERMES_AGENT_BRIDGE_PYTHON	auto-discovered	Python interpreter used to launch the agent bridge.
HERMES_AGENT_BRIDGE_UV	auto-discovered	uv executable used to launch the agent bridge when available.
UV	auto-discovered	Fallback uv executable path.
PYTHON	auto-discovered	Fallback Python executable for the agent bridge.
HERMES_AGENT_BRIDGE_ENDPOINT	platform default	Agent bridge broker endpoint. Windows defaults to tcp://127.0.0.1:18765; macOS/Linux defaults to ipc:///tmp/hermes-agent-bridge.sock.
HERMES_AGENT_BRIDGE_TIMEOUT_MS	120000	Timeout for Node requests to the bridge broker.
HERMES_AGENT_BRIDGE_CONNECT_RETRY_MS	5000	Short retry window for connecting to the bridge socket.
HERMES_AGENT_BRIDGE_STARTUP_TIMEOUT_MS	120000	Timeout while waiting for the Python bridge to become ready.
HERMES_AGENT_BRIDGE_STOP_ON_SHUTDOWN	enabled	Stop the bridge broker during Web UI shutdown and restart. Set 0, false, no, or off to keep the bridge across restarts.
HERMES_AGENT_BRIDGE_AUTO_RESTART	enabled	Auto-restart the bridge broker after unexpected exit. Set 0, false, no, or off to disable.
HERMES_AGENT_BRIDGE_RESTART_DELAY_MS	1000	Base delay for bridge auto-restart backoff.
HERMES_AGENT_BRIDGE_PLATFORM	cli	Platform identity passed to Hermes Agent.
HERMES_AGENT_BRIDGE_WORKER_TRANSPORT	platform default	Profile worker transport. Set tcp for loopback TCP or ipc/unix for Unix domain sockets; defaults to Windows TCP and macOS/Linux IPC.
HERMES_AGENT_BRIDGE_WORKER_PORT_BASE	18780	Base port for TCP worker endpoints.
HERMES_BRIDGE_PROVIDER	profile/default	Provider override for bridge runs.
HERMES_BRIDGE_TOOLSETS	profile/default	Toolset override for bridge runs.
HERMES_BRIDGE_MAX_TURNS	profile/default	Maximum turn override for bridge runs.
HERMES_BRIDGE_SUPPRESS_PLATFORM_HINT	cli	Controls bridge platform hint suppression passed to Hermes Agent.
HERMES_OPENROUTER_APP_REFERER	https://hermes-studio.ai	OpenRouter attribution referer sent by bridge runs.
HERMES_OPENROUTER_APP_TITLE	Hermes Web UI	OpenRouter attribution title sent by bridge runs.
HERMES_OPENROUTER_APP_CATEGORIES	cli-agent,personal-agent	OpenRouter attribution categories sent by bridge runs.
HERMES_WEB_UI_MANAGED_GATEWAY	enabled	Controls Web UI-managed Hermes gateway process handling. Set 0, false, no, or off to use hermes gateway start instead.
HERMES_WEB_UI_DISABLE_GATEWAY_AUTOSTART	unset	Skip startup gateway checks/autostart. Set 1, true, yes, or on for dashboard-only deployments where another service owns Hermes gateway lifecycle.
HERMES_WEB_UI_DISABLE_SKILL_INJECTION	unset	Skip startup bundled skill injection. Set 1, true, yes, or on when bundled skills are managed outside Hermes Web UI. When injection is enabled, Web UI updates only skills it previously installed or identical existing bundled copies; local edits and user-owned same-name skills are skipped.
HERMES_WEB_UI_STOP_GATEWAYS_ON_SHUTDOWN	enabled in production	Controls whether Web UI shutdown also stops managed gateway processes. Set 0 or false to detach them.
HERMES_GATEWAY_URL / GATEWAY_URL	unset	Explicit Hermes gateway upstream URL for proxy routes.
GATEWAY_HOST	127.0.0.1	Default Hermes gateway upstream host for proxy routes.
GATEWAY_PORT	8642	Default Hermes gateway upstream port for proxy routes.
HERMES_WEB_UI_PREVIEW_REPO	package repository	GitHub repository used by Version Preview.
HERMES_WEB_UI_PREVIEW_AGENT_BRIDGE_TRANSPORT	platform default	Version Preview broker transport. Set tcp to use loopback TCP for Preview on macOS/Linux; when unset, Preview follows HERMES_AGENT_BRIDGE_WORKER_TRANSPORT=tcp.
HERMES_WEB_UI_PREVIEW_AGENT_BRIDGE_ENDPOINT	isolated preview endpoint	Directly overrides the Version Preview broker endpoint.
HERMES_WEB_UI_BACKEND_PORT	8648	Backend port used by the Vite dev proxy.
HERMES_WEB_UI_FRONTEND_PORT	8649	Frontend Vite dev server port.

CLI Commands

Command	Description
hermes-web-ui start [port]	Start in background; accepts a positional port or --port <port>
hermes-web-ui client [port]	Start for a remote client with gateway autostart disabled and permissive CORS
hermes-web-ui restart [port]	Restart; stops the bridge by default
hermes-web-ui stop	Stop the background process
hermes-web-ui status	Check if running
hermes-web-ui clear-login-locks [--restart]	Clear persisted login locks, optionally restart
hermes-web-ui reset-default-login	Create or reset the default administrator login
hermes-web-ui update / upgrade	Update to the latest version and restart
hermes-web-ui version / -v	Show the version
hermes-web-ui -h	Show help

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 -g hermes-web-ui@latest and restart. Cache cleanup is best-effort; if it fails, the updater continues with the install.

Auto Configuration

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

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

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

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

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.