Hermes WebUI: The Agent Interface Built Without a Framework
A stdlib Python server and hand-written JavaScript deliver near CLI parity for the Hermes Agent, with no build step required.
- Hermes WebUI is a browser shell around one persistent Hermes Agent process, not a general-purpose chat frontend.
- It reaches near CLI parity by sharing the agent's filesystem and SQLite state rather than reimplementing sessions, memory, or tool calls.
- The stdlib Python server and vanilla JavaScript stay small enough to read and modify, with no framework, bundler, or build step.
- Streaming turns, bounded concurrency, and agent discovery are treated as first-class engineering problems, not afterthoughts.
The Web UI That Refuses to Be a Web App
Hermes WebUI has no React. No Vue. No bundler. No build step. The server is Python's standard library http.server, subclassed into a threaded QuietHTTPServer. The frontend is hand-written JavaScript and CSS.
Roughly 81 percent of the repository is Python and 16 percent is JavaScript. That ratio matters. There is no node_modules directory to audit, no transpile step between saving a file and seeing the change, and no framework version to track.
- 81% Python
- 16% JavaScript
- 0 build steps
- 1 server process
For a project that fronts an autonomous agent, this is a deliberate bet. The interface stays small enough to read in an afternoon and modify without a toolchain. When something breaks, the stack trace points at a file you can open.
No build step, no framework, no bundler. Just Python and vanilla JS.
A Shell Around an Agent, Not a Chat App
Hermes WebUI does not contain the agent. It finds an existing Hermes Agent installation, imports its modules in-process, runs its turns on threads, and reads its SQLite state. The interface is a shell around a process that already exists.
The layout reflects that. Sessions sit on the left, the conversation runs in the center, and a workspace file browser fills the right. A composer footer holds model, profile, and workspace controls. Settings live in a Hermes Control Center.
The coupling is the point. The WebUI shares a filesystem and database with the agent instead of reimplementing sessions, memory, or tool state. A layer of adapter modules (agent_compat.py, runtime_adapter.py, agent_health.py) absorbs drift between agent versions.
Hermes WebUI is a lightweight, dark-themed web app interface in your browser for Hermes Agent.
Why Build It?
The target user already runs Hermes on a server. They want to reach it from a browser or a phone without exposing it to the open internet. The documented path is an SSH tunnel to a host bound to 127.0.0.1, with Tailscale and mobile access as alternatives.
The project is built by nesquena and contributors. It is not a universal chat frontend, and it does not try to be. The value is reaching one agent, with its sessions and workspace intact, from wherever you happen to be.
Hermes WebUI is not trying to be a universal chat app. It is a browser shell for one persistent agent process, and that changes everything about how the interface works.
Finding Hermes: Bootstrap Archaeology
Before the server can stream anything, it has to find the agent. bootstrap.py does this by inspecting the hermes launcher script itself.
shutil.which("hermes")locates the launcher on PATH.- The first 20 lines are read, bounded so a huge binary is never slurped.
- The code parses either a Python console-script shebang or a POSIX shell wrapper that execs the real binary.
- Parent directories are walked until
run_agent.pyturns up.
Explicit candidates always win. A path set through HERMES_WEBUI_AGENT_DIR, or a clone at $HERMES_HOME/hermes-agent, takes precedence over whatever the CLI points at. A stale clone in a known location beats the live launcher.
The tradeoff is fragility. Discovery reverse-engineers the installer's output format, and the docstring already documents two installer generations. If a third changes the wrapper shape, discovery falls back silently.
def _agent_dir_from_hermes_cli():
hermes = shutil.which("hermes")
if not hermes:
return None
# read a bounded prefix so we never slurp a huge file
with open(hermes, "r", errors="replace") as fh:
head = "".join(islice(fh, 20))
target = None
for line in head.splitlines():
line = line.strip()
# POSIX shell wrapper: exec "/path/to/venv/bin/hermes" "$@"
if line.startswith("exec "):
target = _parse_exec_target(line)
break
# Python console-script shebang points at the venv binary
if line.startswith("#!"):
target = _parse_shebang_target(line)
if not target:
return None
# walk up until run_agent.py turns up
for parent in [target, *target.parents]:
if (parent / "run_agent.py").exists():
return parent
return None
Turns That Survive a Refresh
Agent turns are long. A browser refresh, a dropped Wi-Fi connection, or a backgrounded phone tab should not kill one. Hermes WebUI runs each turn on a background thread and fans its output to clients over server-sent events.
Per-stream buffers hold the state needed to resume: partial answer text, reasoning text, live tool calls, and the last event ID. A reconnecting client sends Last-Event-ID, and the server replays from there instead of restarting the turn.
Cancellation is cooperative. CANCEL_FLAGS let the UI ask a running turn to stop. Each session holds its own agent lock, so two turns cannot drive the same agent at once.
def get_stream_runtime_snapshot():
# copy the registry under a nonblocking acquire
if not STREAMS_LOCK.acquire(blocking=False):
return partial_snapshot()
try:
streams = list(STREAMS.values())
finally:
STREAMS_LOCK.release()
# STREAMS_LOCK is now released, before any channel lock is touched,
# so registry and channel locks are never nested.
results = []
for stream in streams:
snapshot = stream.read_nonblocking()
if snapshot is None:
continue # a busy channel counts as unavailable
results.append(snapshot)
return results
The snapshot endpoint that reports on live streams follows a strict lock-ordering rule. The registry is copied under a nonblocking acquire of STREAMS_LOCK, and that lock is released before any per-channel lock is touched. Registry and channel locks are never nested, so the endpoint cannot deadlock. A busy channel counts as unavailable and the loop moves on. A partial answer beats a stalled server.
Bounded by Design
Concurrency is capped rather than left to the operating system. QuietHTTPServer sets a fixed queue size and allows a fixed maximum of concurrent request threads, enforced by a semaphore.
request_queue_size = 64queued connectionsmax_request_workers = 128concurrent request threadsmax_overflow_reject_workers = 16in-flight static 503 responsesCUSTOM_MODELS_ENDPOINT_TIMEOUT_SECONDS = 5.0provider probe timeoutCUSTOM_MODELS_ATTEMPT_ONLY_TIMEOUT_SECONDS = 0.01minimum probe timeout
When the worker pool is full, the server writes a pre-built 503 response directly instead of spawning another thread. Only 16 rejections can be in flight at once. Under a connection flood, the server sheds load instead of growing without bound.
Smaller details show the same discipline. SIGPIPE is ignored so a client disconnect cannot kill the process. The 0.01-second probe timeout exists because Python's urllib reads a literal zero timeout as non-blocking, which would report a live probe as an instant failure.
How Hermes WebUI Compares
Hermes WebUI is not competing with general model dashboards. It is a purpose-built shell for one agent, and the comparison table below shows where that puts it next to other agent tools and chat frontends.
| Project | Primary interface | Build stack | Agent model | Self-hosted web UI |
|---|---|---|---|---|
| Hermes WebUI | Browser shell for the Hermes Agent | Stdlib Python + vanilla JS, no build step | One persistent Hermes Agent process | Yes, tightly coupled to the agent |
| OpenClaw | Always-on agent with memory and messaging | Project-specific stack | Self-hosted persistent agent | Yes |
| Claude Code | Terminal coding agent | Node CLI | Anthropic-tied coding agent | No first-party web UI |
| Codex CLI | Terminal coding agent | Rust and Node CLI | OpenAI coding agent | No first-party web UI |
| OpenCode | Terminal and browser coding agent | Project-specific stack | Provider-flexible coding agent | Yes |
| Open WebUI | General model dashboard | Python + Svelte frontend | Any OpenAI-compatible endpoint | Yes, generic |
| Chatbot UI | General chat frontend | Next.js + React | Any model provider | Yes, generic |
| SillyTavern | Persona and roleplay chat frontend | Node + vanilla JS | Any model provider | Yes, generic |
Who Should Run This
Hermes WebUI is for people who already run Hermes and want a browser and phone surface for it without opening the agent to the internet. If you want a general dashboard for many models and providers, this is not that tool.
The no-build stack is a feature for a specific kind of user: someone who wants to read the interface, change a stylesheet, and reload the page. That is a smaller audience than a framework would reach, and it is exactly the audience the project is built for.





