Hermes WebUI: A Browser Front End for the Hermes Agent, With Caveats

What Hermes WebUI Actually Is

Hermes WebUI is not an agent. It is a web app that talks to an existing Hermes Agent installation. The README states it is a lightweight, dark-themed interface that gives nearly 1:1 parity with the Hermes CLI. The target user is someone who already runs Hermes Agent on a server and wants to reach it from a browser or a phone without opening a terminal. The project solves a specific problem: terminal-only access to a persistent, self-hosted agent. It does not add new agent capabilities. It reuses your existing models and your existing Hermes setup, which the README stresses requires no additional configuration. That is both the appeal and the boundary. If you do not already run Hermes Agent, this project gives you nothing.

How It Works: A Three-Panel Client

The interface is a three-panel layout. Left sidebar for sessions and navigation, center for chat, right for workspace file browsing. The composer footer holds model, profile, and workspace controls, and a circular context ring shows token usage. All settings and session tools live in the Hermes Control Center, launched from the sidebar bottom. The README lists features like session projects, tags, tool call cards, and a workspace file browser with inline preview. Nothing here suggests a heavy framework. The README explicitly says no build step, no framework, no bundler, just Python and vanilla JS. That is a deliberate architectural choice. The backend is Python, the frontend is plain JavaScript. The data flow is simple: the web UI uses your existing Hermes agent, which does the actual work. In the single-container Docker setup the WebUI container runs the agent in-process, while the two- and three-container compose files separate them.

Getting It Running: Commands and Config Keys

The quick start is a clone and a bootstrap. Run git clone https://github.com/nesquena/hermes-webui.git hermes-webui, then cd hermes-webui, then python3 bootstrap.py. Alternatively, ./start.sh. For a daemonized setup, ctl.sh wraps the lifecycle. The README gives concrete commands: ./ctl.sh start runs the bootstrap in background, writes a PID to ~/.hermes/webui.pid, and logs to ~/.hermes/webui.log. ./ctl.sh status shows PID, uptime, bound host/port, log path, and /health. ./ctl.sh logs --lines 100 tails the log. ./ctl.sh restart and ./ctl.sh stop are also there. Configuration comes from a .env file plus inline overrides, such as HERMES_WEBUI_HOST=0.0.0.0 ./ctl.sh start. The default port appears to be 8787, based on the README's stop instructions that mention lsof -i :8787. The README's configuration section covers auto-discovery and overrides.

The Stop Problem: A Genuine Failure Mode

The README is unusually honest about a limitation: each launch method has its own stop path, and they do not interoperate. If you start with python3 bootstrap.py, you stop with Ctrl-C in the foreground. If you start with ./ctl.sh start, you stop with ./ctl.sh stop. But if you launch bootstrap.py detached or use ./start.sh, there is no PID file, and you must find the process via lsof -i :8787 or ss -tlnp and kill it manually. Worse, the README states plainly that ./ctl.sh stop cannot stop a server launched by bootstrap.py or start.sh directly. That is a sharp edge. An operator who mixes launch methods will find themselves hunting for PIDs. This is the kind of detail that matters in production. The project acknowledges it, which is good, but it is a real operational cost. If you are automating deployment, you must standardize on one launch method or you will create zombie processes.

Security and Access: SSH Tunnel as the Default

The README recommends accessing the web UI securely through an SSH tunnel from your Hermes setup. That is a specific, concrete security model, alongside a configurable password and, per requirements.txt, optional local passkey/WebAuthn support. The README mentions you can customize settings and configure a password, but the default path is SSH tunneling. That means the web UI itself is not exposed to the internet by default. For a homelab or a single-user server, that is reasonable. For a team or a public deployment, it is insufficient. The README's contents also list remote, Tailscale and phone access under configuration. The point is that much of the security posture is left to the operator. That is a trade-off: simplicity on the client side, but security responsibility on you.

Alternatives: OpenClaw and the CLI

The README itself names OpenClaw as the closest competitor. Both are always-on, self-hosted, open-source agents with memory, cron, and messaging. The difference: OpenClaw is Node.js based, Hermes is Python. OpenClaw's skill system centers on a community marketplace, while Hermes writes and saves its own skills automatically. The README also claims Hermes is more stable across updates, citing documented release regressions in OpenClaw. For the web UI specifically, OpenClaw offers a dashboard only, not a full chat interface. Hermes WebUI gives full parity with the CLI. If you are already in the Node.js ecosystem or prefer a marketplace for skills, OpenClaw is a real alternative. If you are a Python user and want a full browser UI, Hermes WebUI is the one. The CLI itself is also an alternative: if you are comfortable in a terminal, you do not need this project at all. The web UI adds convenience, not capability.

Maintenance and Upgrade Cost

The repository is actively pushed, with releases like exp-v0.52.621 dated 2026-11-03. The versioning is experimental, indicated by the exp prefix. That means you should expect frequent updates and possible breaking changes. The license is MIT, which allows free use and modification, but you must retain the copyright notice. The project is self-hosted, so you are responsible for updates and backups. The README's architecture section covers the state directory, and logs and the PID file live under ~/.hermes. The cost is low for a single user, but for a production deployment, the experimental versioning and the stop-procedure quirk mean you should test upgrades carefully.

Editorial conclusion

Adopt Hermes WebUI if you already run Hermes Agent and want a browser-based interface with CLI parity, especially for phone access via SSH tunnel. Skip it if you expect a standalone agent. Before adopting, verify your launch method and stop procedure: only ctl.sh start writes a PID file, and the README explicitly warns that ctl.sh stop cannot stop servers started by bootstrap.py or start.sh. Also confirm your SSH tunnel setup, since the README recommends that for secure remote access.

Frequently asked questions

Official sources

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