Install Hermes WebUI in 2026: Step-by-Step Setup Guide

So you want a web UI for your Hermes Agent. Smart move.

I've been running Hermes in production since early 2025. The terminal is fine for quick queries, but once you start managing sessions, reviewing tool call results, or letting teammates poke the agent — you need a browser interface. Hermes WebUI delivers that without the bloat.

This guide covers every installation method I've tested in 2026: Docker, npm, and manual. I'll also walk through the gotchas that'll waste your time if you skip them. Let's get it running.

Prerequisites: What You Need Before Starting

Before you touch any install command, check these boxes:

• Hermes Agent v0.11+ — WebUI talks to the agent's API server. Run hermes --version. If it's lower than 0.11, update: hermes update. I've seen folks waste an hour debugging connection errors because they were on v0.9. Classic.
• Node.js 18+ (for npm method) — node --version. If you're below 18, grab the latest LTS from NodeSource or use nvm.
• Docker Engine 24+ (for Docker method) — docker --version. The compose file uses healthcheck and restart: unless-stopped, so you want a modern engine.
• SSH access to your server — You'll need to tunnel WebUI ports if you don't expose it publicly (which you shouldn't, unless you enjoy getting scanned).
• API keys for at least one LLM provider — Anthropic, OpenAI, OpenRouter, whatever. WebUI doesn't ship with a built-in model; it's a frontend for your Hermes agent, which needs a backend.

Last Tuesday, on my staging cluster, I skipped the Hermes version check. Spent 40 minutes wondering why the WebUI kept showing "Agent offline." The agent was running — just too old. Don't be me.

Method 1: Docker Install (Recommended)

This is my daily driver. Docker isolates dependencies, survives reboots, and makes upgrades trivial.

Step 1: Create the Docker Compose File

Create docker-compose.yml in a directory of your choice:

services:
  hermes-webui:
    image: ghcr.io/nesquena/hermes-webui:latest
    container_name: hermes-webui
    restart: unless-stopped
    volumes:
      - /home/youruser/.hermes:/root/.hermes
      - hermes-webui-state:/var/lib/hermes-webui
    environment:
      HERMES_HOME: /root/.hermes
      HERMES_WEBUI_STATE_DIR: /var/lib/hermes-webui
      HERMES_WEBUI_AUTH_MODE: basic
      HERMES_WEBUI_BIND_HOST: 127.0.0.1
      HERMES_WEBUI_BIND_PORT: 8780
    ports:
      - "127.0.0.1:8780:8780"
    mem_limit: 1g

volumes:
  hermes-webui-state:

A few notes from my battle scars:

• Bind to 127.0.0.1, not 0.0.0.0. The WebUI has no built-in TLS. Exposing it publicly without a reverse proxy is a footgun. Use SSH tunneling or put nginx/caddy in front.
• Volume mount your .hermes directory — This is where Hermes stores sessions, memory, and configs. Without it, WebUI won't see your agent's state.
• mem_limit: 1g — WebUI itself is lightweight, but Hermes agent can spike memory during heavy tool calls. 1GB is safe.

Step 2: Start the Container

docker compose up -d

Check logs:

docker compose logs -f

You should see something like:

Hermes WebUI starting on http://127.0.0.1:8780
WebUI is running

Step 3: Set Up SSH Tunnel

From your local machine:

ssh -L 8780:127.0.0.1:8780 user@your-server

Now open http://127.0.0.1:8780 in your browser. You'll see a login prompt if HERMES_WEBUI_AUTH_MODE is set to basic. Default credentials are admin / hermes — change those immediately.

Actionable alternative: Skip the entire Docker setup and try Try Hermes WebUI for a fully managed experience. No SSH tunnels, no volume mounts, just a browser tab.

Method 2: npm Install (For Local Dev or Lightweight Servers)

If you're on a machine without Docker, or you want to hack on the WebUI itself, npm is the way.

Step 1: Clone the Repo

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

Step 2: Install Dependencies

npm install

This pulls Prism.js, the SSE client, and a few utility libraries. Takes 60-180 seconds depending on your network. The classic trap — I fell into it in production: if you're behind a corporate proxy, npm install will fail silently on some packages. Set HTTP_PROXY and HTTPS_PROXY environment variables before running.

Step 3: Configure Environment

Copy the example env file:

cp .env.example .env

Edit .env:

HERMES_HOME=/home/youruser/.hermes
HERMES_WEBUI_STATE_DIR=/home/youruser/.hermes-webui
HERMES_WEBUI_AUTH_MODE=basic
HERMES_WEBUI_BIND_HOST=127.0.0.1
HERMES_WEBUI_BIND_PORT=8780

Step 4: Start the WebUI

npm start

Output:

Hermes WebUI running at http://127.0.0.1:8780

Open that URL. You should see the three-panel layout: sessions on the left, chat in the center, workspace file browser on the right.

Step 5 (Optional): Run as a Background Service

For production, you don't want npm start tied to your SSH session. Use pm2 or systemd:

npm install -g pm2
pm2 start npm --name "hermes-webui" -- start
pm2 save
pm2 startup

After two hours of debugging my YAML configs, I finally found the culprit for a missing pm2 startup — the WebUI would die on server reboot. Don't skip pm2 startup.

Method 3: Manual Install (For the Curious)

You want to see every file. I respect that.

Step 1: Download the Release

Grab the latest tarball from the GitHub releases page:

wget https://github.com/nesquena/hermes-webui/archive/refs/tags/v0.52.0.tar.gz
tar -xzf v0.52.0.tar.gz
cd hermes-webui-0.52.0

Step 2: Install Dependencies

Same as npm method — npm install.

Step 3: Set Up Hermes Agent API

WebUI relies on Hermes Agent's built-in API server. Ensure your .hermes/.env has:

API_SERVER_ENABLED=true
API_SERVER_HOST=127.0.0.1
API_SERVER_PORT=8781
API_SERVER_KEY=your-secret-key-here

Then restart Hermes: hermes restart.

Step 4: Configure WebUI to Connect

In the WebUI's .env, add:

HERMES_API_URL=http://127.0.0.1:8781
HERMES_API_KEY=your-secret-key-here

Step 5: Start

node server.js

Nope. That's not a typo — the manual method requires running the Node server directly. No build step, no bundler. The WebUI is vanilla JavaScript with zero framework overhead.

Configuration Deep Dive

Authentication Modes

I use basic with a strong password. If you need multi-user, put a reverse proxy with OAuth2-proxy in front.

Environment Variables Reference

Provider Configuration

WebUI supports multiple LLM backends. Add API keys in Settings > API Keys. The provider dropdown dynamically populates based on what you configure.

Common providers:

• Anthropic: Paste your Claude API key
• OpenAI: OpenAI API key
• OpenRouter: OpenRouter key (gives access to 200+ models)
• Ollama: Point at http://localhost:11434 (no key needed)

For a detailed walkthrough of provider-specific patterns, check my Hermes WebUI v0.51.247: How Reasoning Effort Coercion Improves AI Agent Performance post — it covers model selection quirks.

Troubleshooting Common Issues

"Agent Offline" Error

WebUI can't reach the Hermes API server. Check:

• Is Hermes running? hermes status
• Is API_SERVER_ENABLED=true in .hermes/.env?
• Port conflict? netstat -tulpn | grep 8781

Blank Screen on Load

Browser console shows SSE connection errors. Usually means:

• CORS misconfiguration — add ACCESS_CONTROL_ALLOW_ORIGIN=http://127.0.0.1:8780 to Hermes env
• WebUI is on HTTPS but Hermes API is HTTP (mixed content) — use a reverse proxy

Sessions Not Persisting

Check volume mounts. If you're on Docker and the hermes-webui-state volume is empty, WebUI can't save sessions. Run docker compose exec hermes-webui ls /var/lib/hermes-webui to verify.

Slow Streaming

SSE responses feel laggy? Check:

• Network latency between WebUI and Hermes API (keep them on the same host)
• Provider API rate limits — Anthropic free tier is slow
• Memory pressure — docker stats to see if you hit the 1GB limit

Architecture Overview

Here's how the components fit together:

Key insight: The WebUI is stateless for agent operations. All session logic lives in Hermes Agent. The WebUI just renders what the API returns. If the agent crashes, the WebUI shows a disconnected state, but your sessions survive.

Security Best Practices

1. Never expose WebUI directly to the internet — Use SSH tunneling or a reverse proxy with TLS
2. Change default credentials — admin / hermes is the first thing bots try
3. Use a dedicated API key — Don't reuse your provider API keys across services
4. Restrict SSH access — Only allow key-based auth, no passwords
5. Keep Hermes updated — hermes update weekly for security patches

For a deeper security discussion, see our Hermes WebUI v0.51.252: Selection Bleed Fix & Compatibility Guide.

Actionable alternative: If managing all this sounds tedious, Try Hermes WebUI handles security, updates, and uptime for you.

FAQ

How does Hermes WebUI compare to Open WebUI?

Hermes WebUI is designed specifically for Hermes Agent, offering 1:1 CLI parity and persistent memory, while Open WebUI is a general-purpose interface for various LLM backends. Hermes WebUI is lighter (no build step, no framework, no bundler) and focuses on the Hermes ecosystem. For a side-by-side comparison, read Hermes WebUI vs Open WebUI: Which AI Agent Interface Wins in 2025?.

What is the best webUI for Hermes?

Hermes WebUI is the official web interface for Hermes Agent, providing full CLI parity, persistent memory, and multi-provider support. It integrates seamlessly with the Hermes Agent setup.

Can I use Hermes WebUI on my phone?

Yes, Hermes WebUI is accessible from any browser, including mobile browsers, via an SSH tunnel. It is designed to be responsive and work on phones.

Is Hermes WebUI open source?

Yes, Hermes WebUI is open source under the MIT license, and the code is available on GitHub.

Do I need to install Hermes Agent separately?

Yes, Hermes WebUI is a frontend for Hermes Agent. The bootstrap script can detect and install Hermes Agent if missing.

What if the WebUI shows "Session not found" after a restart?

This happens when the Hermes agent's session store gets out of sync with WebUI's state. The fix is trivial: restart both services. docker compose restart or pm2 restart all. If it persists, delete the WebUI state directory (rm -rf /var/lib/hermes-webui/*) and restart. You won't lose agent sessions — those live in .hermes.