Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Systemd Service

2.6. Systemd Service — Making It a Real Background Service

Installing the service (applies to the direct install only — Docker uses --restart unless-stopped in place of this)

hermes gateway install          # Linux, systemd user service
sudo hermes gateway install --system   # Linux, system-wide, starts at boot even without a login

The service restarts itself on crash and starts automatically when the machine reboots.

Everyday management commands

hermes gateway start
hermes gateway status
hermes gateway logs --follow

Why enable-linger is needed (already mentioned in 1.2)

With a systemd user service (not using --system), the service only lives while there is a user session — without linger, the service stops when you disconnect SSH:

sudo loginctl enable-linger hermes

After this step, the service survives both SSH disconnects and server reboots, restarting itself through the systemd user instance.

When systemd cannot be trusted

On WSL2, systemd support is unstable — many installs do not enable it by default, and even when enabled, the service may not survive a WSL restart or Windows shutting down on idle. In that case, running in the foreground directly or via tmux/nohup is the more practical solution:

tmux new -s hermes 'hermes gateway run'
# reattach later: tmux attach -t hermes

Notes

  • On a real Linux VPS (not WSL), always prefer systemd over tmux/nohup — systemd restarts on crash, tmux does not.
  • After installing new tools (Homebrew, nvm, cargo…) on a machine that already has the gateway service, remember to rerun hermes gateway install to capture the PATH again — missing PATH entries are the most common reason auxiliary tools (voice, WhatsApp bridge) suddenly report “not found” even though you installed them correctly.
  • On a freshly installed VPS, gateway start may fail immediately if gateway install has not been run first — this is expected behavior, not a bug; always install the service before trying to start it.