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.

8 min read • View on GitHub • More from nesquena

A wide editorial illustration of a glass bell jar shaped like a browser window resting on a wooden desk. Inside the jar sits a small mechanical brain built from gears and vacuum tubes, and a single thick cable runs out to a terminal on the left and a smartphone on the right. The illustration shows the interface as a transparent shell wrapped around a living agent, with no construction scaffolding around the glass.
Hermes WebUI is a shell around an agent that already exists. The browser window holds the agent, it does not build one.
Key Takeaways

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.

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.

Hermes WebUI project, Project description · nesquena/hermes-webui

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.

Hermes WebUI project, Project description · nesquena/hermes-webui

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.

nesquena, Project creator and maintainer · Repo Explainer article

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.

  1. shutil.which("hermes") locates the launcher on PATH.
  2. The first 20 lines are read, bounded so a huge binary is never slurped.
  3. The code parses either a Python console-script shebang or a POSIX shell wrapper that execs the real binary.
  4. Parent directories are walked until run_agent.py turns 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.

A close-up editorial illustration of two hands passing a baton. The left hand is human and holds a small data packet shaped like a JSON brace, while the right hand is mechanical and receives it. A thin taut thread runs from the baton to a brass spool at the right edge, and a dotted arc traces between the two hands. The image represents the handoff of a streaming turn from the agent thread to the browser, with the spool standing in for the per-stream buffer that lets a reconnect resume.
A turn is passed from the agent thread to the browser over SSE, while the stream buffer holds the thread that lets a reconnect pick up where it stopped.

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.

How a turn moves from the agent thread to the browser, and how a reconnect resumes from the last event ID instead of restarting.

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.

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.

ProjectPrimary interfaceBuild stackAgent modelSelf-hosted web UI
Hermes WebUIBrowser shell for the Hermes AgentStdlib Python + vanilla JS, no build stepOne persistent Hermes Agent processYes, tightly coupled to the agent
OpenClawAlways-on agent with memory and messagingProject-specific stackSelf-hosted persistent agentYes
Claude CodeTerminal coding agentNode CLIAnthropic-tied coding agentNo first-party web UI
Codex CLITerminal coding agentRust and Node CLIOpenAI coding agentNo first-party web UI
OpenCodeTerminal and browser coding agentProject-specific stackProvider-flexible coding agentYes
Open WebUIGeneral model dashboardPython + Svelte frontendAny OpenAI-compatible endpointYes, generic
Chatbot UIGeneral chat frontendNext.js + ReactAny model providerYes, generic
SillyTavernPersona and roleplay chat frontendNode + vanilla JSAny model providerYes, 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.