3.9 KiB
title, type, status, created, updated, verified_on, last_tested, confidence, tags, sources
| title | type | status | created | updated | verified_on | last_tested | confidence | tags | sources | ||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Restart Hermes | runbook | active | 2026-07-22 | 2026-10-20 | 2026-10-20 | 2026-10-20 | high |
|
|
Restart Hermes
Purpose
Restart the Hermes agent, gateway, dashboard, and browser helper processes cleanly.
Symptoms that match this runbook
- Hermes stops responding in chat or WebUI
- Tools fail mid-session but the agent is otherwise running
- After an update or config change
Prerequisites
- User account
hermeswith access to systemd --user - No active backups in progress
- If using a browser session, warn the user before restarting dashboards
Procedure
1. Identify the active Hermes processes
ps aux | grep -E "hermes_cli.main (gateway|dashboard) run|hermes-webui/server.py|cua-driver serve|x11vnc.*5901" | grep -v grep
Expected active pieces on this install (live ps 2026-10-20):
- gateway:
hermes gateway run→/home/hermes/.hermes/tools/python-3.14.7+20260901-linux-x64/bin/python3 … gateway run(unithermes-gateway.service) - dashboard:
hermes dashboard --host 0.0.0.0 --port 9119 --no-open(unithermes-dashboard.service) - webui:
/home/hermes/.hermes/hermes-agent/venv/bin/python /home/hermes/hermes-webui/server.py(port 8787) - camofox/cua-driver:
/home/hermes/.local/bin/cua-driver serve - x11vnc:
-display :99 ... 5901
The
venv/path in this runbook is wrong for the gateway and dashboard (verified 2026-10-20). They no longer run from~/.hermes/hermes-agent/venv/; they run from the uv-managed runtime~/.hermes/tools/python-3.14.7+20260901-linux-x64/, launched throughhermes_cli/main.pywith arunpybootstrap. Thehermeslauncher at/home/hermes/.local/bin/hermesis a 73-byte shim. Prefer thehermesCLI and the systemd user units over hand-writtenpython -m hermes_cli.main …commands — the units already carry the correct interpreter path and the_hermes_closure_repair()bootstrap that protects against a half-finishedhermes update.Live user units (2026-10-20):
hermes-gateway.service,hermes-dashboard.service,hermes-ui.service,hermes-ui-prod.service,hermes-wiki-serve.service— allactive (running).
2. Restart the gateway
hermes gateway restart
Equivalent and preferred (survives a broken CLI shim):
systemctl --user restart hermes-gateway.service
3. Restart the dashboard if needed
hermes dashboard restart
If that fails, stop and rerun:
hermes dashboard stop
hermes dashboard --host 0.0.0.0 --port 9119 --no-open
4. Restart the browser helper if needed
pkill -f "cua-driver serve"
/home/hermes/.local/bin/cua-driver serve
5. Restart the WebUI if needed
Find its PID, then restart standalone:
pkill -f "hermes-webui/server.py"
/home/hermes/.hermes/hermes-agent/venv/bin/python /home/hermes/hermes-webui/server.py
Verification
hermes gateway status
hermes dashboard status
ss -tlnp | grep -E "8787|9119|5901|6081"
ps aux | grep -E "gateway run|dashboard|cua-driver serve|server.py" | grep -v grep
Current known-good ports after verified restart:
- gateway: active via
hermes-gateway.service - dashboard:
0.0.0.0:9119 - webui:
0.0.0.0:8787 - VNC:
5901 - noVNC:
6081
Rollback
- If restart fails, review recent config changes and consider restoring
config.yaml.bak.* - Do not delete old config files without explicit confirmation
- Re-run backup first if you plan to rollback config
Notes
- Last tested: 2026-07-22 on debian 13, user-mode systemd
- WebUI logs:
/home/hermes/.hermes/webui/bootstrap-8787.log - Defunct
<defunct>processes in process list are expected zombie shells from prior runs and do not require action unless they pile up