What does this mean?

Suggested meta description: The Hermes WebUI refuses to work after an agent update? Here’s why sudo systemctl restart hermes-webui gets you nowhere and the one-liner that actually fixes it.

---

If you run the Hermes Agent locally and use the web interface in your browser, this scenario will probably look familiar: you update the agent, switch back to the open browser tab, click any action — and instead of a result you get this message:

Hermes Agent was updated while Hermes WebUI was running. Restart Hermes WebUI before retrying this action.

The message tells you almost exactly what to do. And yet the obvious restart commands fail, and you can easily lose ten minutes to a problem that a single line solves.

The short version

systemctl --user restart hermes-webui

No sudo. That’s the crucial part.

Why the message appears at all

This isn’t a bug in the usual sense it’s a deliberate safeguard.

The WebUI is a separate, long-running process. At startup it loads the Hermes Agent’s modules into memory and keeps that version there for as long as it runs. If the agent is then updated on disk, nothing happens inside the running process: the code in memory is frozen, while the code on disk is new.

Hermes detects exactly this mismatch and blocks further actions. That’s sensible, because the alternative would be considerably worse: an interface mixing old and new code paths, issuing calls with changed signatures, or working against a migrated database schema it doesn’t know about yet. A clean stop with a clear instruction is by far the better option.

Rule of thumb: an agent update only takes effect after the WebUI is restarted.

Why sudo systemctl restart hermes-webui doesn’t work

This is where the real trap sits. Typical responses look like this:

Failed to restart hermes-webui.service: Unit hermes-webui.service not found.

Or the restart is acknowledged but changes nothing in the browser.

The reason: systemd manages two separate levels.

• System level — services that start at boot as root, independent of any login. Addressed with systemctl or sudo systemctl.
• User level — services that run in the context of a specific user. Addressed with systemctl --user.

A local Hermes installation usually lives in the home directory (typically under ~/.hermes), accesses user-owned configuration, models and databases, and is therefore best run as a user unit.

And here’s the part that makes this confusing: sudo doesn’t just change privileges, it changes the user context too. So sudo systemctl --user restart hermes-webui queries root’s session bus — where the unit simply doesn’t exist. The sudo needs to go, with nothing replacing it.

The same applies to attempts like systemctl restart hermes: if no system unit by that name exists, there’s nothing to restart.

Diagnosis: how is my WebUI actually running?

If the one-liner above doesn’t change anything, it’s worth checking the actual state. These four commands settle the question quickly:

# 1. Does a user unit exist?
systemctl --user list-units --all | grep -i hermes

# 2. Does a system unit exist?
systemctl list-units --all --type=service | grep -i hermes

# 3. Is the process running without systemd at all (shell, tmux, screen)?
ps aux | grep -i hermes | grep -v grep

# 4. Which PID holds the WebUI port? (adjust the port as needed)
sudo ss -tulpn | grep -E '8000|8080|7860'

Command 4 is the most telling one: whichever process holds the port is exactly the process that needs restarting — no matter how it was originally started.

Depending on what you find:

• User unit: systemctl --user restart hermes-webui
• System unit: sudo systemctl restart hermes-webui
• Started manually: stop it with kill <PID>, confirm it’s gone with ps aux, then run your usual start command again
• Container: docker restart <container-name>

If the message persists after a restart

In the vast majority of cases the restart ends the story. If the message sticks around, there are two usual culprits:

The old process is still alive. The restart failed, the port is still held by the old instance, and the browser is talking to the same process as before. Check with:

systemctl --user status hermes-webui
journalctl --user -u hermes-webui -n 50 --no-pager

The browser is holding on to an old state. A hard reload (Ctrl + Shift + R) clears that up, particularly with open WebSocket connections or cached frontend assets.

After a reboot: don’t forget lingering

One side effect of user units regularly causes confusion: by default they only run while a session for that user exists. On a server with nobody permanently logged in, the WebUI is simply gone after a reboot.

Lingering solves this:

sudo loginctl enable-linger $USER

The user unit will then start without an active login — and the interface is reachable again after a restart.

Conclusion

The message isn’t a defect but a deliberate guard against an inconsistent state between an updated agent and a still-running interface. The fix is a single command — you just have to know that the WebUI runs as a user service and that sudo actively gets in the way here:

systemctl --user restart hermes-webui

If you update the agent regularly, build the restart into your update routine. Then the message never shows up in the first place.

---

Also see this article about SSH and Hermes