Hermes Agent Guide
Hermes Agent in tmux: The Gateway Expects a Supervisor
tmux is the usual answer to "my gateway dies when I close my laptop", and it does fix that. Hermes is an unusually bad fit for it though, and not for the generic reasons — the gateway actively kills itself when it detects trouble, on the assumption that something is watching. Understanding that one design decision tells you exactly where tmux stops working.
What you are keeping alive
The long-running piece of Hermes is the gateway, started with:
hermes gateway runIt holds your platform connections and keeps the agent reachable. It runs in the foreground, so it belongs to the shell that launched it and dies when that shell goes away. An interactive hermes chat session is a separate, deliberately transient thing — this guide is about the gateway.
Hermes assumes something will restart it
This is the part that makes the tmux question different for Hermes than for other agent runtimes.
The gateway runs an in-process liveness watchdog on a daemon OS thread. It repeatedly probes the event loop; if the loop stops processing those probes, the watchdog counts a miss. After a few consecutive misses — the default is three, roughly 90 to 120 seconds of sustained blocking — it dumps the stacks of every thread and hard-exits with the service-restart code, exit 75.
Read that again as a design statement: when Hermes decides it is wedged, its recovery strategy is to die. The upstream comment is explicit that it exits this way so the supervisor can revive the process. It is on by default (gateway.loop_watchdog), and its tolerances are tuned to ignore transient stalls — a Telegram or Discord reconnect doing synchronous socket I/O during a network blip should not trigger it — so an exit generally means a genuine wedge, not noise.
Why that makes tmux the wrong home
Deliberate self-termination is a good strategy when something restarts you. It is a terrible one when nothing does.
In a tmux pane, the gateway detects a wedge, prints a wall of thread stacks, exits 75 — and stops. The pane keeps the stack dump on screen. The session is still there. Nothing is listening for that exit code, so nothing acts on it. Your agent is offline, having correctly diagnosed its own problem and signalled for help that never comes.
That is worse than the ordinary "tmux does not restart crashes" complaint. A crash is an accident. This is a designed handoff to a supervisor, and tmux quietly drops the handoff. The failure also tends to arrive at the least convenient time, because the conditions that wedge an event loop — network trouble, a wave of reconnects — are exactly the conditions where you are not watching.
The short version: Hermes ships self-healing that only works if it is supervised. Running it in tmux keeps the self-diagnosis and throws away the healing.
The second watchdog, and why the unit file is not enough
There is a separate, systemd-facing mechanism, and it is easy to misconfigure because it is opt-in. gateway.systemd_watchdog_seconds defaults to 0, and zero deliberately keeps Type=simple and disables sd_notify at runtime.
So writing Type=notify and a WatchdogSec into a unit file does not, by itself, get you readiness signalling or heartbeats — you also have to set that config value to a positive number. Upstream normalises the two together precisely so a value cannot enable Type=notify while leaving the application heartbeats off, which would leave systemd waiting forever for a readiness message that never arrives.
Note the division of labour: the loop watchdog works under any supervisor, because it just exits. The sd_notify path is what lets systemd additionally know when the gateway is ready and healthy.
If you are using tmux anyway
For development it is entirely reasonable. Start a named session, run the gateway in it, detach with Ctrl-b d, and come back with tmux attach -t hermes:
tmux new -s hermes
hermes gateway run
# Ctrl-b then d to detach
tmux attach -t hermesThe general tmux mechanics — panes, windows, copy mode for scrolling back through output — are the same for any process, and are covered in the OpenClaw tmux guide rather than repeated here. One habit worth forming for Hermes specifically: if the agent goes quiet, reattach and scroll back. A thread-stack dump ending in exit 75 is the watchdog telling you the loop was blocked, not a mystery crash.
What to run instead
Anything that restarts the process on exit turns the watchdog from a liability back into a feature.
- A systemd unit with a restart policy is the natural fit, since exit 75 is meant for exactly this. Add
gateway.systemd_watchdog_secondsif you also want readiness and heartbeat reporting. - Docker with a restart policy achieves the same result without writing a unit file.
- Managed hosting removes the question: the gateway is supervised, restarts on failure, and survives reboots, with no terminal in the loop. The VPS guide covers the self-hosted end of this.
All three are legitimate. The one option that quietly breaks a documented Hermes behaviour is leaving the gateway in a tmux pane and treating that as deployment.
Hermes Agent and tmux FAQ
Can I run the Hermes gateway in tmux?
You can, and for development it is fine. But Hermes is built on the assumption that something will restart it: the gateway runs an in-process liveness watchdog, on by default, that hard-exits when the event loop wedges so a supervisor can bring it back. In a tmux pane nothing brings it back, so a mechanism designed to self-heal turns into a silent outage.
What is the Hermes loop watchdog?
A daemon OS thread that probes the gateway's event loop. After a few consecutive missed probes — the default is three, roughly 90 to 120 seconds of sustained blocking — it dumps every thread's stack and hard-exits with the service-restart code, exit code 75. It is enabled by default and can be turned off with gateway.loop_watchdog: false.
Does the gateway support systemd sd_notify?
Yes, but it is opt-in and off by default. gateway.systemd_watchdog_seconds is 0 out of the box, and zero deliberately keeps Type=simple and disables sd_notify at runtime. Set it to a positive number to get readiness signalling and watchdog heartbeats; writing Type=notify in the unit file alone will not enable them.
Does tmux survive a reboot?
No. tmux sessions live in memory and are lost when the machine restarts, so any host that reboots for kernel updates takes the gateway with it and never brings it back.