Skip to content

13.2 Native Binary Deployment

Jump to bottom
Nikolay Vyahhi edited this page Feb 19, 2026 · 2 revisions

Native Binary Deployment

Relevant source files

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

Purpose and Scope

This document covers building, installing, and deploying the ZeroClaw native Rust binary across different platforms and architectures. It explains compilation options, build profiles, cross-compilation strategies, and the bootstrap automation script. For containerized deployments, see Docker Deployment. For production hardening and runtime configuration, see Production Configuration.

Overview

ZeroClaw compiles to a single, statically-linked native binary with no runtime dependencies beyond system libraries. The binary supports:

  • ARM, x86-64, and RISC-V architectures
  • Windows, Linux, and macOS operating systems
  • Low-memory compilation (1GB RAM minimum with codegen-units=1)
  • Small binary size (3.4-8.8 MB depending on features and build profile)
  • Fast cold start (< 10ms on modern hardware)
graph TB
    Source["Source Code<br/>(Cargo.toml, src/)"]
    
    subgraph "Build System"
        Cargo["cargo build"]
        Profile1["--release<br/>(codegen-units=1)"]
        Profile2["--profile release-fast<br/>(codegen-units=8)"]
        Profile3["--profile dist<br/>(LTO=fat)"]
    end
    
    subgraph "Compilation Output"
        Binary["target/release/zeroclaw"]
        Size["Binary Size:<br/>3.4-8.8 MB"]
        Features["Features:<br/>default, hardware,<br/>browser-native, probe"]
    end
    
    subgraph "Installation"
        CargoInstall["cargo install --path ."]
        ManualCopy["cp target/release/zeroclaw<br/>~/.cargo/bin/"]
        BootstrapScript["./bootstrap.sh"]
    end
    
    subgraph "Deployed Binary"
        BinPath["~/.cargo/bin/zeroclaw"]
        SystemPath["System PATH"]
        Execute["zeroclaw agent<br/>zeroclaw daemon<br/>zeroclaw gateway"]
    end
    
    Source --> Cargo
    Cargo --> Profile1
    Cargo --> Profile2
    Cargo --> Profile3
    
    Profile1 --> Binary
    Profile2 --> Binary
    Profile3 --> Binary
    
    Binary --> Size
    Binary --> Features
    
    Binary --> CargoInstall
    Binary --> ManualCopy
    Binary --> BootstrapScript
    
    CargoInstall --> BinPath
    ManualCopy --> BinPath
    BootstrapScript --> BinPath
    
    BinPath --> SystemPath
    SystemPath --> Execute
Loading

Diagram: Native Binary Compilation and Installation Flow

Sources: README.md:169-198, Cargo.toml:161-181

Prerequisites by Platform

Windows

Requirement Installation Purpose
Visual Studio Build Tools winget install Microsoft.VisualStudio.2022.BuildTools MSVC linker and Windows SDK
Rust toolchain winget install Rustlang.Rustup Cargo and rustc
Workload: Desktop development with C++ Via Visual Studio Installer C++ compilation dependencies

After installation, verify:

rustc --version
cargo --version

Sources: README.md:102-123

Linux

Debian/Ubuntu:

sudo apt install build-essential pkg-config

Fedora/RHEL:

sudo dnf group install development-tools
sudo dnf install pkg-config

Rust toolchain:

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

Sources: README.md:133-151

macOS

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

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

Sources: README.md:133-151

Build Profiles

ZeroClaw defines three distinct build profiles optimized for different scenarios:

Profile Comparison Table

Profile Opt Level LTO Codegen Units Use Case RAM Required
release z thin 1 Default: Low-memory devices (Raspberry Pi 3) 1GB+
release-fast z thin 8 Powerful development machines 16GB+
dist z fat 1 Distribution binaries (CI/CD) 2GB+

release Profile (Default)

Optimized for compilation on low-memory devices like Raspberry Pi 3 (1GB RAM):

[profile.release]
opt-level = "z"          # Optimize for size
lto = "thin"             # Thin LTO (lower memory use)
codegen-units = 1        # Serialized codegen (single-threaded)
strip = true             # Remove debug symbols
panic = "abort"          # Reduce binary size

Build command:

cargo build --release --locked

Expected output:

  • Binary size: ~8.8 MB
  • Compilation time: 10-20 minutes (on 4-core ARM)
  • Memory usage: < 1GB peak

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

release-fast Profile

Optimized for fast builds on powerful machines (16GB+ RAM):

[profile.release-fast]
inherits = "release"
codegen-units = 8        # Parallel codegen (8 threads)

Build command:

cargo build --profile release-fast

Use when:

  • Developing on a workstation with 16GB+ RAM
  • Need faster iteration cycles
  • Acceptable to trade compilation speed for larger binary

Sources: Cargo.toml:169-172, README.md:164

dist Profile

Optimized for distribution binaries with maximum optimization:

[profile.dist]
inherits = "release"
opt-level = "z"
lto = "fat"              # Full LTO (maximum optimization)
codegen-units = 1
strip = true
panic = "abort"

Build command:

cargo build --profile dist

Used by:

  • CI/CD pipelines for release artifacts
  • GitHub Actions Docker image builds
  • Official distribution binaries

Sources: Cargo.toml:174-180

Building from Source

Standard Build

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

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

# Verify binary
ls -lh target/release/zeroclaw

The --locked flag ensures deterministic builds using Cargo.lock, preventing dependency drift on fresh systems. This is critical for reproducibility and security.

Sources: README.md:195-198, README.md:807-814

Feature Flags

ZeroClaw supports optional features that can be enabled during compilation:

Feature Description Impact
default Includes hardware feature +50 KB
hardware USB enumeration and serial port tools +500 KB
browser-native Rust-native fantoccini browser backend +2 MB
sandbox-landlock Landlock LSM sandbox (Linux only) +100 KB
probe probe-rs for STM32/Nucleo debugging +5 MB, +50 deps
rag-pdf PDF extraction for datasheet RAG +1 MB

Example: Build with browser and probe support:

cargo build --release --features "browser-native,probe"

Example: Minimal build (no hardware tools):

cargo build --release --no-default-features

Sources: Cargo.toml:144-160

Measuring Build Output

# Binary size
ls -lh target/release/zeroclaw

# Memory footprint during execution
/usr/bin/time -l target/release/zeroclaw --help
/usr/bin/time -l target/release/zeroclaw status

# Startup time
time target/release/zeroclaw --help

Expected metrics (macOS arm64, Feb 2026):

  • Binary size: 8.8 MB
  • zeroclaw --help: ~0.02s, ~3.9 MB peak memory
  • zeroclaw status: ~0.01s, ~4.1 MB peak memory

Sources: README.md:82-98

Installation Methods

Method 1: cargo install (Recommended)

Builds and installs to ~/.cargo/bin/:

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

Flags:

  • --path .: Install from current directory
  • --force: Overwrite existing binary
  • --locked: Use exact dependency versions from Cargo.lock

After installation:

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

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

Sources: README.md:198-201

Method 2: Manual Copy

Copy the binary to a directory in your PATH:

# Build first
cargo build --release --locked

# Copy to user bin directory
cp target/release/zeroclaw ~/.local/bin/

# Or system-wide (requires sudo)
sudo cp target/release/zeroclaw /usr/local/bin/

Sources: README.md:195-198

Method 3: Bootstrap Script

Automated installation with dependency management:

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

# Run bootstrap script
./bootstrap.sh

# Optional: Install system dependencies and Rust
./bootstrap.sh --install-system-deps --install-rust

# Optional: Run onboarding immediately
./bootstrap.sh --onboard --api-key "sk-..." --provider openrouter
sequenceDiagram
    participant User
    participant bootstrap.sh
    participant scripts/bootstrap.sh
    participant Cargo
    participant Config
    
    User->>bootstrap.sh: ./bootstrap.sh --install-system-deps
    bootstrap.sh->>scripts/bootstrap.sh: exec with args
    
    alt System deps requested
        scripts/bootstrap.sh->>scripts/bootstrap.sh: Detect OS (uname)
        scripts/bootstrap.sh->>scripts/bootstrap.sh: Install build-essential/pkg-config
        Note over scripts/bootstrap.sh: May prompt for sudo
    end
    
    alt Rust not installed
        scripts/bootstrap.sh->>scripts/bootstrap.sh: curl rustup.rs installer
        scripts/bootstrap.sh->>scripts/bootstrap.sh: sh -s -- -y
    end
    
    scripts/bootstrap.sh->>Cargo: cargo build --release --locked
    Cargo-->>scripts/bootstrap.sh: Binary: target/release/zeroclaw
    
    scripts/bootstrap.sh->>scripts/bootstrap.sh: cargo install --path . --force --locked
    scripts/bootstrap.sh-->>User: Installed to ~/.cargo/bin/zeroclaw
    
    alt --onboard flag present
        scripts/bootstrap.sh->>Config: zeroclaw onboard --api-key ... --provider ...
        Config-->>User: Config written to ~/.zeroclaw/config.toml
    end
Loading

Diagram: Bootstrap Script Execution Flow

Sources: bootstrap.sh:1-6, README.md:172-192

Cross-Compilation

Target Architectures

ZeroClaw supports cross-compilation for multiple targets:

Target Triple Architecture OS Use Case
x86_64-unknown-linux-gnu x86-64 Linux (glibc) Standard Linux servers
x86_64-unknown-linux-musl x86-64 Linux (musl) Alpine Linux, static binaries
aarch64-unknown-linux-gnu ARM64 Linux Raspberry Pi 4, AWS Graviton
armv7-unknown-linux-gnueabihf ARMv7 Linux Raspberry Pi 3
x86_64-pc-windows-msvc x86-64 Windows Windows servers
x86_64-apple-darwin x86-64 macOS Intel Macs
aarch64-apple-darwin ARM64 macOS Apple Silicon Macs

Cross-Compilation Setup

Install target:

rustup target add aarch64-unknown-linux-gnu

Install cross-compilation linker:

# Ubuntu/Debian
sudo apt install gcc-aarch64-linux-gnu

# macOS (via Homebrew)
brew install aarch64-unknown-linux-gnu

Configure Cargo:

Create .cargo/config.toml:

[target.aarch64-unknown-linux-gnu]
linker = "aarch64-linux-gnu-gcc"

Build:

cargo build --release --target aarch64-unknown-linux-gnu

Output location:

target/aarch64-unknown-linux-gnu/release/zeroclaw

Using cross for Complex Targets

For targets requiring system libraries (e.g., OpenSSL), use the cross tool:

# Install cross
cargo install cross

# Build for ARM64
cross build --release --target aarch64-unknown-linux-gnu

cross uses Docker containers with pre-configured toolchains, eliminating manual linker setup.

Sources: README.md:54, Cargo.toml:140-142 (target-specific dependencies)

Platform-Specific Considerations

Windows: MSVC Linker Resolution

ZeroClaw requires the MSVC toolchain on Windows. Common issues:

Issue: link.exe not found

error: linker `link.exe` not found

Solution:

  1. Verify Visual Studio Build Tools installation
  2. Ensure "Desktop development with C++" workload is installed
  3. Restart terminal to refresh environment variables

Issue: OpenSSL build errors

ZeroClaw uses rustls by default to avoid OpenSSL dependencies. If you encounter openssl-sys errors:

# Rebuild with locked dependencies
cargo clean
cargo build --release --locked

Sources: README.md:102-128, README.md:805-814

Linux: OpenSSL Dependency Management

ZeroClaw is configured to use rustls for HTTP/TLS, avoiding system OpenSSL dependencies. However, transitive dependencies may still reference openssl-sys.

If encountering OpenSSL errors:

# Sync dependencies with repository lockfile
git pull
cargo build --release --locked
cargo install --path . --force --locked

The --locked flag enforces exact dependency versions, keeping the transitive graph deterministic.

Sources: README.md:805-814

macOS: Xcode Command Line Tools

Ensure Xcode Command Line Tools are installed before building:

# Check if already installed
xcode-select -p

# Install if missing
xcode-select --install

Sources: README.md:138

Low-Memory Devices (Raspberry Pi)

Default profile works on Raspberry Pi 3 (1GB RAM):

cargo build --release --locked

If compilation still fails with OOM:

  1. Reduce codegen-units further (edit Cargo.toml):
[profile.release]
codegen-units = 1  # Already set, but verify
  1. Increase swap space:
sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfile  # Set CONF_SWAPSIZE=2048
sudo dphys-swapfile setup
sudo dphys-swapfile swapon
  1. Cross-compile from a more powerful machine (see Cross-Compilation section above)

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

Binary Characteristics and Performance

Size Comparison by Profile

Build Profile Binary Size Compilation Time Use Case
release (default) 8.8 MB 15-20 min (4-core ARM) Low-memory devices
release-fast 8.9 MB 5-7 min (8-core x86) Development machines
dist 8.7 MB 25-30 min (4-core x86) Distribution artifacts

Runtime Performance

Cold start (release build, macOS arm64):

Command Real Time Peak Memory
zeroclaw --help ~0.02s ~3.9 MB
zeroclaw status ~0.01s ~4.1 MB
zeroclaw agent -m "test" ~0.8s ~12 MB (includes LLM API call)

Memory footprint by mode:

Mode Idle Memory Active Memory Notes
CLI commands 3-5 MB N/A Ephemeral
zeroclaw gateway 8-12 MB 15-20 MB Persistent process
zeroclaw daemon 10-15 MB 20-30 MB All channels active

Sources: README.md:9, README.md:51, README.md:93-98

Static vs. Dynamic Linking

ZeroClaw produces a mostly-static binary:

  • Rust standard library: statically linked
  • Core dependencies: statically linked
  • System libraries (libc, pthread): dynamically linked (required by OS ABI)

Check dynamic dependencies:

# Linux
ldd target/release/zeroclaw

# macOS
otool -L target/release/zeroclaw

Expected dependencies are minimal: libc, libgcc_s, libpthread, libdl.

Troubleshooting

Build Failures

Issue: Out of memory during compilation

error: could not compile zeroclaw
Killed

Solutions:

  1. Use default release profile (codegen-units=1)
  2. Increase swap space (Linux)
  3. Cross-compile from a more powerful machine
  4. Close other applications during build

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

Issue: Linker errors on Windows

error: linking with `link.exe` failed

Solutions:

  1. Install Visual Studio Build Tools
  2. Select "Desktop development with C++" workload
  3. Restart terminal
  4. Verify rustc --version shows msvc target

Sources: README.md:102-128

Issue: openssl-sys build failure

error: failed to run custom build command for `openssl-sys`

Solution:

git pull  # Get latest Cargo.lock
cargo clean
cargo build --release --locked

Sources: README.md:805-814

Installation Issues

Issue: zeroclaw command not found after installation

Solution:

# Check if ~/.cargo/bin is in PATH
echo $PATH | grep cargo

# If missing, add to shell profile
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Issue: Permission denied when running bootstrap script

bash: ./bootstrap.sh: Permission denied

Solution:

chmod +x bootstrap.sh
./bootstrap.sh

Or run directly with bash:

bash bootstrap.sh

Sources: README.md:200-201

Verification and Testing

After installation, verify the binary works correctly:

# Version check
zeroclaw --version

# Help output
zeroclaw --help

# System diagnostics
zeroclaw doctor

# Status check
zeroclaw status

# Test agent (requires API key configuration)
zeroclaw agent -m "Hello, world!"

Expected zeroclaw doctor output:

✓ Config file exists: ~/.zeroclaw/config.toml
✓ Provider configured: openrouter
✓ Workspace exists: ~/.zeroclaw/workspace
✓ Memory backend: sqlite
✓ Runtime adapter: native

Sources: README.md:213-234

Comparison: Native vs. Docker Deployment

Aspect Native Binary Docker Container
Deployment complexity Low (single binary) Medium (image + runtime)
Startup time < 10ms ~1-2s (container init)
Memory overhead 3-5 MB (binary only) +50-100 MB (Docker runtime)
Isolation OS-level user/process Container namespace isolation
Portability Compile per target Run anywhere with Docker
Update process Replace binary Pull new image
Best for Edge devices, CLI usage Cloud deployments, CI/CD

For containerized deployments, see Docker Deployment.

Next Steps

Sources: README.md:169-252, Cargo.toml:1-189

Home

  1. Overview

  2. Getting Started

  3. Core Architecture

  4. Configuration

  5. Providers

  6. Channels

  7. Agent Core

  8. Tools

  9. Memory System

  10. Gateway

  11. Scheduler

  12. Development Guide

  13. Deployment

  14. Maturity Framework

Clone this wiki locally
⚡