Site icon Efficient Coder

Hermes Web UI: The Self-Hosted Browser Interface for Your AI Agent

高效码农

Hermes Web UI: The Browser Interface That Makes Hermes Agent Truly Practical

Have you ever wished your powerful AI agent felt as effortless to use as a regular chat app? You love the depth of Hermes Agent—its persistent memory, self-hosted scheduling, and ability to grow smarter over time—but switching between the terminal and your workflow can feel clunky. Hermes Web UI solves exactly that. It’s a lightweight, dark-themed web application that brings the full power of Hermes Agent straight into your browser.

Hermes Agent is an autonomous AI that runs on your own server. It remembers what it learns, handles cron jobs while you’re offline, and becomes more capable the longer it operates. The Web UI delivers 1:1 parity with the command-line experience. Everything you can do in the terminal, you can now do in a clean, three-panel layout that feels familiar if you’ve used Claude-style interfaces.

Left sidebar for sessions and tools, center chat area, right-side workspace file browser. No build steps, no heavy frameworks, no bundlers—just clean Python and vanilla JavaScript. The result is a fast, self-hosted interface that reuses your existing Hermes setup without any extra configuration.

Hermes Web UI — three-panel layout

Here’s the same interface in light mode, showing full profile support, session management, and inline file previews.

Light mode with full profile support

And this screenshot shows the settings panel where you can customize everything, including password protection.

Customize your settings, configure a password

Why Choose a Web Interface for Hermes Agent

Most AI tools treat every conversation like a fresh start. They don’t remember who you are, what projects you’re working on, or the conventions your team follows. You end up repeating the same context over and over.

Hermes Agent is different. It keeps context across sessions, runs scheduled tasks in the background, and learns your environment the longer it runs. The Web UI simply makes all of that accessible and visual. You still use your existing models, tools, and configuration—no new setup required.

Key advantages that set Hermes apart:

  • Persistent memory: user profiles, agent notes, and a skills system that saves reusable procedures so you never re-explain the same thing.
  • Self-hosted scheduling: cron jobs that run while you’re offline and deliver results to Telegram, Discord, Slack, Signal, email, and more.
  • Multi-platform access: the same agent is available in the terminal or via 10+ messaging apps on your phone.
  • Self-improving skills: the agent automatically writes and saves new skills based on experience—no marketplace, no plugins to install.
  • Provider-agnostic: works with OpenAI, Anthropic, Google, DeepSeek, OpenRouter, and others.
  • Orchestrates other agents: can delegate heavy tasks to Claude Code or similar tools and bring results back into its own memory.
  • Fully self-hosted: your conversations, memory, and data stay on your hardware.

For a quick side-by-side view, here’s how Hermes compares with similar tools (based on core capabilities):

Feature OpenClaw Claude Code Codex CLI OpenCode Hermes
Automatic persistent memory Yes Partial Partial Partial Yes
Self-hosted scheduled jobs Yes No No No Yes
Messaging app access Yes (15+ platforms) Partial No No Yes (10+)
Self-hosted web UI Dashboard only No No Yes Yes
Self-improving skills Partial No No No Yes
Native Python / ML ecosystem No (Node.js) No No No Yes
Provider-agnostic Yes No (Claude only) Yes Yes Yes
Open source Yes (MIT) No Yes Yes Yes

Hermes stands out for its automatic skill generation, update stability, and deep integration with the Python ecosystem. It gives you the best of both worlds: the power of a long-running autonomous agent and the convenience of a modern browser interface.

Quick Start: From Zero to Browser in Minutes

Before using the Web UI, you need Hermes Agent installed and configured. The steps are straightforward:

  • Run the curl command to download and set up Hermes.
  • Configure your LLM provider with hermes model.
  • Set up messaging gateways with hermes gateway setup (optional but recommended).
  • Start chatting in the terminal with hermes.
  • Optionally configure extended memory and tools.

Once Hermes Agent is ready, installing the Web UI takes one command:

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

The start.sh script handles everything automatically:

  1. Locates your existing Hermes Agent directory.
  2. Finds or creates the required Python environment.
  3. Starts the web server.
  4. Prints the local URL and, if you’re on a remote server, the SSH tunnel command.

That’s it—you can open the URL in your browser and start using the full three-panel interface immediately.

Docker Deployment: Clean and Portable

If you prefer containers, pre-built images for amd64 and arm64 are available on GitHub Container Registry:

docker pull ghcr.io/nesquena/hermes-webui:latest
docker run -d -p 8787:8787 -v ~/.hermes:/root/.hermes ghcr.io/nesquena/hermes-webui:latest

Docker Compose is even simpler (recommended):

docker compose up -d

Or build locally:

docker build -t hermes-webui .
docker run -d -p 8787:8787 -v ~/.hermes:/root/.hermes hermes-webui

To add password protection, just include the environment variable:

docker run -d -p 8787:8787 -e HERMES_WEBUI_PASSWORD=your-secret -v ~/.hermes:/root/.hermes ghcr.io/nesquena/hermes-webui:latest

Session data persists in a named volume called hermes-data. By default, Docker Compose binds to localhost only. To expose on your network, update the port mapping in docker-compose.yml and enable the password.

What start.sh Automatically Discovers

The script is designed to require almost no manual configuration. It intelligently finds:

Item How it finds it
Hermes Agent directory Environment variable first, then ~/.hermes/hermes-agent, then sibling ../hermes-agent
Python executable Agent’s venv, then repo’s .venv, then system python3
State directory HERMES_WEBUI_STATE_DIR or ~/.hermes/webui-mvp
Default workspace HERMES_WEBUI_DEFAULT_WORKSPACE or ~/workspace
Port HERMES_WEBUI_PORT or first command-line argument (default 8787)

If the automatic detection misses something, you can override with environment variables:

export HERMES_WEBUI_AGENT_DIR=/path/to/hermes-agent
export HERMES_WEBUI_PYTHON=/path/to/python
export HERMES_WEBUI_PORT=9000
./start.sh

Or in one line:

HERMES_WEBUI_AGENT_DIR=/custom/path ./start.sh 9000

Full list of supported environment variables includes HERMES_WEBUI_HOST, HERMES_WEBUI_STATE_DIR, HERMES_WEBUI_DEFAULT_MODEL, HERMES_WEBUI_PASSWORD, and several Hermes-specific paths for maximum flexibility.

Accessing the UI from a Remote Server

By default the server binds only to 127.0.0.1. If Hermes is running on a VPS, create an SSH tunnel from your local machine:

ssh -N -L <local-port>:127.0.0.1:<remote-port> <user>@<server-host>

Example:

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

Then open http://localhost:8787 in your browser. The start.sh script automatically prints the correct tunnel command when it detects an SSH environment.

Using Tailscale for Phone Access

Want to use the interface on your phone without port forwarding? Tailscale creates a zero-config private mesh network.

Steps:

  1. Install Tailscale on your server and phone.
  2. Start the Web UI listening on all interfaces with password protection:
HERMES_WEBUI_HOST=0.0.0.0 HERMES_WEBUI_PASSWORD=your-secret ./start.sh
  1. Open http://<server-tailscale-ip>:8787 in your phone’s browser.

The interface is fully responsive: hamburger sidebar on mobile, bottom navigation bar, touch-friendly controls, and a composer positioned above the nav. You can even add it to your home screen for an app-like experience. All traffic stays encrypted end-to-end.

Manual Launch Without the Script

Prefer direct control? Change to your Hermes Agent directory and run:

cd /path/to/hermes-agent
HERMES_WEBUI_PORT=8787 venv/bin/python /path/to/hermes-webui/server.py

Use the same Python environment that has Hermes dependencies installed. A simple health check confirms everything is running:

curl http://127.0.0.1:8787/health

Complete Feature Overview

Chat and Agent Interaction

  • Real-time streaming responses via Server-Sent Events (SSE)—tokens appear as they’re generated.
  • Dynamic model dropdown populated from your configured providers (OpenAI, Anthropic, Google, DeepSeek, etc.).
  • Queue new messages while one is still processing.
  • Inline editing of any past user message, then regenerate from that point.
  • One-click retry for the last assistant response.
  • Cancel running tasks directly from the activity bar.
  • Tool-call cards show name, arguments, and result snippets; toggle expand/collapse for all tools.
  • Sub-agent delegation cards with distinct styling.
  • Inline Mermaid diagram rendering (flowcharts, sequence diagrams, Gantt charts).
  • Collapsible gold-themed cards for extended thinking and reasoning blocks.
  • Approval workflow for dangerous shell commands (allow once, session, always, or deny).
  • Automatic SSE reconnection after network interruptions.
  • File attachments persist across page reloads.
  • Timestamps on every message (hover for full date).
  • Code-block copy buttons with “Copied!” feedback.
  • Prism.js syntax highlighting for Python, JavaScript, bash, JSON, SQL, and more.
  • Safe HTML rendering in AI responses.
  • Live context usage indicator showing token count, estimated cost, and fill bar.

Session Management

  • Create, rename, duplicate, delete, and search sessions by title or content.
  • Pin important sessions to the top (gold indicator).
  • Archive sessions without deleting them.
  • Color-coded projects to organize sessions.
  • Hashtag tags in titles become clickable colored chips for filtering.
  • Sidebar groups sessions by Today / Yesterday / Earlier (collapsible).
  • Export as Markdown transcript, full JSON, or import JSON files.
  • Browser tab title updates to match the active session.
  • CLI sessions from the agent’s SQLite store appear with a “cli” badge and can be imported with full history.

Workspace File Browser

  • Expandable directory tree (single-click toggle, double-click navigate).
  • Clickable breadcrumb navigation.
  • Inline previews for text, code, rendered Markdown, and images.
  • Create, edit, delete, and rename files and folders directly.
  • Automatic binary file download.
  • Git integration: branch name and dirty file count shown in the header.
  • Drag-to-resize right panel.
  • Unsaved changes guard when navigating away.

Voice Input

  • Microphone button in the composer (powered by Web Speech API).
  • Tap to record; tap again or send to stop.
  • Live interim transcription appears in the text area.
  • Auto-stops after ~2 seconds of silence.
  • Appends to existing text instead of replacing it.
  • Automatically hidden in browsers without Web Speech support.

Profiles

  • Top-bar profile picker with dropdown showing all profiles.
  • Gateway status indicators, model info, and skill count per profile.
  • Sidebar panel to create, switch, and delete profiles (clone config on creation).
  • Switching is instant—no server restart required.

Security and Themes

  • Optional password authentication (off by default for localhost).
  • Signed HMAC HTTP-only cookies with 24-hour expiry.
  • Security headers on every response.
  • Six built-in themes with instant switching and server-side persistence.
  • Custom themes supported by adding CSS custom properties.

Additional Panels and Commands

  • Tasks panel for managing cron jobs, history, and completion alerts.
  • Skills panel to browse, preview, create, edit, and delete skills.
  • Memory panel for inline editing of MEMORY.md and USER.md.
  • Todos panel showing live tasks from the current session.
  • Spaces for quick workspace switching.
  • Slash commands (/help, /model, /workspace, /usage, /theme, etc.) with autocomplete.

The entire UI is mobile-responsive with a slide-in sidebar, iOS-style bottom navigation, and minimum 44px touch targets.

Architecture Overview

The project keeps things simple and maintainable:

  • server.py handles HTTP routing and authentication.
  • api/ folder contains modules for auth, config discovery, session models, profiles, streaming, workspace operations, and more.
  • static/ contains the HTML template, CSS, and modular JavaScript files for UI, workspace, sessions, messages, and panels.
  • Over 430 tests run in an isolated environment so production data is never touched.

All state lives outside the repository in ~/.hermes/webui-mvp/ (easily overridden).

Documentation Included

The repository ships with clear guides:

  • HERMES.md for design philosophy and comparisons.
  • ROADMAP.md, ARCHITECTURE.md, TESTING.md, CHANGELOG.md, SPRINTS.md, and THEMES.md.

Frequently Asked Questions

How does Hermes Web UI relate to Hermes Agent?
It is the official browser interface for Hermes Agent. You get complete feature parity with the terminal while keeping all intelligence, memory, and tools exactly as you configured them.

Can I use it with Dockerized Hermes Agent?
Yes—simply mount the ~/.hermes volume into the Web UI container and they share the same configuration and state.

Is password protection required?
No for local use. Enable it with the HERMES_WEBUI_PASSWORD environment variable whenever you expose the service over a network or Tailscale.

Which models are supported?
Every model and provider already configured in your Hermes Agent appears automatically in the dropdown.

Does the file browser support real editing?
Yes—you can edit text and code files inline, save changes instantly, and see Git status live.

Is voice input extra work?
No setup needed. It uses the browser’s built-in Web Speech API and works in Chrome, Edge, Safari, and similar browsers.

Will my sessions survive page refreshes or tunnel drops?
Yes. Everything—sessions, settings, projects, tags—is persisted on the server.

How do I see token usage and costs?
Toggle it in Settings or type /usage in the composer. Each conversation shows input/output tokens and estimated cost.

How well does it work on mobile?
It was built with mobile in mind: slide-in panels, bottom navigation, and touch-optimized controls make it feel native.

Are there tests to ensure reliability?
Absolutely—433 tests across 23 files run against an isolated server and never touch your real data.

Hermes Web UI turns a powerful terminal-based autonomous agent into a polished, browser-first experience. Whether you’re at your desk or on your phone, you can manage persistent memory, scheduled jobs, skills, and file workspaces with the same convenience as a modern chat tool.

If you already have Hermes Agent running, try ./start.sh right now. Within minutes you’ll have a clean three-panel interface that finally makes long-running AI agents feel approachable and productive. Your conversations, your memory, your hardware—now just a browser tab away.

Exit mobile version