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 processorTested 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 supportedFirmware: Embedded builds for microcontrollers (limited feature set)Experimental: Community-supported, may require manual configuration

Installation Methods

Homebrew (Recommended)
Clone + Bootstrap
Cargo Install
Remote One-Liner
Docker

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

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

Validates system requirements (RAM, disk space)
Optionally installs Rust toolchain via rustup
Builds ZeroClaw with optimized release profile:
```
cargo build --release --locked
```

Installs binary to ~/.cargo/bin/:

cargo install --path . --force --locked

Bootstrap Options

# 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.

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

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:

Detects if running in a git repo
Clones temp workspace if needed
Builds and installs ZeroClaw
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.

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)
Native Windows

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.

Install Visual Studio Build Tools (C++ workload)

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

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

Update System

sudo apt-get update
sudo apt-get upgrade -y

Install Rust

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

Install Build Dependencies

sudo apt-get install -y build-essential pkg-config libssl-dev git

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

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
Cargo
Source
Self-Update (Coming Soon)

brew upgrade zeroclaw

cargo install zeroclaw --force

cd zeroclaw
git pull origin main
./bootstrap.sh

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.

Getting Started

Core Concepts

Guides

Operations

​Installation Guide

​System Requirements

​Minimum Runtime Requirements

RAM

Disk Space

CPU

OS

​Supported Platforms

​Installation Methods

​macOS and Linux (Homebrew/Linuxbrew)

​Update to Latest

​From Source (All Platforms)

​Bootstrap Options

​Advanced Options

​Via Cargo (Rust Package Manager)

​Install Specific Version

​Install with Features

​Direct Install (No Git Clone)

​Legacy Install Script

​Containerized Deployment

​Quick Start

​Manual Docker Build

​Docker Compose

​Advanced Docker Options

​Platform-Specific Instructions

​Linux

​macOS

​Windows

​Raspberry Pi

​Android (Termux)

​Embedded & Microcontroller Firmware

​ESP32

​STM32 Nucleo

​Arduino

​Verification

​Updating ZeroClaw

​Uninstallation

​Next Steps

Quick Start

Configuration

Build docs developers (and LLMs) love

Installation Guide

System Requirements

Minimum Runtime Requirements

Supported Platforms

Installation Methods

macOS and Linux (Homebrew/Linuxbrew)

Update to Latest

From Source (All Platforms)

Bootstrap Options

Advanced Options

Via Cargo (Rust Package Manager)

Install Specific Version

Install with Features

Direct Install (No Git Clone)

Legacy Install Script

Containerized Deployment

Quick Start

Manual Docker Build

Docker Compose

Advanced Docker Options

Platform-Specific Instructions

Linux

macOS

Windows

Raspberry Pi

Android (Termux)

Embedded & Microcontroller Firmware

ESP32

STM32 Nucleo

Arduino

Verification

Updating ZeroClaw

Uninstallation

Next Steps