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:

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

The canonical installation paths explain the fast and guided routes, source fallback, app selection, PATH handoff, and the next Quickstart step.

Homebrew (Linuxbrew)

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

The upstream flake provides the ZeroClaw CLI. With Nix and flakes enabled:

nix run github:zeroclaw-labs/zeroclaw -- --version

See NixOS for source builds, the Nixpkgs package, and the multi-instance NixOS service module. For prebuilt binaries, use the installer described above.

CLI-only build (servers)

For a server that only runs agents and channels, install the CLI-only build: the standard features without the dashboard and the web gateway.

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

It builds from source, so the installer sets up Rust when it is missing. In a CLI-only build:

• zeroclaw gateway and zeroclaw desktop say that the dashboard needs the standard build, and zeroclaw status shows the web UI as not included.
• Channels that receive webhooks, such as webhook and Lark, keep their own listeners.
• To update and stay CLI-only, re-run the installer with --cli-only. Releases publish only the standard build, so zeroclaw update stops and explains the choice. zeroclaw update --standard switches to the standard build, which adds the dashboard and web gateway; the daemon then starts the gateway, by default on 127.0.0.1:42617 with pairing required.
• There is no gateway pairing for remote clients. Run zerocode on the server over SSH, or connect with an OIDC token; see Remote setup.

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.

zeroclaw service install
zeroclaw service start
zeroclaw service status

Logs go to the systemd journal by default:

journalctl --user -u zeroclaw -f

Full details: Service management.

SBC / Raspberry Pi

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

./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:

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

Update

Standard release updates carry the native adapters for both minimal and full tool settings. Full stays the default for new and existing installations, including configurations without [tools]. Minimal, eleven tools in Chat and eight in Code/ACP, is opt-in through optional = []. Explicit selections are preserved; named entries select individual extras. Full preserves existing integration prerequisites and permission gates. Plain Cargo-default source builds, including a Homebrew formula that uses only those defaults, can still omit adapters. See minimal/full tools and build recovery.

Re-run the installer, it detects the existing install and upgrades in place (add --cli-only for a CLI-only build):

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

Or from a clone:

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

If installed via Homebrew instead:

brew update && brew upgrade zeroclaw

After updating, restart the service:

zeroclaw service restart

Uninstall

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

./install.sh --uninstall

Stop and remove the service:

zeroclaw service stop
zeroclaw service uninstall

Remove the binary:

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

# Homebrew
brew uninstall zeroclaw

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

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

Next

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