Install and manage ZeroClaw as a systemd user-level service on Linux or a system-wide OpenRC service on Alpine, including config paths and log locations.
Use this file to discover all available pages before exploring further.
ZeroClaw can manage itself as a background service using your operating system’s init system. On Linux distributions that run systemd, the service installs at the user level — no sudo required. On Alpine Linux (and other OpenRC-based distributions), the service installs system-wide and requires root. ZeroClaw auto-detects which init system is present and uses the correct backend automatically.
Init system
Scope
Config path
Requires sudo
systemd (default on Linux)
User-level
~/.zeroclaw/config.toml
No
OpenRC (Alpine Linux)
System-wide
/etc/zeroclaw/config.toml
Yes
systemd (Linux)
OpenRC (Alpine)
Systemd is the default init system on most Linux distributions (Debian, Ubuntu, Fedora, Arch, and others). ZeroClaw installs as a user-level systemd unit, which means it runs under your own account with no elevated privileges.
1
Install the service unit
zeroclaw service install
This registers a zeroclaw.service unit file under ~/.config/systemd/user/ and enables it for your session.
Systemd routes service output to the journal. Use journalctl to follow logs in real time:
journalctl --user -u zeroclaw.service -f
To view the last 100 lines without following:
journalctl --user -u zeroclaw.service -n 100
On Alpine Linux, ZeroClaw uses OpenRC for system-wide service management. All operations require sudo or root access. The service runs under a dedicated zeroclaw system user (least privilege).
1
Install the service (requires sudo)
sudo zeroclaw service install
This creates:
Init script: /etc/init.d/zeroclaw
Config directory: /etc/zeroclaw/
Log directory: /var/log/zeroclaw/
The installer automatically migrates existing runtime state from your user setup when available and sets correct ownership for the zeroclaw service user. If no prior state exists, create /etc/zeroclaw/config.toml before starting the service.
sudo rc-service zeroclaw stopsudo rc-update del zeroclaw defaultsudo zeroclaw service uninstall
OpenRC services are system-wide only — there is no user-level equivalent. All operations require sudo or root. If the zeroclaw system user does not exist, sudo zeroclaw service install will exit with instructions to create it.
If the service becomes unhealthy, follow this sequence to restore it cleanly:
# 1. Snapshot current statezeroclaw statuszeroclaw doctorzeroclaw channel doctor# 2. Check service statuszeroclaw service status# 3. Restart cleanlyzeroclaw service stopzeroclaw service start# 4. Verify recoveryzeroclaw statuszeroclaw channel doctor
If channels continue to fail after a restart, verify allowlists and credentials in your config file.