@quanthermes/hermes-web-ui

Hermes Studio 中文

A desktop app, local runtime, and web console for Hermes Agent.
Chat with agents, manage models and profiles, connect platform channels,
automate jobs, inspect files, run coding agents, and keep everything local. A full-featured web dashboard for Hermes Agent.
Manage AI chat sessions, monitor usage & costs, configure platform channels,
schedule cron jobs, browse skills — all from a clean, responsive web interface.

npm install -g @quanthermes/hermes-web-ui && hermes-web-ui start

Core Capabilities

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
• File download support — download uploaded files and agent-generated files by resolved path across local, Docker, SSH, and Singularity backends
• Session search — Ctrl+K search across the Web UI local session database; read-only Hermes history sessions are not included
• 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 8 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

• 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

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 & custom OpenAI-compatible)
• OpenAI Codex & Nous Portal OAuth login
• Provider URL auto-detection for non-v1 API versions (e.g. /v4)
• Provider-level model grouping with default model switching

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
• View file content with syntax highlighting

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

• Launch and monitor local coding-agent sessions from the web dashboard
• Dedicated proxy routes for Codex and Claude Code integrations
• DeepSeek Harness (deepseek-harness) as a managed coding agent, driven over JSON-RPC stdio and mapped onto the same streaming event pipeline
• Stores agent output and reasoning metadata for later inspection

Skills & Memory

• Browse and search installed skills
• View skill details and attached files
• User notes and profile management

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 MCP server and profile injection
• 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.

When the login page reports that the IP is locked (HTTP 429/503), the same operations are available directly in the UI as two buttons — "Clear Login Lock" and "Reset Default Password" — protected by a single shared recovery password. By default the recovery password equals the shipped default admin password (12345678); override it with the HERMES_WEB_UI_RECOVERY_PASSWORD environment variable to use an independent value.

Device QR Login (Token Platform)

Hardware Hermes devices (QuantClaw, 量迹龙虾盒子, etc.) can bind themselves to a Token Platform account on first boot by scanning a WeChat QR code — no manual username/password typing on the device. Once bound, the device holds a dedicated API key + model whitelist and the binding is restored on every subsequent boot.

Flow:

1. Device boots for the first time and the LoginView renders a WeChat QR (WeChatQrPanel.vue).
2. The BFF calls Token Platform POST /api/device-login/request with the device's stable hardware_id (a random UUID persisted under HERMES_WEB_UI_HOME/device-id, regenerated only if missing) and receives {appid, state, redirect_uri}.
3. User scans the QR with WeChat and confirms on the phone.
4. The device polls GET /api/device-login/status?login_id=..; on approval Token Platform returns {api_base, api_key, models, device_id} (one-shot, KeyDelivered flag prevents leak).
5. The BFF (POST /api/auth/device-login) validates the device API key via verifyDeviceApiKey, resolves the bound user profile, auto-bootstraps a local admin super admin on first run, issues a Hermes JWT, and persists the binding to ${HERMES_WEB_UI_HOME}/device-binding.json (api_base / api_key / models / display_name / username / bound_at / expires_at).
6. On later boots, useDeviceBinding reads device-binding.json and calls POST /api/auth/device-login/restore to re-issue a Hermes JWT without re-scanning.

Configuration:

• TOKEN_PLATFORM_BASE_URL (default https://api.quantclaw.vip) — Token Platform base URL.
• HERMES_WEB_UI_HOME — directory holding device-id and device-binding.json.

Endpoints (Web UI BFF):

Unbind from the UI: Settings → Device Binding → Unbind, or call DELETE /api/auth/device-binding. Unbinding only clears the local binding file; the Token Platform account and its device API key remain active until you remove the device from https://api.quantclaw.vip.

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

• Read assistant replies aloud from chat and group-chat messages.
• Providers: browser Web Speech, built-in Edge TTS, OpenAI-compatible /audio/speech, custom OpenAI-compatible TTS endpoints, and MiMo.
• MiMo supports preset voices, voice design prompts, and voice clone reference audio (.mp3/.wav, max 10 MB) with selectable auth header mode (Authorization, api-key, or both).
• Edge/OpenAI-compatible/custom/MiMo playback uses the Web UI backend's unified /api/hermes/tts/synthesize endpoint, so stop/pause state is shared and in-flight fetches are aborted when possible.
• Provider API keys and MiMo clone reference audio are saved in server-side TTS settings, with only masked secret status shown back to the browser.
• Save provider settings in Settings → Voice before using OpenAI/custom/MiMo playback. Message playback sends text and non-secret playback options; the backend reads the stored per-user secret when synthesizing.
• Turn-based voice input is available from the chat input mic control: start/stop a voice turn, transcribe it, stage the transcript in the current input box for editing, then send it with the normal Send button.
• Voice input / STT can use browser speech recognition when available or a server-backed provider configured in Settings → Voice.
• Starting a new voice turn while assistant audio is playing stops playback first. This barge-in boundary does not implicitly cancel an active agent run; stopping a run remains an explicit action.
• For supported settings, security notes, and current non-goals, see docs/voice-dialogue.md.
• Limitation: external TTS providers may continue processing a request after the browser/server aborts; custom/OpenAI-compatible and MiMo base URLs must be public http/https endpoints and cannot target localhost/private networks.

Meeting Mode

Real-time speech transcription with AI-powered meeting analysis, speaker diarization, and smart meeting minutes generation.

Core Features:

Speaker Diarization Mode:

• Enable speaker diarization to automatically identify different speakers
• Manually set speaker count (2-8) to improve identification accuracy
• Speaker IDs are automatically mapped to readable names (Speaker 1, Speaker 2...)
• Rename speakers with auto-sync across all historical records

JSON Export Format:

{
  "title": "Meeting Title",
  "createdAt": "2026-07-17T10:00:00.000Z",
  "speakers": [
    { "id": "0", "displayName": "Alice" },
    { "id": "1", "displayName": "Bob" }
  ],
  "sentences": [
    {
      "index": 1,
      "text": "Meeting transcript content",
      "startTimeMs": 1000,
      "endTimeMs": 3500,
      "speakerId": "0",
      "speakerName": "Alice"
    }
  ],
  "analysis": {
    "summary": "Meeting summary",
    "meeting_type": "Project Update",
    "key_points": ["Point 1", "Point 2"],
    "action_items": [
      { "task": "Draft the rollout plan", "assignee": "Alice", "deadline": "2026-07-25" }
    ],
    "decisions": ["Ship v0.74 behind a feature flag"],
    "risks": ["ASR backend still single-node"],
    "learnings": [],
    "feedback": { "positive": [], "negative": [] },
    "topics": ["Topic 1", "Topic 2"]
  }
}

Analysis pipeline (v0.74):

• Typed analysis triggers. Each session picks one of three modes:
  • sentences — auto-analyze every N sentences (default 10, range 1–100).
  • time — auto-analyze every N seconds (default 60, range 10–600).
  • both — trigger on either condition. Configure from the right-panel toolbar (cog icon) or via the analysisTriggerMode / analysisIntervalSentences / analysisIntervalSeconds fields on MeetingSession.
• Meeting type classification. The LLM first labels the meeting as one of Minutes, Customer Follow-up, Brainstorm, Project Update, Training, or Other, and emits type-specific fields (decisions / feedback / risks / learnings) accordingly.
• Structured action items. action_items is now [{ task, assignee, deadline }] on both the client store and the Python backend. Legacy string[] values are still rendered for backward compatibility.
• HTML report pipeline. When analysis runs, the server renders a complete, self-contained HTML document (CSS + JS inlined, ECharts only when relationships are present) tailored to the detected meeting type. The client caches html_content; the Agent panel shows a "View HTML" shortcut and a cached-report banner on the empty state.
• Composable utilities. useMeetingAnalysis (packages/client/src/composables/useMeetingAnalysis.ts) extracts balanced JSON from agent output, escapes HTML, and detects analysis-shaped payloads. Covered by tests/client/useMeetingAnalysis.test.ts.

Reliability patch (v0.74.1):

• Broader HTML report extraction. useMeetingAgent.ts now pulls the AI-generated HTML from any of three sources — write_file (and similar) tool arguments, the matching tool result, or an assistant ```html code block (including blocks that only appear after concatenating multiple assistant messages). Falls back to the templated report only when none of the three contain a real HTML document. This stops the empty-state HTML viewer when the agent returns the report inline instead of writing a file.
• Reentry guards. sendMessage and runAgent short-circuit while a run is already in flight (isRunning flag), so duplicate clicks on the trigger no longer spawn a second concurrent agent run or fight over the isRunning state previously owned by the run callbacks.
• Aligned Python LLM accessor. meeting-asr/python-backend/app/llm_service.py switched from the deprecated storage.get_llm_config() to storage.get_config().llm, matching the storage refactor introduced in v0.74. Without this the ASR backend would raise on every analysis or HTML render once the legacy accessor was removed.

Transcript correction (v0.74.2):

• AI transcript correction. A new "Correct Transcript" action in the agent panel sends the current sentences to Hermes as an ASR proofreading task. The agent returns a JSON {index, original, corrected} array; the client applies the changes back into the active session and refreshes finalSentences. Implemented by correctTranscript() in useMeetingAgent.ts, surfaced as a button in MeetingAgentPanel.vue, and wired into the session store from MeetingView.vue (onAgentCorrectTranscript).
• Auto-close on completion. The panel now emits a completed event when an analysis run finishes; MeetingView.onAgentCompleted closes the panel if an HTML report was produced, so the report view takes over without an extra click.
• Locale strings. meeting.correctTranscript and meeting.correctTranscriptHint are added to the English and Chinese locale files. Other locales fall back to the English strings until translated.

ASR model picker & save-mode (v0.74.3):

• Per-meeting ASR model selection. The create-meeting dialog now exposes an ASR model picker with three options — paraformer-v2, fun-asr, fun-asr-mtl — each with a short description in both locales. The selected model is stored on MeetingSession.asrModel and forwarded to the ASR websocket as part of the runtime config.
• Save mode (diarize-only). A new saveMode toggle on MeetingView opens a dedicated diarize websocket instead of the live ASR stream. Audio is uploaded to the diarize backend and speaker labels come back asynchronously, which is enough for later analysis/HTML report generation and skips DashScope's per-second ASR billing for users on tight quotas.
• ASR-only branch. startRecording now splits the websocket setup into three explicit branches — saveMode (diarize-only), useDiarize (ASR + diarize side-by-side), and the new plain ASR-only path — so users who don't need speaker labels skip the diarize websocket entirely.
• Speaker rename sync. confirmRenameSpeaker now mirrors the updated speakerMap from the store back into the live MeetingView refs in addition to finalSentences, so a rename reflects immediately without a session reload.

Transcript correction hardening (v0.74.3):

• Robust correction extraction. extractCorrections() in useMeetingAnalysis.ts now validates every parsed item (index number + original/corrected strings) and tolerates three extra shapes the LLM occasionally emits: a bare JSON array, a corrections = [...] assignment-style line, and a JSON block wrapped in surrounding prose. Invalid payloads return null instead of a half-populated array.
• Stricter proofreading prompt. The correction prompt in useMeetingAgent.correctTranscript was rewritten to be explicit about the proofreading role and to forbid tool calls. A pinned instructions is now sent alongside the run so Hermes does not detour into web search or file writes mid-correction.
• Coverage. tests/client/extractCorrections.test.ts adds 6 cases covering the new shapes and the validation guard (16/16 green).

Agent panel polish (v0.74.4):

• Session-switch reload. MeetingAgentPanel.vue now watches sessionId and reloads messages, analysisResult, and reportHtml from the new session, plus resets isRunning / error / completed / correctedSentences. Previously the panel kept showing the previous meeting's conversation after the user switched sessions in MeetingView.
• Markdown rendering for assistant content. The plain-text <div class="assistant-content">{{ msg.content }}</div> is replaced with an async-loaded MarkdownRenderer so analysis output is rendered as actual Markdown (headings, lists, tables, code blocks) instead of escaped text.
• Smarter report prompt. useMeetingAgent.generateReport now passes a pinned instructions payload to Hermes, includes the session title, and folds in any prior analysisResult plus the previous assistant/system messages as ### Previous analysis result / ### Previous conversation blocks. This keeps a re-run of "Generate Report" idempotent instead of re-analyzing from scratch, and the strict instructions enforce the write_file + ```html code block contract that extractHtml looks for.
• Looser HTML detection. looksLikeHtmlDocument now also accepts <!DOCTYPE html> prefixes and drops the minimum-length threshold from 200 to 100 characters, so shorter ECharts-free reports are still recognized as full HTML documents.

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

npm (Recommended)

npm install -g @quanthermes/hermes-web-ui
hermes-web-ui start

Open http://localhost:8648

One-line Setup (Auto-detect OS)

Automatically installs Node.js (if missing) and hermes-web-ui on Debian/Ubuntu/macOS:

bash <(curl -fsSL https://raw.githubusercontent.com/EKKOLearnAI/hermes-web-ui/main/scripts/setup.sh)

WSL

bash <(curl -fsSL https://raw.githubusercontent.com/EKKOLearnAI/hermes-web-ui/main/scripts/setup.sh)
hermes-web-ui start

WSL uses the same Web UI daemon startup flow as other local installs; no separate gateway service is started by Web UI.

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.

Source Deployment Note

For Armbian / Ubuntu host-level source deployment, review docs/work-log.md before following deployment steps.

• The 2026-05-19 log records a real failure where Hermes was installed under root while hermes-web-ui.service ran as hermesui
• That mismatch caused the agent bridge to fail with run_agent.py not found, and chat requests then hit ENOENT /tmp/hermes-agent-bridge.sock
• After source deployment, verify that /home/hermesui/.local/bin/hermes belongs to hermesui rather than linking into /root/.local/...

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 itself. Provider API keys and Hermes Agent settings are managed separately through Hermes profiles.

CLI Commands

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

npm Release

• Publish package: @quanthermes/hermes-web-ui
• Install globally: npm install -g @quanthermes/hermes-web-ui
• Runtime command: hermes-web-ui start
• Release workflow: push a v* tag to trigger .github/workflows/npm-publish.yml
• Release runbook: docs/npm-release.md

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 browser on successful startup

Development

npm install
npm run dev

• Frontend: http://localhost:5173
• BFF Server: http://localhost:8648

npm run build   # outputs to dist/

See DEVELOPMENT.md for project development guidelines.

Architecture

Browser → BFF (Koa, :6060) → Socket.IO /chat-run ↓ ↓ 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](https://github.com/tangledup-ai/hermes-web-ui/blob/HEAD/LICENSE)

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.