03. Background Service

Chapter 3 of 24 · 15 min

KEY INSIGHT

Running an agent as a background service requires systemd integration, proper user context, and secure logging infrastructure. The agent runs as a systemd service to ensure reliable startup, automatic restart on failure, and proper system integration. Service configuration defines resource limits, user context, and dependency relationships with other system services. Service Configuration The systemd unit file specifies how the service runs and how systemd manages it. The `[Unit]` section declares dependencies and documentation. The `[Service]` section defines the execution environment, restart behavior, and resource constraints. The `[Install]` section specifies how the service connects to system boot targets. ```ini [Unit] Description=OpenCLaw Personal AI Agent After=network-online.target Wants=network-online.target Documentation=https://runlocalai.co/learn [Service] Type=simple User=openclaw Group=openclaw WorkingDirectory=/var/lib/openclaw Environment=OPENCLAW_HOME=/var/lib/openclaw ExecStart=/usr/local/bin/openclaw-agent serve Restart=on-failure RestartSec=10 StandardOutput=journal StandardError=journal WatchdogSec=60 MemoryMax=512M CPUQuota=50% [Install] WantedBy=multi-user.target ``` User Context and Security The agent runs under a dedicated user account with limited permissions. This isolation prevents security vulnerabilities in the agent from affecting other system components. File permissions restrict access to sensitive data. Network access follows the principle of least privilege. Logging goes to the systemd journal rather than plain files. Journalctl provides filtering by severity, time range, and other criteria. Log rotation happens automatically through journald configuration.

Local verification checkpoint

Run the smallest example from this chapter in a local workspace and record the package version, runtime, data path, and observed output. If the result depends on model size, vector count, CPU/GPU backend, or available memory, note that constraint beside the exercise so the lesson remains reproducible.

Local verification checkpoint

EXERCISE

Create a systemd unit file for an OpenCLaw agent that starts after both network connectivity and a local database service. Include watchdog monitoring and resource limits appropriate for a development workstation.