Hermes WebUI Master Guide

What Is Hermes WebUI? #

Hermes WebUI is a lightweight, dark-themed web application that provides a browser-based interface to the Hermes Agent. It delivers full 1:1 parity with the CLI experience - everything you can do from a terminal, you can do from this UI. Built with Python and vanilla JavaScript, it requires no build step, no framework, and no bundler.

Architecture #

Hermes WebUI is a single-process Python application that imports Hermes Agent modules directly - there is no HTTP communication between separate services.

Backend Structure

Frontend Structure

Quick Start #

Get Hermes WebUI running in under 2 minutes.

1. Clone the repository

   git clone https://github.com/nesquena/hermes-webui.git hermes-webui
   cd hermes-webui

2. Run the start script

   ./start.sh

   Installs dependencies, checks for Hermes Agent, starts server on http://localhost:8787.

3. Open in browser

   Navigate to http://localhost:8787. The onboarding wizard guides you through provider setup on first run.

Installation Methods #

git clone https://github.com/nesquena/hermes-webui.git hermes-webui
cd hermes-webui
./start.sh

docker pull ghcr.io/nesquena/hermes-webui:latest
docker run -d \
  -e WANTED_UID=$(id -u) -e WANTED_GID=$(id -g) \
  -v ~/.hermes:/home/hermeswebui/.hermes \
  -v ~/workspace:/workspace \
  -p 127.0.0.1:8787:8787 \
  ghcr.io/nesquena/hermes-webui:latest

git clone https://github.com/nesquena/hermes-webui.git
cd hermes-webui
mkdir -p ~/.hermes/webui-mvp
pip install -r requirements.txt
export HERMES_WEBUI_HOST=0.0.0.0
export HERMES_WEBUI_PORT=8787
python -m uvicorn api.main:app --host 0.0.0.0 --port 8787

Docker Setup #

Docker is the recommended deployment method for VPS. Three compose configurations:

Single-Container Setup

version: '3.8'
services:
  hermes-webui:
    image: ghcr.io/nesquena/hermes-webui:latest
    container_name: hermes-webui
    ports:
      - "127.0.0.1:8787:8787"
    volumes:
      - hermes-home:/home/hermeswebui/.hermes
      - ~/workspace:/workspace
    environment:
      - WANTED_UID=${UID:-1000}
      - WANTED_GID=${GID:-1000}
      - HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui-mvp
    restart: unless-stopped
volumes:
  hermes-home:

Quick start:

git clone https://github.com/nesquena/hermes-webui
cd hermes-webui
cp .env.docker.example .env
docker compose up -d

Two-Container Setup

Use when you run Hermes Agent separately (for Telegram/Discord/CLI) and want WebUI as an additional surface.

version: '3.8'
services:
  hermes-agent:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-agent
    volumes:
      - hermes-home:/root/.hermes
      - hermes-agent-src:/opt/hermes
    environment:
      - HERMES_HOME=/root/.hermes
    restart: unless-stopped
  hermes-webui:
    image: ghcr.io/nesquena/hermes-webui:latest
    container_name: hermes-webui
    depends_on:
      - hermes-agent
    ports:
      - "127.0.0.1:8787:8787"
    volumes:
      - hermes-home:/home/hermeswebui/.hermes
      - hermes-agent-src:/home/hermeswebui/.hermes/hermes-agent
      - ~/workspace:/workspace
    environment:
      - HERMES_WEBUI_HOST=0.0.0.0
      - HERMES_WEBUI_PORT=8787
      - HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui-mvp
      - WANTED_UID=${UID:-1000}
      - WANTED_GID=${GID:-1000}
    restart: unless-stopped
volumes:
  hermes-home:
  hermes-agent-src:

UID/GID Configuration

The container auto-detects your host user UID/GID. Set explicitly if needed:

id -u  # e.g., 1000
id -g  # e.g., 1000
# Set in .env: UID=1000, GID=1000

Bind-Mount Migration (Advanced)

volumes:
  hermes-home:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /home/youruser/.hermes

Requirements: Host directory must be readable by container UID. All containers sharing the volume must run as the SAME UID/GID. If host .env is mode 0640, set HERMES_SKIP_CHMOD=1.

Dependency Installation

At startup, the init script runs:

uv pip install /home/hermeswebui/.hermes/hermes-agent

This installs Hermes Agent and all dependencies into the WebUI Python environment on first boot. Takes 1-2 minutes.

Remote Access #

SSH Tunnel (Recommended)

Safest method. No ports exposed to the internet.

ssh -N -L 8787:127.0.0.1:8787 user@your-server.com

Then open http://localhost:8787. The start.sh script prints this command automatically when it detects SSH.

Tailscale / ZeroTier

1. Install Tailscale on VPS

   curl -fsSL https://tailscale.com/install.sh | sh
   sudo tailscale up

2. Install Tailscale on local machine

   curl -fsSL https://tailscale.com/install.sh | sh
   sudo tailscale up

3. Access via Tailscale IP

   http://<tailscale-ip>:8787

Direct Network Exposure

# In docker-compose.yml:
ports:
  - "8787:8787"
environment:
  - HERMES_WEBUI_PASSWORD=your-strong-password

Reverse Proxy (Caddy)

hermes-webui.yourdomain.com {
    reverse_proxy localhost:8787
}

Caddy auto-provisions Let's Encrypt certificates.

Onboarding Behind Reverse Proxy

If behind nginx/Caddy/Traefik or SSH tunnel, the onboarding IP check may block you. Fixed in v0.50.22+. For older versions:

# Option 1: Set env var
HERMES_WEBUI_ONBOARDING_OPEN=1
# Option 2: Set password before first run
HERMES_WEBUI_PASSWORD=your-password
# Option 3: Upgrade to v0.50.22+

Chat and Streaming #

The chat interface is the core of Hermes WebUI. Every CLI workflow has a web equivalent.

Sending Messages

Type in the composer and press Enter. Messages are sent via SSE (Server-Sent Events) for real-time streaming.

Streaming Behavior

• rAF-throttled rendering: Token rendering throttled via requestAnimationFrame to prevent UI jank
• SSE auto-reconnect: If connection drops (common with SSH tunnels), stream automatically reconnects
• Send while streaming: Queue next message while agent responds - sent inline after current response

Model Selection

The composer footer includes a model picker showing all providers from your config.yaml:

• Multi-provider: OpenAI, Anthropic, Google, OpenRouter, xAI, GLM, DeepSeek, Mistral, MiniMax, Kimi, Nous Portal, custom OpenAI-compatible
• Dynamic discovery: Ollama, LM Studio, vLLM models discovered live via /v1/models
• Free-form OpenRouter: Type any model name with autocomplete
• Per-conversation: Each session can use a different model
• LM Studio first-class: Dedicated provider with live discovery even without env vars injected

Reasoning Display

• Claude thinking blocks: Rendered inline with expand/collapse
• o3 reasoning blocks: Distinct styling
• Reasoning effort selector: low/medium/high + /reasoning command

Rich Content Rendering

• Markdown: Full CommonMark with GFM extensions
• Code blocks: Prism.js syntax highlighting (Python, JS, bash, JSON, SQL, etc.). Copy button with "Copied!" feedback
• Mermaid diagrams: Rendered inline from ```mermaid blocks
• KaTeX math: Inline $...$ and block $$...$$ rendering

Cancel and Retry

• Stop button: Cancel streaming at any time
• Retry: Delete last assistant message and resend with one click

Context Usage Indicator

Circular ring badge in composer footer shows input tokens, output tokens, estimated cost, and context fill percentage. Toggleable in Settings or via /usage.

File Attachments

• Drag-and-drop or click to attach
• Persist across page reloads
• Images displayed inline

Session Management #

Basic Operations

• Create: Click "+" in sidebar or use /new
• Rename: Double-click title (Escape cancels) or use ... dropdown
• Delete: Use ... dropdown - Delete
• Duplicate: Fork a session to create a new branch with same history
• LLM-generated titles: First message triggers automatic title generation

Organization

Tags

Add #tag to session titles for colored chips. Click chips to filter. Tags extracted automatically from title text.

Projects

Named folders with colors. Sessions assigned to projects via ... dropdown. Sidebar shows chip filter bar including "Unassigned" filter.

Date Grouping

Grouped by: Today, Yesterday, Last Week, Last Month, Earlier. Collapsible groups.

Pin and Archive

Star sessions to pin to top. Archive sessions to hide from main list; "Show N archived" toggle reveals them.

Search

• Title search: Filter by title in sidebar search box
• Content search: Full-text search across all session messages

Batch Operations

Multi-select sessions, then bulk delete, move to project, or archive.

Import/Export

• Export JSON: Full messages + metadata
• Import JSON: Restore sessions from export
• Download Markdown: Transcript for sharing or archiving

CLI Session Bridge

Unique to Hermes WebUI: CLI sessions from hermes-agent SQLite store appear in sidebar with gold "cli" badge. Click to import with full history, then reply normally.

Subagent Session Tree

Sessions with parent_session_id grouped under parent in sidebar with expand/collapse chevrons and child count badges. Collapse state persists in localStorage.

Per-Session Configuration

• Per-session profile: Different model profile per session
• Per-session toolset: Override tools via /toolsets
• Per-session model: Composer-scoped model picker

Session Navigation

Opt-in in Appearance settings:

• Jump buttons: Sticky "Start" pill (loads full history) and "End" pill
• Endless scroll: Auto-prefetches older transcript with 1.5x viewport prefetch
• Viewport preservation: Loading older history anchors at current viewport

Sessions persist across page reloads and SSH tunnel disconnections. Browser tab title reflects active session name.

Workspace and File Browser #

File Tree

• Directory tree: Expandable/collapsible folders
• Drag-resizable panel: Resize by dragging edge
• Git detection: Branch name in header, dirty file count badge

File Preview

• Text/Code: Syntax-highlighted (Prism.js) - Python, JS, bash, JSON, SQL
• Markdown: Rendered preview
• Images: Inline preview
• Binary files: Auto-detected from MIME type, downloadable

File Operations

• Create: New file or folder from toolbar
• Edit: Inline editing with unsaved-change guard
• Delete/Rename: Files and folders
• Download: Any file to local machine

Workspace Allowlist

Paths validated against workspaces.json. _resolve_workspace prevents directory traversal attacks.

Auto-Close

File preview auto-closes on directory navigation, with unsaved-edit guard.

Profiles and Models #

Profiles are named configurations bundling model selection, provider settings, and agent behavior.

Profile Management

• Create: Define named profiles with model/provider combinations
• Clone: Clone config from existing profile
• Edit/Delete: Modify or remove profiles

Provider Configuration

• Provider: OpenRouter, Anthropic, OpenAI, Google, or custom
• Custom endpoint: Base URL, API key, model name
• API key: Written into config.yaml at creation

Seamless Switching

No server restart needed. WebUI tracks which profile each session uses. Each session records which profile was used.

Tools and Command Approval #

Tool Call Cards

• Tool name: Displayed prominently
• Arguments: Expandable section
• Result snippet: Preview of output
• Expand/collapse all: Toggle for multi-tool turns

Command Approval

When agent attempts dangerous shell commands, an approval card appears:

• Allow once: Single execution
• Allow for session: All similar commands this session
• Allow always: Permanently allow this pattern
• Deny: Block execution

Approval polling is SSE-pushed - card updates in real-time.

Hermes Detection

Hermes detects destructive commands (rm -rf, drop table, etc.) and requires approval. Default is fail-closed - if unsure, it stops.

Sandbox Backends

Six sandbox backends: Docker, SSH, Singularity, Modal, and more. Configured via config.yaml.

Slash Commands #

Type / in the composer for autocomplete picker.

Skills and Memory #

Skills System

Hermes Agent has a self-improving skills system that auto-generates reusable skills from complex tasks. WebUI provides full CRUD:

• Browse: View all skills in Control Center
• Create/Edit/Delete: Full skill management

Skills stored as markdown in ~/.hermes/skills/, directly editable.

Memory System

Hermes retains context across sessions via:

• User profile: Persistent preferences and identity
• Agent notes: Manually written or auto-generated notes
• Self-improving skills: Skills that evolve from experience

Memory files stored in ~/.hermes/memory/ as editable markdown. WebUI provides memory write surface in Control Center.

Cron and Scheduled Jobs #

Self-hosted scheduling that fires while you are offline and delivers results to multiple platforms.

Creating Cron Jobs

• CRUD: Create, view, switch, edit, delete from Control Center
• Cron expressions: Standard cron syntax
• Delivery targets: Telegram, Discord, Slack, Signal, email, and more

How It Works

Cron jobs managed by Hermes Agent scheduler. Execution happens in the agent process. Jobs fire even when WebUI is closed, as long as agent is running.

Use Cases

• Daily data aggregation and report generation
• Weekly file organization and cleanup
• Scheduled reminders and notifications
• Periodic web scraping and data collection

MCP Integration #

Model Context Protocol allows Hermes Agent to use external tools and services.

MCP Server UI

• View MCP servers: See configured servers and status
• Configure: Add, edit, remove MCP server configurations
• Tool discovery: MCP tools appear alongside native Hermes tools

MCP server rewritten in v0.51.28 for better reliability, tool discovery, error handling, and connection management.

Subagents and Delegation #

Subagent Delegation Cards

• Distinct icon: Child agent tasks shown with unique icon
• Streaming display: Real-time progress of subagent execution
• Status tracking: See when subagents start, complete, or fail

Session Tree

Sessions spawned by subagents linked via parent_session_id:

• Expand/collapse chevrons: Show/hide child sessions
• Child count badges: See how many children a parent has
• localStorage persistence: Collapse state survives page reload

Insights and Analytics #

Usage analytics across all sessions.

Overview Cards

• Token total: Aggregate input + output tokens
• Cost total: Estimated spending
• Session count: Total conversations in period
• Active days: Days with activity

Model Usage Table

Breakdown by model: name, sessions, tokens, cost.

Top Tools

Ranked list with usage bars.

Activity Heatmap

• Day-of-week bars: Activity by Mon-Sun
• Top hours: When you are most active

Notable Sessions

Links to actual sessions - click to load in chat view.

Days Selector

Filter by 7 / 30 / 90 / All days.

Backend

GET /api/insights?days=30 instantiates InsightsEngine from agent/insights.py. Capped at 365 days. Guarded by sync_to_insights setting.

Rollback and Checkpoints #

Hermes Agent maintains workspace checkpoints via shadow git repos.

Checkpoint List

View all checkpoints in workspace detail panel with timestamp and description.

Diff Viewer

Modal diff viewer shows changes between current state and any checkpoint. Syntax-highlighted, side-by-side.

Restore

Restore with confirmation dialog. Reads shadow git repos directly.

API Endpoints

• GET /api/rollback/list - List all checkpoints
• GET /api/rollback/diff - Get diff for a checkpoint
• POST /api/rollback/restore - Restore to a checkpoint

Voice Mode #

Turn-based voice interaction using browser Web Speech API.

1. Activate: Click voice button in composer
2. Speak: Browser captures audio via Web Speech API (STT)
3. Send: Transcribed text sent as message
4. Listen: Agent response read aloud via TTS
5. Loop: Auto-resumes listening after response completes

Features

• Progressive enhancement: Hidden if Web Speech API unsupported
• Pulsing indicator: Visual feedback when listening
• TTS settings: Respects existing voice/rate/pitch config
• Error handling: Bail-out on not-allowed and audio-capture errors with toast

Git Worktrees #

Create isolated git worktrees for sessions, enabling parallel development branches.

Creating Worktree Sessions

POST /api/session/new accepts worktree: true flag:

• Creates isolated worktree at <repo>/.worktrees/<session>-XXXX
• Persists worktree_path, worktree_branch, worktree_root, worktree_commit
• Worktree indicator shown in sidebar

Worktree Behavior

• Empty worktree sessions stay visible in sidebar
• Filter at /worktrees/ to see uncommitted edits
• Default branch is master

Internationalization and Themes #

Supported Languages

Themes

9 built-in themes, switchable via Settings or /theme:

Security and Authentication #

Password Authentication

HERMES_WEBUI_PASSWORD=your-secret-password

Uses signed HMAC HTTP-only cookies. Cookie not accessible via JavaScript, preventing XSS session hijacking.

Rate Limiting

Login rate limiting persists across restarts. Failed attempts stored in STATE_DIR/.login_attempts with atomic writes and 0600 permissions. Buckets prune on load.

Security Headers

All responses include security headers. CDN resources SRI-pinned to prevent supply chain attacks.

API Redaction

API keys redacted by default. Self-hosted users can disable via Settings toggle. Lazy check at call-time, default ON for safety.

Workspace Allowlist

Paths validated against workspaces.json. Directory traversal prevented by _resolve_workspace.

Offline Recovery

When browser cannot reach Hermes, high-contrast offline banner appears. App probes /health automatically and refreshes on reconnection. Stream errors deferred while offline.

PWA Security

Service-worker shell assets use network-first strategy (with cache fallback). PWA install + offline launch preserved via install-time pre-caching.

PWA and Mobile #

Mobile Experience

Designed mobile-first:

• Hamburger sidebar: Collapsible navigation on small screens
• Touch-friendly targets: 44px minimum touch targets
• Full-height chat: Chat takes full viewport on phones
• Slide-overs: Panels slide over content on mobile
• Responsive breakpoints: Works at all screen sizes

Tailscale Access

Access via Tailscale for native app-like mobile experience. No port forwarding, no public exposure.

PWA Features

• Service worker: Network-first caching for shell assets
• Offline recovery: Banner + auto-reconnect
• Install prompt: Add to home screen on supported browsers
• Stream error deferral: Brief network drops do not surface terminal errors

Environment Variables #

API Reference #

Sessions

Chat

Workspace

Other Endpoints

Troubleshooting #

Onboarding blocked behind reverse proxy

Fix: Upgrade to v0.50.22+, or set HERMES_WEBUI_ONBOARDING_OPEN=1, or set HERMES_WEBUI_PASSWORD before first run.

Container permission issues

Fix: Set WANTED_UID and WANTED_GID to match host user. Use id -u and id -g.

Agent dependencies not installed

Fix: Check hermes-agent-src volume is mounted correctly. Check container logs for uv pip install output.

SSH tunnel connection drops

Fix: SSE auto-reconnect handles this. Add ServerAliveInterval 60 to SSH config if persistent.

Docker port binding - cannot access from other machines

Fix: Change port to "8787:8787" in docker-compose.yml and set HERMES_WEBUI_PASSWORD.

Two-container agent resolution

Fix: Use named volumes from docker-compose.two-container.yml. Do not replace with bind mounts.

Podman compatibility

Fix: Upgrade to Podman 4+, or use single-container setup, or use community image sunnysktsang/hermes-suite.

Workspace not in allowlist

Fix: Ensure workspace path is in workspaces.json.

Offline banner will not disappear

Fix: Check network connection and that Hermes server is running. Banner appears when navigator.onLine === false or /health probe fails.

Stream errors on page load

Fix: Normal if previous session was streaming when page closed. Click different session and back, or refresh.

Frequently Asked Questions #

General

Deployment

Chat and Models

Sessions

Workspace and Files

Profiles and Skills

Cron and Scheduling

Security

Mobile and PWA

Advanced