02.1 Installation

Installation

Relevant source files

The following files were used as context for generating this wiki page:

Purpose and Scope

This page provides detailed installation instructions for ZeroClaw, covering all supported installation methods: native binary compilation from source, Docker deployment (pre-built and custom builds), and automated setup via the bootstrap script. For initial configuration after installation, see Onboarding Wizard. For production deployment considerations, see Production Configuration.

Prerequisites Overview

ZeroClaw has different prerequisites depending on your installation method and operating system. The table below summarizes requirements:

Component	Windows	Linux	macOS	When Required
Rust toolchain	Required	Required	Required	Native compilation
Visual Studio Build Tools	Required	—	—	Native compilation (Windows)
build-essential / pkg-config	—	Required	—	Native compilation (Linux)
Xcode Command Line Tools	—	—	Required	Native compilation (macOS)
Docker	Optional	Optional	Optional	Docker runtime (`runtime.kind = "docker"`)
Git	Recommended	Recommended	Recommended	Source checkout

Sources: README.md:99-166

Installation Method Decision Flow

flowchart TD
    Start["Choose Installation Method"]
    
    Start --> Q1{"Fresh system<br/>or existing dev<br/>environment?"}
    
    Q1 -->|"Fresh system"| Bootstrap["Use bootstrap.sh"]
    Q1 -->|"Existing dev"| Q2{"Docker available?"}
    
    Q2 -->|"Yes, prefer containers"| DockerPath["Docker Deployment"]
    Q2 -->|"No, or prefer native"| NativePath["Native Compilation"]
    
    Bootstrap --> BootstrapOpts["./bootstrap.sh<br/>--install-system-deps<br/>--install-rust"]
    BootstrapOpts --> BuildBinary["Automated:<br/>cargo build --release"]
    BootstrapOpts --> InstallBinary["Automated:<br/>cargo install --path ."]
    
    NativePath --> CheckPrereqs["Install Prerequisites"]
    CheckPrereqs --> Clone["git clone zeroclaw"]
    Clone --> CargoLocked["cargo build --release --locked"]
    CargoLocked --> CargoInstall["cargo install --path . --force --locked"]
    
    DockerPath --> PreBuilt{"Use pre-built<br/>image?"}
    PreBuilt -->|"Yes"| PullImage["docker pull<br/>ghcr.io/zeroclaw-labs/zeroclaw:latest"]
    PreBuilt -->|"No, build custom"| DockerBuild["docker build -t zeroclaw ."]
    
    PullImage --> ComposeSetup["Configure<br/>docker-compose.yml"]
    DockerBuild --> ComposeSetup
    ComposeSetup --> DockerUp["docker compose up -d"]
    
    BuildBinary --> Verify["zeroclaw --version"]
    InstallBinary --> Verify
    CargoInstall --> Verify
    DockerUp --> VerifyDocker["docker exec zeroclaw<br/>zeroclaw --version"]
    
    Verify --> NextSteps["Proceed to Onboarding"]
    VerifyDocker --> NextSteps

Installation Method Decision Flow

This diagram shows the three primary installation paths and their decision points. The bootstrap script automates the native compilation path with prerequisite installation.

Sources: README.md:169-252, bootstrap.sh:1-6, docker-compose.yml:1-63

Native Binary Compilation

Native compilation produces a single static binary (zeroclaw) that runs directly on your system without runtime dependencies beyond system libraries.

Windows Prerequisites

Windows requires the Microsoft Visual C++ toolchain for linking and the Rust compiler.

Installation Steps:

Visual Studio Build Tools (provides MSVC linker and Windows SDK):
```
winget install Microsoft.VisualStudio.2022.BuildTools
```
During installation, select the "Desktop development with C++" workload via the Visual Studio Installer.
Rust toolchain:
```
winget install Rustlang.Rustup
```
After installation, open a new terminal and run:
```
rustup default stable
```
Verification:
```
rustc --version
cargo --version
```

Sources: README.md:104-127

Linux Prerequisites

Linux requires build tools and the Rust compiler. Instructions differ by distribution family.

Debian/Ubuntu:

sudo apt install build-essential pkg-config
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Fedora/RHEL/CentOS:

sudo dnf group install development-tools
sudo dnf install pkg-config
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

One-Line System + Rust Installer:

The repository includes a convenience script that installs all prerequisites:

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

Verification:

rustc --version
cargo --version

Sources: README.md:130-166

macOS Prerequisites

macOS requires Xcode Command Line Tools for build tooling and the Rust compiler.

Installation Steps:

Xcode Command Line Tools:
```
xcode-select --install
```

Rust toolchain:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Verification:
```
rustc --version
cargo --version
```

Sources: README.md:130-150

Build Profiles and Memory Requirements

ZeroClaw provides multiple build profiles optimized for different hardware capabilities:

Profile	Invocation	Optimization	Codegen Units	RAM Required	Use Case
release (default)	`cargo build --release`	Size (`opt-level = "z"`)	1	~1GB	Low-memory devices (Raspberry Pi 3)
release-fast	`cargo build --profile release-fast`	Size (`opt-level = "z"`)	8	~16GB	Fast builds on powerful machines
dist	`cargo build --profile dist`	Size (`opt-level = "z"`)	1 + LTO fat	~2GB	Official distribution builds

The default profile uses codegen-units=1 for serialized compilation, which is critical for devices with limited RAM. The build configuration is in Cargo.toml:161-189.

Sources: README.md:164-165, Cargo.toml:161-189

Compilation Steps

After installing prerequisites, compile ZeroClaw from source:

# Clone repository
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw

# Build release binary with locked dependencies
cargo build --release --locked

# Install to ~/.cargo/bin
cargo install --path . --force --locked

# Ensure cargo bin directory is in PATH
export PATH="$HOME/.cargo/bin:$PATH"

The --locked flag ensures dependency versions match Cargo.lock exactly, preventing unexpected version resolution on fresh systems. The --force flag overwrites any existing zeroclaw binary in ~/.cargo/bin.

Development Build (faster, larger binary):

cargo build

Fast Release Build (requires 16GB+ RAM):

cargo build --profile release-fast

Sources: README.md:194-202, README.md:784-794

Build Output Verification

After compilation, verify the binary:

# Check binary size
ls -lh target/release/zeroclaw

# Verify execution
target/release/zeroclaw --version

# Or if installed globally
zeroclaw --version

Expected release binary size: approximately 8-9 MB on arm64, varies by platform and feature flags.

Memory Footprint Benchmarks:

To measure actual runtime memory usage:

/usr/bin/time -l target/release/zeroclaw --help
/usr/bin/time -l target/release/zeroclaw status

Reference measurements (macOS arm64, as of February 2026):

zeroclaw --help: ~0.02s, peak memory ~3.9MB
zeroclaw status: ~0.01s, peak memory ~4.1MB

Sources: README.md:81-98

Troubleshooting Linux OpenSSL Errors

If you encounter openssl-sys build errors on Linux, this typically indicates a dependency version mismatch. ZeroClaw is configured to use rustls for TLS, but transitive dependencies may reference OpenSSL.

Resolution:

git pull  # Ensure latest Cargo.lock
cargo build --release --locked
cargo install --path . --force --locked

The --locked flag forces Cargo to use the exact dependency graph specified in Cargo.lock, avoiding version resolution that might introduce incompatible crate versions.

Sources: README.md:804-814

Docker Deployment

Docker deployment packages ZeroClaw as a container with all runtime dependencies. The official images are multi-stage builds with separate development and production stages.

Docker Image Architecture

flowchart LR
    subgraph "Build Stage (rust:1.93-slim)"
        BuildDeps["Install pkg-config"]
        CopyManifests["Copy Cargo.toml<br/>Cargo.lock<br/>rust-toolchain.toml"]
        DummyBuild["Build dependencies<br/>(cached layer)"]
        CopySource["Copy src/<br/>crates/<br/>benches/"]
        ReleaseCompile["cargo build<br/>--release --locked"]
        StripBinary["strip zeroclaw"]
    end
    
    subgraph "Dev Stage (debian:trixie-slim)"
        DevRuntime["ca-certificates<br/>curl"]
        DevConfig["config.template.toml<br/>Ollama defaults"]
        DevBinary["zeroclaw binary<br/>/usr/local/bin/zeroclaw"]
    end
    
    subgraph "Release Stage (distroless cc-debian13:nonroot)"
        ProdBinary["zeroclaw binary<br/>/usr/local/bin/zeroclaw"]
        ProdConfig["Minimal config.toml<br/>OpenRouter defaults"]
    end
    
    BuildDeps --> CopyManifests
    CopyManifests --> DummyBuild
    DummyBuild --> CopySource
    CopySource --> ReleaseCompile
    ReleaseCompile --> StripBinary
    
    StripBinary --> DevBinary
    StripBinary --> ProdBinary

Docker Multi-Stage Build Architecture

The Dockerfile:1-113 implements a three-stage build:

Builder stage: Compiles the release binary using Rust 1.93-slim with layer caching for dependencies
Dev stage: Debian-based runtime with development tools (curl, ca-certificates)
Release stage: Distroless runtime with minimal attack surface

Sources: Dockerfile:1-113

Using Pre-Built Images

Official images are published to GitHub Container Registry (GHCR) on every main push and release tag.

Pull latest image:

docker pull ghcr.io/zeroclaw-labs/zeroclaw:latest

Pull specific version:

docker pull ghcr.io/zeroclaw-labs/zeroclaw:v0.1.0

Run container interactively:

docker run --rm -it \
  -e API_KEY="your-api-key" \
  -e PROVIDER="openrouter" \
  -p 3000:3000 \
  ghcr.io/zeroclaw-labs/zeroclaw:latest gateway

Images are published by .github/workflows/pub-docker-img.yml with multi-platform support (linux/amd64, linux/arm64) for release tags.

Sources: README.md:13, .github/workflows/pub-docker-img.yml:82-193, docker-compose.yml:10-15

Building Custom Images

To build a custom image from source:

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

# Build development stage (includes dev tools)
docker build --target dev -t zeroclaw:dev .

# Build release stage (minimal distroless)
docker build --target release -t zeroclaw:release .

# Default build (uses release stage)
docker build -t zeroclaw:custom .

Build arguments and cache optimization:

The Dockerfile uses BuildKit mount caches to accelerate rebuilds:

zeroclaw-cargo-registry: Caches downloaded crates
zeroclaw-cargo-git: Caches Git dependencies
zeroclaw-target: Caches compiled artifacts

To leverage caching:

DOCKER_BUILDKIT=1 docker build -t zeroclaw:cached .

Sources: Dockerfile:23-39

Docker Compose Deployment

The repository includes a docker-compose.yml for production deployments with persistent storage and resource limits.

Configuration steps:

Copy and customize compose file:

cp docker-compose.yml docker-compose.custom.yml

Set required environment variables: Create a .env file:

API_KEY=your-actual-api-key
PROVIDER=openrouter
HOST_PORT=3000

Start services:

docker compose -f docker-compose.custom.yml up -d

Verify deployment:

docker compose ps
docker compose logs zeroclaw
docker exec zeroclaw zeroclaw status

Environment variable reference:

Variable	Default	Purpose
`API_KEY`	(empty)	LLM provider API key (required)
`PROVIDER`	`openrouter`	Default provider (see Built-in Providers)
`ZEROCLAW_ALLOW_PUBLIC_BIND`	`true` (in container)	Allow binding to `0.0.0.0` (required for container networking)
`ZEROCLAW_MODEL`	(from config.toml)	Override default model
`ZEROCLAW_GATEWAY_PORT`	`3000`	Internal container port
`HOST_PORT`	`3000`	Host machine port mapping

The compose configuration includes:

Persistent volume (zeroclaw-data) mounted at /zeroclaw-data for workspace and config
Resource limits: 2 CPU cores, 2GB RAM (adjust in docker-compose.yml:42-50)
Health checks: Uses zeroclaw status every 60 seconds
Auto-restart: unless-stopped restart policy

Sources: docker-compose.yml:1-63, Dockerfile:93-113

Docker Environment Configuration

The Docker images use different default configurations based on the stage:

Development stage defaults:

Provider: ollama
Model: llama3.2
Config: dev/config.template.toml with Ollama-specific settings
User: 65534:65534 (nobody:nogroup)

Release stage defaults:

Provider: openrouter
Model: anthropic/claude-sonnet-4-20250514 (from inline config)
Config: Minimal inline config in Dockerfile:43-56
User: 65534:65534 (nobody:nogroup)

Both stages:

Bind to [::] (all interfaces) with allow_public_bind = true for container networking
Workspace: /zeroclaw-data/workspace
Config: /zeroclaw-data/.zeroclaw/config.toml
Default command: gateway

Sources: Dockerfile:59-91, Dockerfile:93-113

Bootstrap Script

The bootstrap script provides automated installation and setup, combining system dependency installation, Rust toolchain setup, and ZeroClaw compilation.

Bootstrap Script Capabilities

flowchart TD
    Entry["./bootstrap.sh"]
    
    Entry --> ParseArgs["Parse Arguments"]
    
    ParseArgs --> CheckFlags{"Flags Present?"}
    
    CheckFlags -->|"--install-system-deps"| DetectOS["Detect OS:<br/>uname -s"]
    CheckFlags -->|"--install-rust"| CheckRust["Check rustc<br/>existence"]
    CheckFlags -->|"--onboard"| OnboardMode["Onboard Mode<br/>Enabled"]
    CheckFlags -->|"No flags"| BuildOnly["Build-Only Mode"]
    
    DetectOS --> InstallDeps["Install Prerequisites:<br/>- build-essential (Linux)<br/>- pkg-config<br/>- Xcode CLT (macOS)"]
    
    CheckRust -->|"Not found"| InstallRustup["curl rustup.rs | sh<br/>Install Rust"]
    CheckRust -->|"Found"| SkipRust["Skip Rust Install"]
    
    InstallDeps --> CargoExists{"Rust Available?"}
    InstallRustup --> CargoExists
    SkipRust --> CargoExists
    
    CargoExists -->|"Yes"| CargoBuildLocked["cargo build<br/>--release --locked"]
    CargoExists -->|"No"| ErrorExit["Error: Rust Required"]
    
    CargoBuildLocked --> CargoInstallForce["cargo install<br/>--path . --force --locked"]
    
    CargoInstallForce --> OnboardCheck{"Onboard Flag?"}
    BuildOnly --> OnboardCheck
    
    OnboardCheck -->|"Yes"| RunOnboard["zeroclaw onboard<br/>--api-key API_KEY<br/>--provider PROVIDER"]
    OnboardCheck -->|"No"| Complete["Installation Complete"]
    
    RunOnboard --> Complete

Bootstrap Script Execution Flow

The script entry point bootstrap.sh:1-6 delegates to scripts/bootstrap.sh which implements the full installation logic.

Sources: bootstrap.sh:1-6, README.md:171-193

Bootstrap Script Usage

Basic usage (build only):

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

Full system setup (fresh machine):

./bootstrap.sh --install-system-deps --install-rust

This option requests sudo privileges to install system packages (build-essential, pkg-config, etc.).

Automated setup with onboarding:

./bootstrap.sh --onboard --api-key "sk-your-api-key" --provider openrouter

Remote one-liner (review before use in production):

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

Common flag combinations:

Use Case	Command
Fresh Linux VM	`./bootstrap.sh --install-system-deps --install-rust --onboard --api-key "sk-..."`
Existing dev environment	`./bootstrap.sh`
CI/CD pipeline	`./bootstrap.sh --install-system-deps --install-rust` (no onboard)
Local development rebuild	`cargo build --release` (skip script)

Sources: README.md:171-193

Post-Installation Steps

After successfully installing ZeroClaw, proceed with initial configuration:

Verify installation:
```
zeroclaw --version
```
Run system diagnostics:
```
zeroclaw doctor
```
This command checks for common configuration issues, missing dependencies, and permission problems.
Configure ZeroClaw:

Quick setup (non-interactive):
```
zeroclaw onboard --api-key sk-your-key --provider openrouter
```
Interactive wizard:
```
zeroclaw onboard --interactive
```
See Onboarding Wizard for detailed configuration guidance.
Test basic functionality:
```
zeroclaw agent -m "Hello, ZeroClaw!"
```
Start the gateway (optional):
```
zeroclaw gateway
```
Default binding: 127.0.0.1:3000

Enable background service (optional):

zeroclaw service install
zeroclaw service status

Sources: README.md:203-252

Installation Verification Checklist

Use this checklist to confirm successful installation:

zeroclaw --version displays version information
zeroclaw status shows system status without errors
zeroclaw doctor reports no critical issues
Configuration directory exists: ~/.zeroclaw/ (native) or /zeroclaw-data/.zeroclaw/ (Docker)
zeroclaw agent -m "test" returns a response (after onboarding)

For Docker installations:

Container runs: docker ps | grep zeroclaw
Health check passes: docker inspect zeroclaw --format='{{.State.Health.Status}}'
Gateway accessible: curl http://localhost:3000/health

Sources: README.md:226-252, docker-compose.yml:53-59

Troubleshooting Common Issues

Issue: `cargo: command not found`

Cause: Rust toolchain not installed or ~/.cargo/bin not in PATH.

Resolution:

# Install Rust if missing
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Add to PATH
export PATH="$HOME/.cargo/bin:$PATH"
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc  # or ~/.zshrc

Sources: README.md:141-150, README.md:200-201

Issue: `linking with cc failed` on Windows

Cause: Visual Studio Build Tools not installed or C++ workload missing.

Resolution:

# Install or repair Build Tools
winget install Microsoft.VisualStudio.2022.BuildTools

# Ensure "Desktop development with C++" workload is selected in installer

Sources: README.md:106-110

Issue: `openssl-sys` build error on Linux

Cause: Dependency version mismatch or missing system OpenSSL development headers.

Resolution:

git pull  # Update to latest Cargo.lock
cargo build --release --locked

If error persists:

# Debian/Ubuntu
sudo apt install libssl-dev pkg-config

# Fedora/RHEL
sudo dnf install openssl-devel pkg-config

Sources: README.md:804-814

Issue: Docker container exits immediately

Cause: Missing required API_KEY environment variable or invalid configuration.

Resolution:

# Check logs
docker logs zeroclaw

# Verify environment variables
docker inspect zeroclaw --format='{{range .Config.Env}}{{println .}}{{end}}'

# Ensure API_KEY is set
docker run -e API_KEY="your-key" ghcr.io/zeroclaw-labs/zeroclaw:latest gateway

Sources: docker-compose.yml:18-32

Issue: Build fails with "out of memory" on low-RAM device

Cause: Default codegen-units=1 can still exceed RAM on devices with <1GB available.

Resolution:

Reduce optimization level temporarily:

# Edit Cargo.toml temporarily, or use this override
CARGO_PROFILE_RELEASE_OPT_LEVEL=s cargo build --release

Or use a machine with more RAM for compilation, then copy the binary to the target device:

# On build machine
cargo build --release --target <target-triple>
scp target/<target-triple>/release/zeroclaw user@target-device:/usr/local/bin/

Sources: README.md:164-165, Cargo.toml:161-168

Issue: Docker image pull fails with "unauthorized"

Cause: GHCR package visibility not set to public, or authentication required.

Resolution:

Images should be public by default. If authentication is required:

# Login to GHCR
echo "$GITHUB_TOKEN" | docker login ghcr.io -u "$GITHUB_USERNAME" --password-stdin

# Pull image
docker pull ghcr.io/zeroclaw-labs/zeroclaw:latest

The publish workflow .github/workflows/pub-docker-img.yml:133-193 attempts to set visibility to public automatically.

Sources: .github/workflows/pub-docker-img.yml:133-193

Next Steps

After successful installation:

Proceed to Onboarding Wizard for initial configuration
Review First Steps for basic usage patterns
Consult Configuration File Reference for advanced configuration

For deployment to production environments, see Production Configuration.

Sources: README.md:203-252

Home

02.1 Installation

Installation

Purpose and Scope

Prerequisites Overview

Installation Method Decision Flow

Native Binary Compilation

Windows Prerequisites

Linux Prerequisites

macOS Prerequisites

Build Profiles and Memory Requirements

Compilation Steps

Build Output Verification

Troubleshooting Linux OpenSSL Errors

Docker Deployment

Docker Image Architecture

Using Pre-Built Images

Building Custom Images

Docker Compose Deployment

Docker Environment Configuration

Bootstrap Script

Bootstrap Script Capabilities

Bootstrap Script Usage

Post-Installation Steps

Installation Verification Checklist

Troubleshooting Common Issues

Issue: cargo: command not found

Issue: linking with cc failed on Windows

Issue: openssl-sys build error on Linux

Issue: Docker container exits immediately

Issue: Build fails with "out of memory" on low-RAM device

Issue: Docker image pull fails with "unauthorized"

Next Steps

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Issue: `cargo: command not found`

Issue: `linking with cc failed` on Windows

Issue: `openssl-sys` build error on Linux