Hermes WebUI: a browser front end for the Hermes Agent you already run

The gap Hermes WebUI fills, and who hits it

Hermes Agent is described in the README as an autonomous agent that lives on your server, is reached through a terminal or messaging apps, remembers what it learns and gets more capable the longer it runs. That description already contains the problem. The agent is persistent, but the terminal is not. A long-running agent that accumulates skills and scheduled jobs is awkward to drive from a shell session you close when you shut the laptop.

Hermes WebUI is the browser layer over that agent. It is a Python server plus vanilla JavaScript, dark themed by default, arranged in three panels: sessions and navigation on the left, chat in the center, workspace file browsing on the right. Model, profile and workspace controls sit in the composer footer, so they stay visible while you type, and a circular context ring reports token usage. Everything else lives in a control center launched from the bottom of the sidebar.

The audience is narrow and specific. You need a Hermes Agent already installed and reachable, because the README states the interface uses your existing agent and existing models without additional setup. If you have that, the WebUI is a convenience layer with a real payoff: the same agent, the same memory, reachable from a phone or a second machine. If you do not have that, there is nothing here for you yet.

What actually runs when you open the page

The repository is a flat Python runtime. server.py is the entry point, api/ holds the backend package, static/ holds the front end, and mcp_server.py provides an MCP surface. The README claims full parity with the CLI, meaning anything you can do from a terminal you can do from the UI. That parity is the design constraint that explains the layout: sessions, workspace files and model selection are not features bolted onto a chat box, they are the CLI's concepts given a visual form.

There is no build step, no framework and no bundler. package.json is explicit that the Node tooling is dev-only, a single ESLint dependency used as a runtime-error guard over static/*.js. That guard exists because of a class of bug the project calls brick-class, citing a const-reassignment case that node --check and source-presence tests miss. For an operator this matters in a practical way: there is no compile stage to fail, no node_modules to install on the server, and no bundler version to pin. The cost is that the front end has no type system, which is why the lint gate exists at all.

State lives under ~/.hermes. The ctl.sh launcher writes a PID to ~/.hermes/webui.pid and logs to ~/.hermes/webui.log. Python dependencies are deliberately thin: pyyaml and cryptography for optional local passkey and WebAuthn support. The comment in requirements.txt is blunt that all heavy ML and agent dependencies live in the Hermes agent virtual environment, not here. Voice, system metrics and Office document preview are optional installs that return 503 with an install hint when absent rather than failing at startup.

Installing Hermes WebUI and getting to a first chat

The README gives three launch surfaces. The bootstrap path is the shortest. Clone the repository, enter it, and run the bootstrap script, which handles dependency discovery and then launches the server.

# from the README quick start
git clone https://github.com/nesquena/hermes-webui.git hermes-webui
cd hermes-webui
python3 bootstrap.py

That runs in the foreground, so the terminal stays occupied and Ctrl-C is the stop path. For a server you intend to leave running, ctl.sh wraps the daemon lifecycle and is the only launcher that writes a PID file.

./ctl.sh start              # background daemon, PID at ~/.hermes/webui.pid
./ctl.sh status             # PID, uptime, bound host/port, log path, /health
./ctl.sh logs --lines 100   # tail ~/.hermes/webui.log
./ctl.sh restart
./ctl.sh stop

ctl.sh start runs the bootstrap in foreground and no-browser mode behind the daemon wrapper, reads .env, and accepts inline overrides. The README shows the host override directly on the command line, which is how you expose the interface beyond localhost.

HERMES_WEBUI_HOST=0.0.0.0 ./ctl.sh start

For a container install, the single-container Compose file is described as the simplest setup: one WebUI container that runs the agent in process. Copy .env.docker.example to .env, edit values, then bring it up and open the printed address.

docker compose up -d
# then open http://localhost:8787

The Compose file binds 127.0.0.1:8787:8787 by default and comments that the alternative 8787:8787 line exposes the port more widely. It mounts ${HERMES_HOME:-${HOME}/.hermes} into the container and passes WANTED_UID and WANTED_GID, defaulting to 1000. On macOS the file warns that UIDs start at 501, so you set them in .env or the container may not read your mounted files. That is the first thing to check if the container starts but the workspace pane looks empty.

Stopping the server is harder than starting it

This is the sharpest operational limitation in the README, and it gets its own callout. Each launch method has a different stop path because only ctl.sh start writes a PID file. bootstrap.py runs in the foreground and stops on Ctrl-C. ctl.sh start stops with ctl.sh stop, which sends SIGTERM, waits, then SIGKILL. A detached bootstrap.py without the foreground flag, or start.sh, has neither: the README tells you to find the process with lsof -i :8787 or ss -tlnp and kill it yourself. It states plainly that ctl.sh stop cannot stop a server launched by bootstrap.py or start.sh, because it only manages processes it started.

That is a real design trade-off, not a documentation gap. A supervisor that tracks only its own children is simpler and avoids killing an unrelated process that happens to hold the port, but it means the stop command depends on remembering how you started. If you run this on a shared host where port 8787 is contested, the failure mode is a stale server you cannot address with the tool the project gave you.

The second limitation is dependency shape. The WebUI is a client. Without a reachable Hermes Agent behind it, there is no model to select and no memory to load. The README frames this as a feature, no additional setup required, and for the intended user it is. For anyone arriving from a search for a self-hosted chat interface, it is the thing that decides whether the project fits.

Hermes WebUI compared with Open WebUI and with the agent's own surfaces

The README positions Hermes WebUI against agentic tools rather than against chat front ends. Its own comparison table lists OpenClaw, Claude Code, Codex CLI and OpenCode, and names OpenClaw as the closest competitor: both always-on, self-hosted, open source, with memory, cron and messaging. The stated differences are that Hermes writes and saves its own skills automatically while OpenClaw's skill system centers on a community marketplace, that Hermes is described as more stable across updates, and that Hermes runs natively in the Python ecosystem.

A more useful comparison for most readers is against Open WebUI, which is the phrase people actually search alongside this project. The architectural difference is straightforward. Open WebUI is a general chat front end for model backends; Hermes WebUI is a front end for one specific agent, and its panels mirror that agent's concepts: sessions, workspace files, profiles, skills, scheduled jobs. You cannot point Hermes WebUI at an arbitrary OpenAI-compatible endpoint and get a working product, because the thing it talks to is Hermes Agent. Provider-agnosticism here means the agent supports OpenAI, Anthropic, Google, DeepSeek and OpenRouter, not that the WebUI does.

The README also distinguishes the WebUI from the agent's messaging surfaces. Ten or more messaging platforms are listed as a way to reach the same agent from a phone, and the WebUI is a separate route to the same place. Whether you want a browser session with a file browser and a token ring, or a Telegram thread, depends on whether you are doing focused work or firing off a request.

Deployment paths, licence and the cost of keeping up

Beyond bootstrap and Docker, the repository ships a Nix flake and NixOS module for declarative install and service management, plus docker-compose.two-container.yml and docker-compose.three-container.yml for setups that separate the agent, the WebUI and a dashboard into distinct containers. The single-container file is the documented starting point; the multi-container files exist for people who want the agent's lifecycle managed independently of the interface.

The licence is MIT, declared in both LICENSE and pyproject.toml, and the README's comparison table lists Hermes as open source under MIT. That permits commercial and private use and modification. It also means no warranty and no support obligation, which is worth stating plainly rather than as a legal caveat: the project's maintenance is whatever the repository shows. The last push was on 2026-08-26, and the most recent release at that date was exp-v0.52.264, with two more in the preceding four days. The exp- prefix on every release tag is a signal in itself. These read as experimental builds, and the version number moving several times a week suggests you should expect to pull often rather than pin and forget.

Upgrade cost is therefore mostly about the agent, not the interface. Because the WebUI has no build step, updating is a git pull and a restart, and ctl.sh restart exists for exactly that. The risk sits in the coupling: if the WebUI's API expectations move with the agent's, a version mismatch surfaces at runtime. The repository carries AGENTS.md, ARCHITECTURE.md, DESIGN.md and a docs directory, so the interfaces are documented, but nothing here describes a compatibility matrix between WebUI and agent versions.

Where Hermes WebUI is the wrong choice

If you want a chat interface for a model API you already pay for, and you have no Hermes Agent, this is the wrong tool. The README's own framing makes the interface dependent on the agent, and the requirements file confirms the heavy agent dependencies live elsewhere. You would be installing a UI for a program you do not run.

If you need a hardened multi-tenant deployment, nothing here supports that claim. There is passkey and WebAuthn support through cryptography, a password setting shown in the README's screenshots, and Docker port binding that defaults to 127.0.0.1, but nothing describes user accounts, role separation or audit logging. The README's own access story leans on an SSH tunnel from your Hermes setup, which tells you the intended trust model is one operator on a private network.

If you cannot tolerate weekly version churn, the release cadence is the deciding fact. Three exp-tagged releases in four days is a project moving fast, and fast movement in a client that depends on a separate agent's API is a maintenance commitment, not a one-time install.

Editorial conclusion

Adopt Hermes WebUI if you already run Hermes Agent on a server and want the same sessions, models and skills reachable from a laptop or phone without touching the terminal. Do not adopt it as a standalone chat product: the README is explicit that it uses your existing Hermes agent and existing models, so a fresh install with no agent behind it gives you a shell with nothing to talk to. Before committing, verify that your Hermes Agent version matches what the WebUI expects, that port 8787 is free or overridden, and that your chosen launch path has a working stop command, because ctl.sh stop only manages processes ctl.sh started.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes