Linux Systemd Agent Deployment - Setup Guide¶
Prerequisites¶
- Linux system with systemd (Ubuntu 20.04+, Debian 11+, Fedora 35+)
- OpenClaw / Clawdbot / Hermes agent installed
- sudo access (for system-level services) or user systemd (
systemctl --user)
Capabilities¶
| Capability | Description |
|---|---|
| Unit File Generation | Create systemd .service files for agent processes |
| Restart Policies | on-failure, always, no - with RestartSec delay |
| Journald Logging | stdout/stderr automatically captured to journald |
| Resource Limits | MemoryMax, CPUQuota, TasksMax for agent processes |
| Environment Variables | Inject API keys, tokens, config paths via Environment= |
| User vs System Services | Choose user-level (systemctl --user) or system-level |
Installation¶
npx skills add alphaonedev/openclaw-graph/linux-systemd
Quick Start¶
User-Level Service (Recommended for Agents)¶
Create ~/.config/systemd/user/hermes-gateway.service:
[Unit]
Description=Hermes Agent Gateway
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
ExecStart=/usr/local/bin/hermes gateway run --profile <your-profile>
Restart=on-failure
RestartSec=30
MemoryMax=4G
CPUQuota=200%
Environment=HERMES_HOME=/home/<user>/.hermes/profiles/<your-profile>
Environment=PATH=/home/hermes/.hermes/node/bin:/usr/local/bin:/usr/bin:/bin
[Install]
WantedBy=default.target
Enable and start:
systemctl --user daemon-reload
systemctl --user enable hermes-gateway.service
systemctl --user start hermes-gateway.service
systemctl --user status hermes-gateway.service
System-Level Service¶
For agents that need to start at boot before user login:
[Unit]
Description=Hermes Agent Gateway (System)
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=hermes
Group=hermes
ExecStart=/usr/local/bin/hermes gateway run --profile <your-profile>
Restart=on-failure
RestartSec=30
MemoryMax=4G
CPUQuota=200%
Environment=HERMES_HOME=/home/<user>/.hermes/profiles/<your-profile>
[Install]
WantedBy=multi-user.target
Install to /etc/systemd/system/hermes-gateway.service and:
sudo systemctl daemon-reload
sudo systemctl enable hermes-gateway.service
sudo systemctl start hermes-gateway.service
Key Configuration Patterns¶
Restart Policy Selection¶
| Policy | Use When |
|---|---|
no |
One-shot tasks, cron jobs |
on-failure |
Long-running agents (prevents death loops from clean exits) |
always |
Critical services that must never stop (use with caution) |
Resource Limits¶
MemoryMax=4G # Hard memory cap - agent gets OOM-killed if exceeded
MemoryHigh=3G # Soft limit - agent gets throttled
CPUQuota=200% # Max 2 CPU cores
TasksMax=512 # Max threads/processes
Viewing Logs¶
# User service
journalctl --user -u hermes-gateway.service -f
# System service
journalctl -u hermes-gateway.service -f --since "10 minutes ago"
CorpusIQ Use Cases¶
-
Gateway Service: Run the Hermes gateway as a systemd service (e.g.,
hermes-gateway.serviceon your agent workstation).Restart=on-failureprevents death loops from CLI--replaceconflicts. -
Cron Workers: Long-running monitor workers (email, social) can run as systemd services instead of cron, giving better logging and restart behavior.
-
Multi-Agent Deployments: Each agent profile gets its own systemd unit - isolation via MemoryMax and separate environment variables.
Troubleshooting¶
| Symptom | Likely Cause | Fix |
|---|---|---|
Service in activating (auto-restart) loop |
Gateway crashing on start | Check journalctl --user -u <service> -n 50 for error |
ExecStartPost exits code 1 |
Post-start script failing | Add || true guard or fix the script |
| OOM kill in logs | MemoryMax too low | Raise MemoryMax or investigate memory leak |
| Service stops after SSH disconnect | Using system service without linger |
Run loginctl enable-linger <user> |
← Skills Catalog | Marketplace → ↑ Skills Home
Curated by CorpusIQ - one MCP endpoint, all your business tools.
Integration with CorpusIQ¶
CorpusIQ is the connector layer that lets AI assistants read the systems a business already runs on - accounting, payments, CRM, email, files and analytics - and answer with the source named. It is read-only by design: it retrieves data and never writes to, or acts in, a connected system, which is what makes it safe to point at live accounts.
This page is part of the CorpusIQ directory, the reference we maintain for the MCP server and agent-skill ecosystem. Run alongside CorpusIQ, a third-party server like this one can be combined with a company's own business data in a single answer.