Linux

Install, update, run as a service, and uninstall, all Linux distributions.

Install

./install.sh

That is the whole install. Run it from a clone, or pipe it from curl:

sh

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash

The installer detects your distribution and architecture, picks a prebuilt binary or builds from source (interactive by default; non-interactive shells take the prebuilt when available), installs to ~/.cargo/bin/zeroclaw, and offers to run zeroclaw quickstart for first-time setup. Pass --help for the full flag reference, or --skip-quickstart to install only.

Homebrew (Linuxbrew)

sh

brew install zeroclaw

Homebrew-on-Linux installs follow Homebrew's service path convention, your workspace lives under $HOMEBREW_PREFIX/var/zeroclaw/ instead of ~/.zeroclaw/. See Service management for why this matters.

NixOS

A multi-instance NixOS module is shipped in-tree. See NixOS.

A note on cargo binstall and nix run

Neither works yet. cargo binstall zeroclaw resolves crate metadata from crates.io, but ZeroClaw is not published there (publish = false), so there is nothing for it to fetch; nix run github:zeroclaw-labs/zeroclaw does not launch the agent because the flake exposes only a dev toolchain, not a runnable package (#5987). install.sh already does what binstall would (download a prebuilt release binary), so it remains the supported one-liner.

System dependencies

The core binary is statically linked where possible. Some features require system libraries:

The hardware feature (GPIO / I2C / SPI on a Pi) uses the pure-Rust rppal driver and needs no extra system library; it talks to /dev/gpiomem, /dev/spidev*, and /dev/i2c-* directly. What it does need is device access: enable the SPI/I2C interfaces and put the service user in the gpio, spi, and i2c groups (see SBC / Raspberry Pi below).

Most deployments don't need any of these.

Running as a service

Systemd is the default. OpenRC is detected and supported as a fallback.

sh

zeroclaw service install
zeroclaw service start
zeroclaw service status

Logs go to the systemd journal by default:

sh

journalctl --user -u zeroclaw -f

Full details: Service management.

SBC / Raspberry Pi

On a Raspberry Pi or similar SBC, build with the hardware feature:

sh

./install.sh --source --features hardware

For hardware access without running as root, the service user needs the gpio, spi, and i2c groups. The user-level unit that zeroclaw service install writes does not set these; use the system-level Pi unit template at scripts/zeroclaw.service, which includes SupplementaryGroups=gpio spi i2c. Either way, verify your user is in those groups:

sh

getent group gpio spi i2c
sudo usermod -aG gpio,spi,i2c $USER
# re-login for group changes to take effect

Update

Re-run the installer, it detects the existing install and upgrades in place:

sh

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash -s -- --skip-quickstart

Or from a clone:

sh

cd /path/to/zeroclaw
git pull
./install.sh --skip-quickstart

If installed via Homebrew instead:

sh

brew update && brew upgrade zeroclaw

After updating, restart the service:

sh

zeroclaw service restart

Uninstall

If you installed with the bootstrap script, use the same script to uninstall:

sh

./install.sh --uninstall

Stop and remove the service:

sh

zeroclaw service stop
zeroclaw service uninstall

Remove the binary:

sh

# cargo install / bootstrap
rm ~/.cargo/bin/zeroclaw

# Homebrew
brew uninstall zeroclaw

Remove config and workspace (optional: this deletes conversation history):

sh

rm -rf ~/.zeroclaw ~/.config/zeroclaw

Next

• Service management: systemd unit details, logs, auto-start
• Quickstart: once installed, getting talking
• Operations → Overview: running in production