Installation Guide

Detailed installation instructions for all platforms and hardware configurations

Installation Guide

Comprehensive installation instructions for ZeroClaw across all supported platforms.

System Requirements

Minimum Runtime Requirements

RAM

< 5MB for basic agent operations

(Build-time: ~2GB recommended)

Disk Space

~9MB for binary + dependencies

(Build-time: ~6GB free space)

CPU

Any ARM, x86_64, or RISC-V processor

Tested down to 0.8GHz single-core

OS

Linux, macOS, Windows, or bare-metal

(Firmware available for microcontrollers)

Supported Platforms

Platform	Architecture	Status	Notes
Linux	x86_64, aarch64, armv7	✅ Tier 1	Debian, Ubuntu, Fedora, Arch, Alpine
macOS	x86_64, aarch64 (Apple Silicon)	✅ Tier 1	macOS 10.15+
Windows	x86_64	✅ Tier 1	Native and WSL2
Raspberry Pi	armv7, aarch64	✅ Tier 1	Pi 3, 4, 5, Zero 2 W (GPIO support)
Docker	Multi-arch	✅ Tier 1	x86_64, aarch64 images
ESP32	xtensa	⚙️ Firmware	zeroclaw-esp32, zeroclaw-esp32-ui
STM32	ARM Cortex-M	⚙️ Firmware	Nucleo boards (zeroclaw-nucleo)
Arduino	AVR, ARM	⚙️ Firmware	zeroclaw-arduino, zeroclaw-uno-q-bridge
Android/Termux	aarch64, armv7	✅ Experimental	Source builds only

Tier 1: Pre-built binaries available, CI-tested, officially supported

Firmware: Embedded builds for microcontrollers (limited feature set)

Experimental: Community-supported, may require manual configuration

Installation Methods

Homebrew (Recommended)

macOS and Linux (Homebrew/Linuxbrew)

Fastest method with pre-built binaries:

brew install zeroclaw

Verify installation:

zeroclaw --version

Homebrew handles PATH configuration automatically. No additional setup needed.

Update to Latest

brew upgrade zeroclaw

Clone + Bootstrap

From Source (All Platforms)

Clone the repository and run the bootstrap script:

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./bootstrap.sh

What bootstrap.sh does

1. Validates system requirements (RAM, disk space)
2. Optionally installs Rust toolchain via rustup
3. Builds ZeroClaw with optimized release profile:
   cargo build --release --locked
   
4. Installs binary to ~/.cargo/bin/:
   cargo install --path . --force --locked
   

Bootstrap Options

Full Environment Setup

# Install system dependencies + Rust + ZeroClaw
./bootstrap.sh --install-system-deps --install-rust

Advanced Options

# Force source build (skip pre-built check)
./bootstrap.sh --force-source-build

# Binary-only (fail if no release asset)
./bootstrap.sh --prebuilt-only

# Custom Cargo features
./bootstrap.sh --cargo-features "hardware,channel-matrix,browser-native"

# Skip build step (dev mode)
./bootstrap.sh --skip-build

Source builds require ~2GB RAM and ~6GB disk. Use --prefer-prebuilt on constrained systems.

Cargo Install

Via Cargo (Rust Package Manager)

If you already have Rust installed:

cargo install zeroclaw

This compiles from the latest crates.io release.

Install Specific Version

cargo install zeroclaw --version 0.1.8

Install with Features

cargo install zeroclaw --features "hardware,channel-matrix,peripheral-rpi"

Available Features:

• hardware — USB device enumeration, serial support
• channel-matrix — Matrix E2EE chat support
• channel-lark — Lark/Feishu/DingTalk channels
• memory-postgres — PostgreSQL memory backend
• peripheral-rpi — Raspberry Pi GPIO support
• browser-native — Selenium/CDP browser automation
• runtime-wasm — WASM tool sandboxing
• wasm-tools — WASM plugin loader
• whatsapp-web — WhatsApp Web client
• probe — STM32/Nucleo memory probing (probe-rs)
• rag-pdf — PDF ingestion for RAG

Remote One-Liner

Direct Install (No Git Clone)

For quick deployment on remote servers:

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/bootstrap.sh | bash

This automatically:

1. Detects if running in a git repo
2. Clones temp workspace if needed
3. Builds and installs ZeroClaw
4. Cleans up temp files

Review scripts before piping to bash in production environments:

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/bootstrap.sh > bootstrap.sh
less bootstrap.sh  # Review
bash bootstrap.sh

Legacy Install Script

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

This legacy endpoint forwards to bootstrap.sh on newer releases.

Docker

Containerized Deployment

Quick Start

./bootstrap.sh --docker

This builds a local image and launches onboarding in a container with persistent storage in ./.zeroclaw-docker/.

Manual Docker Build

# Build image
docker build -t zeroclaw:local .

# Run onboarding
docker run -it --rm \
  -v zeroclaw-data:/root/.zeroclaw \
  zeroclaw:local onboard

# Start gateway
docker run -d --name zeroclaw-gateway \
  -p 3000:3000 \
  -v zeroclaw-data:/root/.zeroclaw \
  zeroclaw:local gateway

Docker Compose

docker-compose.yml

version: '3.8'
services:
  zeroclaw:
    build: .
    container_name: zeroclaw-agent
    ports:
      - "3000:3000"
    volumes:
      - zeroclaw-config:/root/.zeroclaw
      - zeroclaw-workspace:/workspace
    environment:
      - API_KEY=${API_KEY}
      - PROVIDER=openrouter
      - ZEROCLAW_GATEWAY_HOST=0.0.0.0
    restart: unless-stopped

volumes:
  zeroclaw-config:
  zeroclaw-workspace:

# Start services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Advanced Docker Options

# Reset existing containers/volumes
./bootstrap.sh --docker --docker-reset

# Seed config from host
./bootstrap.sh --docker --docker-config ./config.toml --docker-secret-key ./.secret_key

# Start persistent daemon
./bootstrap.sh --docker --docker-daemon

# Custom Cargo features in Docker build
ZEROCLAW_DOCKER_CARGO_FEATURES="hardware,browser-native" ./bootstrap.sh --docker

Use Podman instead of Docker by setting:

export ZEROCLAW_CONTAINER_CLI=podman
./bootstrap.sh --docker

Platform-Specific Instructions

Linux

Debian/Ubuntu

# Install build dependencies
sudo apt-get update
sudo apt-get install -y build-essential pkg-config libssl-dev git curl

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install ZeroClaw
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./bootstrap.sh

Optional features:

# Hardware support (USB, serial)
sudo apt-get install -y libudev-dev

# Browser automation
sudo apt-get install -y chromium-browser chromium-chromedriver

Fedora/RHEL/CentOS

# Install build dependencies
sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y pkg-config openssl-devel git curl

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install ZeroClaw
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./bootstrap.sh

Arch Linux

# Install dependencies
sudo pacman -Syu base-devel openssl git curl

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install ZeroClaw
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./bootstrap.sh

Alpine Linux

# Install dependencies
apk add --no-cache build-base openssl-dev git curl bash

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install ZeroClaw
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./bootstrap.sh

Alpine uses musl libc. Some features may require additional packages:

apk add --no-cache pkgconfig libudev-zero-dev

macOS

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install ZeroClaw
brew install zeroclaw

Or from source:

# Install Xcode Command Line Tools
xcode-select --install

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Clone and build
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./bootstrap.sh

macOS may require granting permissions for terminal access to folders. Go to System Preferences → Security & Privacy → Files and Folders if you encounter permission errors.

Windows

WSL2 (Recommended)

Install Windows Subsystem for Linux 2:

wsl --install -d Ubuntu

Then follow Linux (Ubuntu) instructions above.

WSL2 provides the best compatibility and performance for Rust development on Windows.

Native Windows

1. Install Visual Studio Build Tools (C++ workload)
2. Install Rust for Windows:
   # Download and run rustup-init.exe
   Invoke-WebRequest -Uri https://win.rustup.rs/x86_64 -OutFile rustup-init.exe
   .\rustup-init.exe
   
3. Clone and build:
   git clone https://github.com/zeroclaw-labs/zeroclaw.git
   cd zeroclaw
   cargo build --release
   cargo install --path . --force
   

Native Windows builds have limited feature support (no GPIO, some channel limitations).

Raspberry Pi

1. Update System

   sudo apt-get update
   sudo apt-get upgrade -y
   
2. Install Rust

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   source $HOME/.cargo/env
   
3. Install Build Dependencies

   sudo apt-get install -y build-essential pkg-config libssl-dev git
   
4. Use Pre-built Binary (Recommended)

   Raspberry Pi 3/4 have limited RAM. Use pre-built binaries:

   git clone https://github.com/zeroclaw-labs/zeroclaw.git
   cd zeroclaw
   ./bootstrap.sh --prefer-prebuilt
   

   If source build is required, enable swap:

   sudo dphys-swapfile swapoff
   sudo nano /etc/dphys-swapfile  # Set CONF_SWAPSIZE=2048
   sudo dphys-swapfile setup
   sudo dphys-swapfile swapon
   
5. Enable GPIO Support

   Install with GPIO peripheral support:

   cargo install zeroclaw --features peripheral-rpi
   

   Or in source builds:

   ./bootstrap.sh --cargo-features "peripheral-rpi"
   

Raspberry Pi GPIO requires running as root or in the gpio group:

sudo usermod -a -G gpio $USER
# Log out and back in for group change to take effect

Android (Termux)

Android/Termux support is experimental. Some features (hardware, some channels) are unavailable.

# Install Termux from F-Droid (not Google Play)
# Inside Termux:

pkg update && pkg upgrade
pkg install rust git binutils

# Clone and build
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
cargo build --release --locked
cargo install --path . --force

Termux builds use target_os="android" and exclude nusb (USB enumeration) to avoid compilation errors.

Embedded & Microcontroller Firmware

ESP32

ZeroClaw firmware for ESP32 with optional UI:

cd firmware/zeroclaw-esp32

# Install ESP-IDF toolchain
. $HOME/esp/esp-idf/export.sh

# Build and flash
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor

See firmware/zeroclaw-esp32/README.md for detailed setup.

STM32 Nucleo

cd firmware/zeroclaw-nucleo

# Install ARM toolchain
sudo apt-get install gcc-arm-none-eabi

# Build
cargo build --release --target thumbv7em-none-eabihf

# Flash with probe-rs
cargo run --release

See docs/nucleo-setup.md.

Arduino

cd firmware/zeroclaw-arduino

# Open in Arduino IDE and flash
# Or use arduino-cli:
arduino-cli compile --fqbn arduino:avr:uno zeroclaw-arduino.ino
arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:avr:uno

Verification

After installation, verify ZeroClaw is working:

# Check version
zeroclaw --version

# Run health check
zeroclaw doctor

# Test configuration
zeroclaw config export

Expected output:

zeroclaw 0.1.8
Zero overhead. Zero compromise. 100% Rust.

Updating ZeroClaw

Homebrew

brew upgrade zeroclaw

Cargo

cargo install zeroclaw --force

Source

cd zeroclaw
git pull origin main
./bootstrap.sh

Self-Update (Coming Soon)

zeroclaw update

Self-update command is planned for v0.2.0.

Uninstallation

# Remove binary
cargo uninstall zeroclaw

# Or if installed via Homebrew
brew uninstall zeroclaw

# Remove config and data (optional)
rm -rf ~/.zeroclaw

Removing ~/.zeroclaw deletes all configuration, credentials, and conversation history. Back up important data first.

Next Steps

Quick Start

Run your first agent in under 5 minutes

Configuration

Configure providers, channels, and runtime options