snapshot: preserve central wiki state 2026-08-15 (7 modified + 1 new file)

2026-08-15 22:11:30 +08:00
commit 92e8028bb8
71 changed files with 9897 additions and 0 deletions
@@ -0,0 +1,96 @@
+---
+title: Restart Hermes
+type: runbook
+status: active
+created: 2026-07-22
+updated: 2026-07-22
+verified_on: 2026-07-22
+last_tested: 2026-07-22
+confidence: high
+tags: [runbook, hermes, restart]
+sources: [raw/configs/hermes-config-sanitized.txt]
+---
+
+# 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 `hermes` with 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
+```bash
+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:
+- gateway: `/home/hermes/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main gateway run`
+- dashboard: `/home/hermes/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main dashboard ...`
+- webui: `/home/hermes/.hermes/hermes-agent/venv/bin/python /home/hermes/hermes-webui/server.py`
+- camofox/cua-driver: `/home/hermes/.local/bin/cua-driver serve`
+- x11vnc: `-display :99 ... 5901`
+
+### 2. Restart the gateway
+```bash
+hermes gateway restart
+```
+
+### 3. Restart the dashboard if needed
+```bash
+hermes dashboard restart
+```
+If that fails, stop and rerun:
+```bash
+hermes dashboard stop
+hermes dashboard --host 0.0.0.0 --port 9119 --no-open
+```
+
+### 4. Restart the browser helper if needed
+```bash
+pkill -f "cua-driver serve"
+/home/hermes/.local/bin/cua-driver serve
+```
+
+### 5. Restart the WebUI if needed
+Find its PID, then restart standalone:
+```bash
+pkill -f "hermes-webui/server.py"
+/home/hermes/.hermes/hermes-agent/venv/bin/python /home/hermes/hermes-webui/server.py
+```
+
+## Verification
+```bash
+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
+
+## Related
+- [[runbooks/backup-wiki]]
+- [[runbooks/update-hermes-safely]]