Hermes Agent vs Hermes WebUI: What Gets Restarted on Update

An update is the moment you find out which parts of your setup were really one install and which were three. Hermes Agent and Hermes WebUI sit on the same screen, so they read as one product. They are not. They are two checkouts with two update paths, and only one of them is managed by hermes update.

This post compares them on the thing that actually bites: what gets restarted when you update, what stays on old code, and which one to run.

The name clash behind the question

The Hermes docs call the browser panel that ships with the agent the Web Dashboard. You start it with hermes dashboard, and it manages configuration, API keys, MCP servers, messaging pairing, webhooks, memory, credentials, sessions, logs, analytics, cron jobs and skills, with an embedded chat.

“Hermes WebUI” is also used for a separate community project, nesquena/hermes-webui. It is an independent repo with its own release cycle. This post means that one whenever it says Hermes WebUI, and the agent (with its built-in dashboard) whenever it says Hermes Agent.

What hermes update actually restarts

For a source install, hermes update runs a fixed pipeline: it snapshots state, changes the checkout, validates the pull and rolls back on a bad parse, prepares dependencies, migrates config, rebuilds the desktop app, and restarts the gateways.

The restart phase is the part people miss. On Linux and macOS, the updater pauses every gateway running from that install right before it first touches the checkout, then starts them again on the new code. Service-managed gateways restart through systemd or launchd. A gateway you started by hand is drained and relaunched in the background. The desktop app is rebuilt from the same checkout with a stage-and-swap, so a failed rebuild leaves the old app in place.

Two things are deliberately left alone. Manually launched hermes serve and hermes dashboard backends are not restarted; the updater leaves them running and reminds their owner. And a separate Hermes WebUI checkout is not part of this install at all, so nothing in hermes update touches it.

If you want the list before you commit, hermes update --plan prints the install kind, the running Hermes services across your profiles, their supervisors, their running code versions, and the restart mechanism for each. The same inventory lands in the update receipt after every run, so you can compare what the updater saw with what it did. These behaviours are described in the updating docs.

Why Hermes WebUI is a second update

Hermes WebUI is a separate repo, MIT licensed, with no build step: a Python standard-library HTTP server and vanilla JavaScript, backend in api/ and frontend in static/. It runs the Hermes agent in-process, reading your existing agent config and models, so it does not need a second copy of your setup.

That design is also why it updates separately. Because the server imports the agent in-process, a running WebUI keeps serving the code it loaded when it started. Updating the agent does not restart the WebUI, and restarting the WebUI is what makes it pick up new agent code. The WebUI has its own update check and release-notes banner, so it can tell you a newer version exists. Applying that update is your step, not the agent updater’s.

The practical order is agent first, then WebUI. Run hermes update, let it finish and restart the gateways, then restart the WebUI server. Done in that order, the WebUI comes up on the same agent code the gateways are running.

The cost of running both

Running both is not free overhead, and none of it is hidden. You have two services to keep alive and two checkouts to keep in step. The WebUI depends on the agent, so it can never be the only thing you install. And an agent update is the moment a mismatch shows: the gateways move to the new code, and the WebUI sits on the old code until you restart it.

If you want one thing to update, the built-in dashboard is the smaller path. If you want the agent in a browser on a phone, the separate WebUI is worth the second service.

When Hermes Agent is the better pick

Pick Hermes Agent alone when your day is mostly the terminal, the Ink TUI, or the desktop app. Pick it when a browser is only for admin: configuration, keys, MCP servers, cron, logs. The built-in dashboard covers that, plus an embedded chat and every messaging platform the gateway reaches.

It is also the better pick when “one thing to update” matters more than a browser chat. Fewer services means fewer restart steps after an update, and the updater handles the parts it manages on its own.

When Hermes WebUI is the better pick

Pick Hermes WebUI when you want full CLI parity in a browser, from a laptop or a phone. Its three-panel layout puts sessions and navigation on the left, chat in the centre, and a workspace file browser on the right, and it uses your existing agent and models with no extra setup.

Pick it when you want optional password, passkey, or OIDC sign-in on the browser surface, or when you would rather reach the agent over a private network or an SSH tunnel than a terminal. It is also the lighter choice for a homelab box, since there is no build step and no bundler: it is Python and vanilla JavaScript.

The honest summary: they are not rivals. Hermes Agent is the install. Hermes WebUI is an optional front end for it, and the one thing to remember at update time is that it is a second checkout you restart yourself. More tool comparisons live on the resources index.