Hermes WebUI Docker Setup Guide 2026: One-Click AI Chat UI

I've been running Hermes WebUI in Docker since the early v0.2 releases. The setup is deceptively simple — until it isn't. Let me walk you through the exact process that works in 2026, including the gotchas that'll waste your evening if you skip them.

Why Docker for Hermes WebUI?

Hermes WebUI is a lightweight Python web app that wraps the Hermes Agent CLI into a browser interface. It gives you streaming chat, session management, workspace file browsing — the whole deal. But running it bare-metal means dealing with Python venvs, port conflicts, and environment drift.

Docker solves that. One container, all dependencies pinned, no "works on my machine" nonsense.

The classic trap — I fell into it in production last month. I ran sudo docker compose up -d without checking the volume mounts. The container started, but my ~/.hermes directory was owned by root. The agent couldn't write to its own state. That broke everything. We'll fix that below.

Prerequisites

Before we start, you need:

• A VPS or local machine running Linux (Ubuntu 22.04+ recommended)
• Docker and Docker Compose v2 installed
• Hermes Agent already configured (WebUI is just the frontend)
• An SSH key for remote access (we'll lock down the port)

If you haven't installed Hermes Agent yet, check our Install Hermes WebUI in 2026: Step-by-Step Setup Guide first.

Step 1: Clone the Repo (or Just Grab the Compose File)

You don't need the full repo. The Docker image is published at ghcr.io/nesquena/hermes-webui:latest. But the Compose file from the repo saves you from writing one yourself.

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

Or just curl the docker-compose.yml:

mkdir ~/hermes-webui && cd ~/hermes-webui
curl -O https://raw.githubusercontent.com/nesquena/hermes-webui/main/docker-compose.yml

Step 2: Configure the Environment

Copy the example env file:

cp .env.example .env

Edit .env to set your paths and password:

HERMES_HOME=/home/youruser/.hermes
HERMES_WORKSPACE=/home/youruser/workspace
HERMES_WEBUI_PASSWORD=your-strong-password-here

Password protection is required if you expose the port outside 127.0.0.1. Don't skip this. I learned the hard way — my test instance was open for 30 minutes before someone from a random IP hit the / endpoint. The logs showed a bot scraping for open WebUIs.

Step 3: Run Docker Compose (Without sudo Pitfalls)

Here's where most people trip up. Running sudo docker compose up -d changes ${HOME} to /root. Docker then mounts /root/.hermes instead of your real ~/.hermes. The WebUI starts, but it can't find your config. You'll see this in the logs:

config.yaml (not found, using defaults)

Nope. That's a lie. The file exists — it's just mounted in the wrong place.

Fix: Add your user to the Docker group and run without sudo:

sudo usermod -aG docker $USER
# Log out and back in, then:
docker compose up -d

If you absolutely must use sudo (corporate laptops, weird setups), use absolute paths and the -E flag:

HERMES_HOME=/home/youruser/.hermes HERMES_WORKSPACE=/home/youruser/workspace sudo -E docker compose up -d

Then verify the mounts:

docker compose config | grep -A5 volumes

Step 4: Verify It's Running

Check the container logs:

docker compose logs -f

You should see something like:

hermes-webui  | INFO:     Started server process [1]
hermes-webui  | INFO:     Waiting for application startup.
hermes-webui  | INFO:     Application startup complete.
hermes-webui  | INFO:     Uvicorn running on http://0.0.0.0:8787

If you see Permission denied errors, it's the volume ownership issue from Step 3. Stop the container, fix the mount paths, and restart.

Step 5: Access Locally (SSH Tunnel)

By default, the container binds to 127.0.0.1:8787. That's safe — no external access. But you need a tunnel to reach it from your browser.

From your local machine:

ssh -L 8787:localhost:8787 youruser@your-vps-ip

Open http://localhost:8787 in your browser. You'll see the login screen (if you set a password) or the chat interface directly.

Actionable alternative: Skip the SSH tunnel hassle and use Try Hermes WebUI for a fully managed experience with HTTPS and auto-updates.

Architecture Overview

Here's how the pieces fit together:

The container mounts your Hermes data directory and workspace. It talks to the Hermes Agent process (which you need running separately) via its internal API. The agent then calls your configured LLM provider.

Common Pitfalls and Fixes

I've collected these from my own deployments and community reports. Save yourself the debugging time.

Pitfall 1: Volume Ownership Mismatch

The container runs as hermeswebui (UID 1000). If your host user has a different UID, files written by the container will be owned by 1000:1000 on the host. You won't be able to read them without sudo.

Fix: The container auto-detects your UID/GID from the mounted ~/.hermes volume. But if that fails, set them explicitly in .env:

WANTED_UID=1001
WANTED_GID=1001

Pitfall 2: Port Conflict on 8787

Already running something on 8787? Change the host port:

# In docker-compose.yml
ports:
  - "127.0.0.1:8788:8787"

Then tunnel to 8788 instead.

Pitfall 3: Agent Not Running

Hermes WebUI is just a frontend. The Hermes Agent process must be running separately. If you see "Agent not reachable" in the WebUI, start the agent:

hermes start

Or run it in a systemd service. For a complete walkthrough, see our detailed deployment guide.

Pitfall 4: Password Not Working

If you set HERMES_WEBUI_PASSWORD after the first run, you need to recreate the container:

docker compose up -d --force-recreate

Just restarting won't pick up the new env variable.

Remote Access with HTTPS (Production Setup)

Exposing port 8787 directly to the internet is a bad idea. Even with password protection, the traffic is plain HTTP. Anyone on the same network can sniff your session.

Better approach: Put a reverse proxy in front. Here's a minimal Caddyfile:

your-domain.com {
    reverse_proxy localhost:8787
}

Then run Caddy in a separate container or on the host. It handles TLS termination automatically via Let's Encrypt.

Even better: Use an SSH tunnel from your phone or laptop. No open ports, no certificates, no headache.

Comparison: Docker vs Bare-Metal vs Managed

If you're not comfortable managing a VPS and Docker, the managed option saves you from all this. Try Hermes WebUI handles deployment, SSL, and updates so you just use the chat.

Performance Tuning

Hermes WebUI is lightweight. The container uses about 50MB RAM at idle. But a few things can slow it down:

• Large workspaces: The file browser scans the workspace directory. Keep it under a few thousand files.
• Many sessions: The session list loads all sessions. Archive old ones regularly.
• Slow LLM providers: Streaming latency is provider-bound, not WebUI-bound.

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.

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.

Final Thoughts

Docker is the fastest way to get Hermes WebUI running, but the devil's in the volume mounts and user permissions. Follow the steps above, and you'll have a working AI chat UI in under 10 minutes.

For a more feature-rich comparison, check out our Hermes WebUI vs Open WebUI: 2026 Comparison Guide.

Actionable alternative: If Docker isn't your thing, Try Hermes WebUI for a one-click deploy that skips all this configuration.