.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
If you've installed Hermes Agent and you're running it inside a tmux session "for now", this is the article that retires that habit. A real systemd unit takes about ten minutes to write, gives you automatic restart on crash, survives reboots without you logging in and routes its logs to journald where they're searchable. Compared to "screen + nohup + I'll remember", it's the upgrade that lets you stop thinking about the agent.
The setup below assumes you've followed the Ubuntu install guide and have hermes on your PATH at ~/.local/bin/hermes. If you came in via a LumaDock VPS with the Hermes template, the VPS setup guide ships a unit out of the box, so you can skim this article for the tuning bits and ignore the install-from-scratch steps. If you're on a different install layout, adjust the ExecStart path accordingly.
What needs to run as a service
Hermes has two long-running processes worth thinking about, plus a third that's optional.
The gateway (hermes gateway start) is the thing that talks to messaging platforms. It polls Telegram, holds a Discord WebSocket open, listens on whatever ports your other channels need. This is the one you want as a real systemd service because if it dies, your bot stops responding.
The interactive CLI (hermes) is the terminal you use when you SSH in and want to talk to the agent directly. You don't run this as a service. You start it ad-hoc when you need it. The interactive session and the gateway can both run at the same time against the same data dir.
The optional third is anything you've configured to run on cron-style schedules. Hermes manages cron jobs internally via the /cron command, so they fire from inside the running gateway process. You don't need a separate cron service if your gateway is up.
The unit below covers the gateway. That's the one you need.
The unit file
Create /etc/systemd/system/hermes.service with the following content. Substitute youruser for whatever Linux user you installed Hermes as.
[Unit]
Description=Hermes Agent gateway
Documentation=https://hermes-agent.nousresearch.com/docs
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=youruser
Group=youruser
WorkingDirectory=/home/youruser
Environment="HOME=/home/youruser"
Environment="PATH=/home/youruser/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
ExecStart=/home/youruser/.local/bin/hermes gateway start
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=hermes
# Resource caps to keep one bad turn from eating the box
MemoryMax=2G
CPUQuota=200%
# Light hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/home/youruser/.hermes
[Install]
WantedBy=multi-user.targetA few of those lines deserve explanation.
After=network-online.target with Wants=network-online.target tells systemd to start Hermes only after the network is fully up. Without it, the gateway tries to connect to Telegram during boot, fails because DNS isn't ready, restarts, fails again. With it, the gateway waits for real connectivity and starts cleanly.
Type=simple works because hermes gateway start is a long-running foreground process. It doesn't fork. If you ever switch to a setup where you wrap Hermes in a manager like tini or run it under a process supervisor, change this to Type=exec or Type=notify, but for vanilla Hermes, simple is right.
Restart=on-failure with RestartSec=10 means systemd will restart the service if it exits non-zero, but waits 10 seconds first. The wait matters because Hermes restart loops can hammer your LLM provider during the brief window where a bad config is causing an immediate crash on every startup. The 10-second backoff gives you time to systemctl stop hermes if you see it crash-looping in the logs.
The resource caps (MemoryMax=2G, CPUQuota=200%) are sized for a small VPS. MemoryMax is a hard limit. If Hermes tries to allocate beyond it (say, a runaway browser-automation task with too much state), the kernel kills it and systemd restarts it. CPUQuota=200% means up to two CPU cores' worth of time, which is plenty for normal agentic work. Adjust both up if you have headroom.
The hardening lines (NoNewPrivileges, PrivateTmp, ProtectSystem=strict, ProtectHome=read-only with explicit ReadWritePaths) are belt-and-braces stuff. They mean that if your Hermes process gets compromised (a malicious skill, a remote-execution bug), it can't write to most of the filesystem and can't escalate privileges. The cost is that you have to remember to add directories to ReadWritePaths if Hermes ever needs to write outside ~/.hermes.
Enable and start the service
sudo systemctl daemon-reload
sudo systemctl enable hermes
sudo systemctl start hermes
sudo systemctl status hermesThe status output should show active (running), with the most recent log lines from Hermes appearing at the bottom of the systemctl status panel. If you see activating (auto-restart) or failed, jump to the troubleshooting section.
To watch logs live:
journalctl -u hermes -fTo search logs (say, for errors in the last hour):
journalctl -u hermes --since "1 hour ago" -p errThe -p err filter restricts to error-level messages and above; useful when you're trying to find the proverbial needle.
Log rotation
journald handles log rotation by default, but the default ceiling is generous. If you're on a VPS with a small disk, journald can use up to 10% of your filesystem before rotating, which is more space than a small box has to spare. Cap it explicitly.
Edit /etc/systemd/journald.conf and uncomment or add:
SystemMaxUse=200M
SystemKeepFree=500M
RuntimeMaxUse=100MThen sudo systemctl restart systemd-journald to apply. journald will keep up to 200 MB of persistent logs and 100 MB of runtime (volatile) logs, freeing space when it gets close to either ceiling.
For most personal Hermes installs, 200 MB of logs holds about three to six weeks of normal traffic. If you need longer retention, bump the cap or pipe logs to a remote log host with rsyslog or Vector.
Loading environment variables from .env
The unit above relies on Hermes reading its config from ~/.hermes/config.yaml and ~/.hermes/.env, which it does by default. If you have additional environment variables that aren't in .env (a custom HERMES_HOME, third-party MCP server credentials, etc.), the cleanest pattern is to put them in a separate file and reference it from the unit:
EnvironmentFile=-/etc/default/hermesThe leading - tells systemd not to fail if the file doesn't exist. Then /etc/default/hermes is a normal shell-style env file:
HERMES_LOG_LEVEL=info
HERMES_DEFAULT_PROVIDER=nous-portalMake sure /etc/default/hermes is owned by root and readable by your service user. chmod 640 with the service user in the group is reasonable.
Updates without dropping conversations
When you run hermes update, the binary itself updates but your data stays put. The systemd service won't pick up the new binary until you restart it. The pattern that works:
sudo systemctl stop hermes
hermes update
sudo systemctl start hermesIf you want to make this automatic on a schedule, drop a small unit pair: a timer that fires nightly and a oneshot service that runs the update sequence. The oneshot looks like:
[Unit]
Description=Hermes Agent auto-update
After=network-online.target
[Service]
Type=oneshot
User=youruser
ExecStart=/usr/bin/systemctl stop hermes
ExecStart=/home/youruser/.local/bin/hermes update --non-interactive
ExecStart=/usr/bin/systemctl start hermesPair it with a timer that fires at 04:00 daily. If this is a good idea, that depends on your tolerance for the agent restarting at 4 AM. For some people, automatic updates are fine. For others (especially anyone running a production agent with users who message at all hours), manual updates after testing are the right policy.
Troubleshooting failed starts
The three most common ways the unit fails on first start:
"Failed to start: Permission denied" usually means the user can't read its own home directory. Check with sudo -u youruser ls -la ~/.hermes. If that fails, your user's home permissions are off; fix with chmod 700 /home/youruser and re-check.
"Failed to start: Unit not found" after editing the unit file means you forgot to systemctl daemon-reload. Run it; try again.
"Active: failed (Result: exit-code)" with the gateway exiting immediately is almost always a config problem. Run sudo -u youruser /home/youruser/.local/bin/hermes gateway start directly from the shell as the service user. The error that comes out tells you what's wrong; common ones are missing API keys, an invalid bot token or a port that's already taken by something else.
If hermes runs fine when invoked directly but fails under systemd, the difference is almost always the environment. The interactive shell sources ~/.bashrc which adds variables and PATH entries that systemd's stripped-down environment doesn't have. Add the relevant variables to your unit's Environment= lines.
Multiple instances on the same machine
If you're running Hermes alongside OpenClaw or running two Hermes installs (one for personal use, one for work), you can templatise the unit using systemd's @ instance feature. Save the unit as /etc/systemd/system/[email protected] and replace the user references with %i:
[Service]
User=%i
ExecStart=/home/%i/.local/bin/hermes gateway start
ReadWritePaths=/home/%i/.hermesThen enable per-user instances:
sudo systemctl enable --now hermes@alice
sudo systemctl enable --now hermes@bobEach instance runs as its own user, with its own data dir and its own logs. journalctl -u hermes@alice -f tails one of them. The side-by-side article covers the broader pattern of running multiple agents on one VPS.
If you're starting from scratch on a fresh box
The LumaDock Hermes Agent VPS template ships with the systemd unit pre-installed and enabled, so the gateway starts on first boot and survives reboots without you doing any of the above. Useful when you want the boring infrastructure to be done on someone else's time so you can focus on configuring the agent.
