hermes-web-ui

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:

| 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 | | 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

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

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

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

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

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.

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. | |