Building ZeroClaw on Raspberry Pi Zero W

Complete guide to compile ZeroClaw on Raspberry Pi Zero W (512MB RAM, ARMv6).

Last verified: February 28, 2026.

Overview

The Raspberry Pi Zero W is a constrained device with only 512MB of RAM. Compiling Rust on this device requires special considerations:

Requirement	Minimum	Recommended
RAM	512MB	512MB + 2GB swap
Free disk	4GB	6GB+
OS	Raspberry Pi OS (32-bit)	Raspberry Pi OS Lite (32-bit)
Architecture	armv6l	armv6l

Important: This guide assumes you are building natively on the Pi Zero W, not cross-compiling from a more powerful machine.

Target Abi: gnueabihf vs musleabihf

When building for Raspberry Pi Zero W, you have two target ABI choices:

ABI	Full Target	Description	Binary Size	Static Linking	Recommended
musleabihf	`armv6l-unknown-linux-musleabihf`	Uses musl libc	Smaller	Yes (fully static)	Yes
gnueabihf	`armv6l-unknown-linux-gnueabihf`	Uses glibc	Larger	Partial	No

Why musleabihf is preferred:

Smaller binary size — musl produces more compact binaries, critical for embedded devices
Fully static linking — No runtime dependency on system libc versions; binary works across different Raspberry Pi OS versions
Better security — Smaller attack surface with musl's minimal libc implementation
Portability — Static binary runs on any ARMv6 Linux distribution without compatibility concerns

Trade-offs:

musleabihf builds may take slightly longer to compile
Some niche dependencies may not support musl (ZeroClaw's dependencies are musl-compatible)

Option A: Native Compilation

Step 1: Prepare System

First, ensure your system is up to date:

sudo apt update
sudo apt upgrade -y

Step 2: Add Swap Space (Critical)

Due to limited RAM (512MB), adding swap is mandatory for successful compilation:

# Create 2GB swap file
sudo fallocate -l 2G /swapfile

# Set proper permissions
sudo chmod 600 /swapfile

# Format as swap
sudo mkswap /swapfile

# Enable swap
sudo swapon /swapfile

# Verify swap is active
free -h

To make swap persistent across reboots:

echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Step 3: Install Rust Toolchain

Install Rust via rustup:

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

# Source the environment
source $HOME/.cargo/env

# Verify installation
rustc --version
cargo --version

Step 4: Install Build Dependencies

Install required system packages:

sudo apt install -y \
    build-essential \
    pkg-config \
    libssl-dev \
    libsqlite3-dev \
    git \
    curl

Step 5: Clone ZeroClaw Repository

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

Or if you already have the repository:

cd /path/to/zeroclaw
git fetch --all
git checkout main
git pull

Step 6: Configure Build for Low Memory

ZeroClaw's Cargo.toml is already configured for low-memory devices (codegen-units = 1 in release profile). For additional safety on Pi Zero W:

# Set CARGO_BUILD_JOBS=1 to prevent memory exhaustion
export CARGO_BUILD_JOBS=1

Step 7: Choose Target ABI and Build ZeroClaw

This step will take 30-60 minutes depending on your storage speed and chosen target.

For native build, the default target is gnueabihf (matches your system):

# Build with default target (gnueabihf)
cargo build --release

# Alternative: Build with specific features only (smaller binary)
cargo build --release --no-default-features --features "wasm-tools"

For musleabihf (smaller, static binary — requires musl tools):

# Install musl development tools
sudo apt install -y musl-tools musl-dev

# Add musl target
rustup target add armv6l-unknown-linux-musleabihf

# Build for musleabihf (smaller, static binary)
cargo build --release --target armv6l-unknown-linux-musleabihf

Note: If the build fails with "out of memory" errors, you may need to increase swap size to 4GB:

sudo swapoff /swapfile
sudo rm /swapfile
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Then retry the build.

Step 8: Install ZeroClaw

# For gnueabihf (default target)
sudo cp target/release/zeroclaw /usr/local/bin/

# For musleabihf
sudo cp target/armv6l-unknown-linux-musleabihf/release/zeroclaw /usr/local/bin/

# Verify installation
zeroclaw --version

# Verify binary is statically linked (musleabihf only)
file /usr/local/bin/zeroclaw
# Should show "statically linked" for musleabihf

Option B: Cross-Compilation (Recommended)

For faster builds, cross-compile from a more powerful machine (Linux, macOS, or Windows). A native build on Pi Zero W can take 30-60 minutes, while cross-compilation typically completes in 5-10 minutes.

Why Cross-Compile?

Factor	Native (Pi Zero W)	Cross-Compile (x86_64)
Build time	30-60 minutes	5-10 minutes
RAM required	512MB + 2GB swap	4GB+ typical
CPU load	High (single core)	Low relative to host
Iteration speed	Slow	Fast

Prerequisites

On your build host (Linux x86_64 example):

# Install ARM cross-compilation toolchain
# Note: We use gcc-arm-linux-gnueabihf as the linker tool,
# but Rust's target configuration produces a static musl binary
sudo apt install -y musl-tools musl-dev gcc-arm-linux-gnueabihf

# Verify cross-compiler is available
arm-linux-gnueabihf-gcc --version

Why gnueabihf for musl builds?

Pure arm-linux-musleabihf-gcc cross-compilers are not available in standard Ubuntu/Debian repositories. The workaround:

Use gcc-arm-linux-gnueabihf as the linker tool (available in repos)
Rust's target spec (armv6l-unknown-linux-musleabihf.json) sets env: "musl"
Static linking (-C link-arg=-static) eliminates glibc dependency
Result: a portable static musl binary that works on any ARMv6 Linux

macOS: Install via Homebrew:

brew install musl-cross

Windows: Use WSL2 or install mingw-w64 cross-compilers.

Build for musleabihf (Recommended)

The ZeroClaw repository includes pre-configured .cargo/config.toml and .cargo/armv6l-unknown-linux-musleabihf.json for static linking.

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

# Add ARMv6 musl target to rustup
rustup target add armv6l-unknown-linux-musleabihf

# The repository's .cargo/config.toml already contains:
# [target.armv6l-unknown-linux-musleabihf]
# rustflags = ["-C", "link-arg=-static"]
#
# And .cargo/armv6l-unknown-linux-musleabihf.json provides
# the target specification for proper ARMv6 support.

# Build for target (static binary, no runtime dependencies)
cargo build --release --target armv6l-unknown-linux-musleabihf

Understanding Static Linking Benefits

The rustflags = ["-C", "link-arg=-static"] flag ensures fully static linking:

Benefit	Description
No libc dependency	Binary works on any ARMv6 Linux distribution
Smaller size	musl produces more compact binaries than glibc
Version-agnostic	Runs on Raspberry Pi OS Bullseye, Bookworm, or future versions
Secure by default	Reduced attack surface with musl's minimal libc
Portable	Same binary works across different Pi models with ARMv6

Verify Static Linking

After building, confirm the binary is statically linked:

file target/armv6l-unknown-linux-musleabihf/release/zeroclaw
# Output should include: "statically linked"

ldd target/armv6l-unknown-linux-musleabihf/release/zeroclaw
# Output should be: "not a dynamic executable"

Build for gnueabihf (Alternative)

If you need dynamic linking or have specific glibc dependencies:

# Add ARMv6 glibc target
rustup target add armv6l-unknown-linux-gnueabihf

# Build for target
cargo build --release --target armv6l-unknown-linux-gnueabihf

Note: gnueabihf binaries will be larger and depend on the target system's glibc version.

Build with Custom Features

Reduce binary size by building only needed features:

# Minimal build (agent core only)
cargo build --release --target armv6l-unknown-linux-musleabihf --no-default-features

# Specific feature set
cargo build --release --target armv6l-unknown-linux-musleabihf --features "telegram,discord"

# Use dist profile for size-optimized binary
cargo build --profile dist --target armv6l-unknown-linux-musleabihf

Transfer to Pi Zero W

# From build machine (adjust target as needed)
scp target/armv6l-unknown-linux-musleabihf/release/zeroclaw pi@zero-w-ip:/home/pi/

# On Pi Zero W
sudo mv ~/zeroclaw /usr/local/bin/
sudo chmod +x /usr/local/bin/zeroclaw
zeroclaw --version

# Verify it's statically linked (no dependencies on target system)
ldd /usr/local/bin/zeroclaw
# Should output: "not a dynamic executable"

Cross-Compilation Workflow Summary

┌─────────────────┐     Clone/Fork     ┌─────────────────────┐
│  ZeroClaw Repo  │ ──────────────────> │   Your Build Host   │
│  (GitHub)       │                    │  (Linux/macOS/Win)  │
└─────────────────┘                    └─────────────────────┘
                                                │
                                                │ rustup target add
                                                │ cargo build --release
                                                ▼
                                        ┌─────────────────────┐
                                        │  Static Binary      │
                                        │  (armv6l-musl)      │
                                        └─────────────────────┘
                                                │
                                                │ scp / rsync
                                                ▼
                                        ┌─────────────────────┐
                                        │  Raspberry Pi       │
                                        │  Zero W             │
                                        │  /usr/local/bin/    │
                                        └─────────────────────┘

Post-Installation Configuration

Initialize ZeroClaw

# Run interactive setup
zeroclaw setup

# Or configure manually
mkdir -p ~/.config/zeroclaw
nano ~/.config/zeroclaw/config.toml

Enable Hardware Features (Optional)

For Raspberry Pi GPIO support:

# Build with peripheral-rpi feature (native build only)
cargo build --release --features peripheral-rpi

Run as System Service (Optional)

Create a systemd service:

sudo nano /etc/systemd/system/zeroclaw.service

Add the following:

[Unit]
Description=ZeroClaw AI Agent
After=network.target

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi
ExecStart=/usr/local/bin/zeroclaw agent
Restart=on-failure

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable zeroclaw
sudo systemctl start zeroclaw

Troubleshooting

Build Fails with "Out of Memory"

Solution: Increase swap size:

sudo swapoff /swapfile
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Linker Errors

Solution: Ensure proper toolchain is installed:

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

SSL/TLS Errors at Runtime

Solution: Install SSL certificates:

sudo apt install -y ca-certificates

Binary Too Large

Solution: Build with minimal features:

cargo build --release --no-default-features --features "wasm-tools"

Or use the .dist profile:

cargo build --profile dist

Performance Tips

Use Lite OS: Raspberry Pi OS Lite has lower overhead
Overclock (Optional): Add arm_freq=1000 to /boot/config.txt
Disable GUI: sudo systemctl disable lightdm (if using desktop)
Use external storage: Build on USB 3.0 drive if available

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Building ZeroClaw on Raspberry Pi Zero W

Overview

Target Abi: gnueabihf vs musleabihf

Option A: Native Compilation

Step 1: Prepare System

Step 2: Add Swap Space (Critical)

Step 3: Install Rust Toolchain

Step 4: Install Build Dependencies

Step 5: Clone ZeroClaw Repository

Step 6: Configure Build for Low Memory

Step 7: Choose Target ABI and Build ZeroClaw

Step 8: Install ZeroClaw

Option B: Cross-Compilation (Recommended)

Why Cross-Compile?

Prerequisites

Build for musleabihf (Recommended)

Understanding Static Linking Benefits

Verify Static Linking

Build for gnueabihf (Alternative)

Build with Custom Features

Transfer to Pi Zero W

Cross-Compilation Workflow Summary

Post-Installation Configuration

Initialize ZeroClaw

Enable Hardware Features (Optional)

Run as System Service (Optional)

Troubleshooting

Build Fails with "Out of Memory"

Linker Errors

SSL/TLS Errors at Runtime

Binary Too Large

Performance Tips

Related Documents

References

FilesExpand file tree

raspberry-pi-zero-w-build.md

Latest commit

History

raspberry-pi-zero-w-build.md

File metadata and controls

Building ZeroClaw on Raspberry Pi Zero W

Overview

Target Abi: gnueabihf vs musleabihf

Option A: Native Compilation

Step 1: Prepare System

Step 2: Add Swap Space (Critical)

Step 3: Install Rust Toolchain

Step 4: Install Build Dependencies

Step 5: Clone ZeroClaw Repository

Step 6: Configure Build for Low Memory

Step 7: Choose Target ABI and Build ZeroClaw

Step 8: Install ZeroClaw

Option B: Cross-Compilation (Recommended)

Why Cross-Compile?

Prerequisites

Build for musleabihf (Recommended)

Understanding Static Linking Benefits

Verify Static Linking

Build for gnueabihf (Alternative)

Build with Custom Features

Transfer to Pi Zero W

Cross-Compilation Workflow Summary

Post-Installation Configuration

Initialize ZeroClaw

Enable Hardware Features (Optional)

Run as System Service (Optional)

Troubleshooting

Build Fails with "Out of Memory"

Linker Errors

SSL/TLS Errors at Runtime

Binary Too Large

Performance Tips

Related Documents

References