Installation

Complete guide to building, installing, and optimizing NullClaw from source across all supported platforms

Installation

This guide covers building NullClaw from source with detailed instructions for all platforms, optimization options, and advanced configuration.

Prerequisites

Required Dependencies

macOS

# Install Zig 0.15.2
brew install zig@0.15.2

# Or download directly
curl -L https://ziglang.org/download/0.15.2/zig-macos-aarch64-0.15.2.tar.xz | tar -xJ

# SQLite (optional, for memory backend)
brew install sqlite

Xcode Command Line Tools (for system libraries):

xcode-select --install

Linux

# Download Zig 0.15.2
wget https://ziglang.org/download/0.15.2/zig-linux-x86_64-0.15.2.tar.xz
tar -xf zig-linux-x86_64-0.15.2.tar.xz
export PATH="$PWD/zig-linux-x86_64-0.15.2:$PATH"

# SQLite development headers (optional)
# Ubuntu/Debian
sudo apt-get install libsqlite3-dev

# Fedora/RHEL
sudo dnf install sqlite-devel

# Arch
sudo pacman -S sqlite

Windows

1. Download Zig 0.15.2 from ziglang.org
2. Extract to C:\zig-0.15.2\
3. Add to PATH: setx PATH "%PATH%;C:\zig-0.15.2\"
4. Install Visual Studio Build Tools or MinGW-w64

SQLite (optional):

• Download from sqlite.org
• Use pre-compiled DLL or build from source

ARM/Edge

# Raspberry Pi / ARM SBC
wget https://ziglang.org/download/0.15.2/zig-linux-aarch64-0.15.2.tar.xz
tar -xf zig-linux-aarch64-0.15.2.tar.xz
export PATH="$PWD/zig-linux-aarch64-0.15.2:$PATH"

# Build dependencies
sudo apt-get update
sudo apt-get install build-essential libsqlite3-dev

On low-memory devices (< 512 MB RAM), consider building on a more powerful machine and copying the binary.

Verify Zig Installation

You must use Zig version 0.15.2 exactly. Other versions will fail to build.

zig version

Expected output:

0.15.2

Building from Source

1. Clone the repository

   git clone https://github.com/nullclaw/nullclaw.git
   cd nullclaw
   

   Or download a specific release:

   wget https://github.com/nullclaw/nullclaw/archive/refs/tags/v2026.2.26.tar.gz
   tar -xzf v2026.2.26.tar.gz
   cd nullclaw-2026.2.26
   
2. Choose your build profile

   NullClaw supports multiple build profiles optimized for different use cases:

   Production (Smallest Binary)

   # ReleaseSmall: Optimized for size
   # ~678 KB binary, full optimizations
   zig build -Doptimize=ReleaseSmall
   

   # Debug build with symbols
   # Larger binary, easier debugging
   zig build
   

   # ReleaseFast: Optimized for speed
   # Larger binary, maximum performance
   zig build -Doptimize=ReleaseFast
   

   # ReleaseSafe: Runtime safety checks enabled
   # Balance of speed and safety
   zig build -Doptimize=ReleaseSafe
   

   Recommended: Use ReleaseSmall for production deployments to achieve the advertised 678 KB binary size.

3. Configure build options

   Memory Backend Selection

   Choose which memory backends to include:

   # Default: base backends + SQLite
   zig build -Doptimize=ReleaseSmall
   
   # Minimal: Only basic backends (markdown, memory, api)
   zig build -Doptimize=ReleaseSmall -Dengines=base
   
   # All: Include all backends (SQLite, Lucid, Redis, LanceDB, PostgreSQL)
   zig build -Doptimize=ReleaseSmall -Dengines=all
   
   # Custom: Select specific backends
   zig build -Doptimize=ReleaseSmall -Dengines=base,sqlite,lucid
   

   Available engines:

   • base / minimal: Basic file and memory backends
   • sqlite: SQLite-backed memory with vector + FTS5 search (default)
   • lucid: Lucid memory backend (requires SQLite)
   • redis: Redis backend (requires Redis client library)
   • lancedb: LanceDB vector store (requires SQLite)
   • postgres: PostgreSQL backend (requires libpq)
   • all: All available backends

   Channel Selection

   Include only the channels you need:

   # Default: All channels
   zig build -Doptimize=ReleaseSmall
   
   # CLI only (minimal)
   zig build -Doptimize=ReleaseSmall -Dchannels=cli
   
   # Common channels
   zig build -Doptimize=ReleaseSmall -Dchannels=cli,telegram,discord,slack
   
   # All channels explicitly
   zig build -Doptimize=ReleaseSmall -Dchannels=all
   

   Available channels: cli, telegram, discord, slack, whatsapp, matrix, mattermost, irc, imessage, email, lark, dingtalk, line, onebot, qq, maixcam, signal, nostr, web

4. Build the binary

   Run the build:

   zig build -Doptimize=ReleaseSmall
   

   Build output:

   zig build -Doptimize=ReleaseSmall
   └─ install
      └─ zig build-exe nullclaw ReleaseSmall native
         ├─ zig build-lib sqlite3 ReleaseSmall native
         └─ install nullclaw to zig-out/bin
   

   The compiled binary is at: zig-out/bin/nullclaw

5. Verify the build

   ls -lh zig-out/bin/nullclaw
   ./zig-out/bin/nullclaw --version
   

   Expected output:

   -rwxr-xr-x 1 user staff 678K Feb 26 12:00 nullclaw
   nullclaw 2026.2.26
   

Platform-Specific Builds

Cross-Compilation

Zig makes cross-compilation trivial:

Linux → Windows

zig build -Doptimize=ReleaseSmall -Dtarget=x86_64-windows

zig build -Doptimize=ReleaseSmall -Dtarget=x86_64-linux

zig build -Doptimize=ReleaseSmall -Dtarget=aarch64-linux

zig build -Doptimize=ReleaseSmall -Dtarget=riscv64-linux

zig build -Doptimize=ReleaseSmall -Dtarget=wasm32-wasi

Static Binary (Fully Portable)

Create a fully static binary with no dynamic dependencies:

zig build -Doptimize=ReleaseSmall -Dtarget=x86_64-linux-musl

This produces a binary that runs on any Linux system without libc dependencies.

Binary Size Optimization

Aggressive Size Reduction

For absolute minimum binary size:

Minimal Channels + Engines

# CLI-only, no SQLite
zig build -Doptimize=ReleaseSmall -Dchannels=cli -Dengines=base

zig build -Doptimize=ReleaseSmall
strip -s zig-out/bin/nullclaw

# Compress the binary with UPX
upx --best --lzma zig-out/bin/nullclaw

# Results in ~250 KB compressed binary
ls -lh zig-out/bin/nullclaw

UPX compression makes the binary smaller on disk but requires decompression at runtime, slightly increasing startup time. Use only if disk space is critical.

Build Options Reference

From build.zig, these optimizations are automatically applied for ReleaseSmall:

if (optimize != .Debug) {
    exe.root_module.strip = true;              // Remove debug symbols
    exe.root_module.unwind_tables = .none;     // No unwind tables
    exe.root_module.omit_frame_pointer = true; // Omit frame pointers
}

Installation Methods

System-Wide Installation

Unix-like (macOS/Linux)

# Copy to /usr/local/bin
sudo cp zig-out/bin/nullclaw /usr/local/bin/

# Verify
nullclaw --version

Linux (systemwide, respects XDG)

# Copy to ~/.local/bin (user-specific)
mkdir -p ~/.local/bin
cp zig-out/bin/nullclaw ~/.local/bin/

# Add to PATH if not already
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Windows

# Copy to a directory in PATH
copy zig-out\bin\nullclaw.exe C:\Windows\System32\

# Or create a dedicated directory
mkdir C:\Program Files\NullClaw
copy zig-out\bin\nullclaw.exe "C:\Program Files\NullClaw\"
setx PATH "%PATH%;C:\Program Files\NullClaw"

Development (PATH only)

# Add to PATH temporarily
export PATH="$PWD/zig-out/bin:$PATH"

# Or add to shell profile
echo 'export PATH="/path/to/nullclaw/zig-out/bin:$PATH"' >> ~/.bashrc

Container Deployment

Dockerfile (Alpine)

FROM alpine:3.20

# Copy static binary
COPY zig-out/bin/nullclaw /usr/local/bin/nullclaw

# Create workspace
RUN mkdir -p /root/.nullclaw/workspace

EXPOSE 3000

CMD ["nullclaw", "gateway"]

FROM scratch

# Fully static binary, no dependencies
COPY zig-out/bin/nullclaw /nullclaw

EXPOSE 3000

ENTRYPOINT ["/nullclaw"]
CMD ["gateway"]

# Build container
docker build -t nullclaw:latest .

# Run
docker run -d -p 3000:3000 \
  -v ~/.nullclaw:/root/.nullclaw \
  nullclaw:latest

Verification

Post-Installation Checks

1. Check binary size

   ls -lh $(which nullclaw)
   

   Expected: ~678 KB for ReleaseSmall

2. Check startup time

   time nullclaw --help
   

   Expected: <10ms on modern hardware

3. Run system diagnostics

   nullclaw doctor
   

   This will check:

   • Zig version compatibility
   • Binary integrity
   • System dependencies
   • Configuration validity
4. Run test suite (optional)

   From the source directory:

   zig build test --summary all
   

   Expected: 3,230+ tests passing, 0 failures, 0 memory leaks

   Test [3230/3230] test.memory_sqlite.hybrid_search... PASS
   
   3230 passed; 0 skipped; 0 failed
   

Benchmark Your Build

Measure performance and resource usage:

# Startup time and memory
/usr/bin/time -l nullclaw --help

# Status command
/usr/bin/time -l nullclaw status

Expected output (macOS):

0.00 real         0.00 user         0.00 sys
  1048576 maximum resident set size  (~1 MB)
        0 page faults

Development Setup

For contributors and developers:

1. Clone with full history

   git clone https://github.com/nullclaw/nullclaw.git
   cd nullclaw
   
2. Install development tools

   # Install pre-commit hooks
   git config core.hooksPath .githooks
   
   # Verify hooks are active
   ls -la .githooks/
   

   Hooks installed:

   • pre-commit: Runs zig fmt --check
   • pre-push: Runs full test suite
3. Build in development mode

   # Debug build with symbols
   zig build
   
   # Run tests
   zig build test --summary all
   
   # Run with arguments
   zig build run -- agent -m "Hello"
   
4. Format code

   # Check formatting
   zig fmt --check src/
   
   # Apply formatting
   zig fmt src/
   

Troubleshooting

Build Failures

SQLite vendored checksum mismatch

Error: error: VendoredSqliteChecksumMismatch

Cause: Vendored SQLite files were modified or corrupted

Solution:

# Re-clone repository
git clone https://github.com/nullclaw/nullclaw.git
cd nullclaw

# Or reset vendored files
git checkout HEAD -- vendor/sqlite3/

Invalid channels/engines option

Error: error: unknown channel 'foo' in -Dchannels list

Solution: Check the available options:

# Valid channels
zig build -Dchannels=all
zig build -Dchannels=cli,telegram,discord

# Valid engines
zig build -Dengines=base,sqlite

Out of memory during build

Error: error: OutOfMemory

Solution: Build on a machine with more RAM, or use a smaller configuration:

zig build -Doptimize=ReleaseSmall -Dchannels=cli -Dengines=base

Cross-compilation failures

Error: error: unable to find native system library 'c'

Solution: Install cross-compilation toolchain:

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

# Or use musl for static builds
zig build -Dtarget=aarch64-linux-musl

Runtime Issues

Command not found after installation

Error: bash: nullclaw: command not found

Solution: Verify PATH or use absolute path:

which nullclaw
echo $PATH

# Add to PATH
export PATH="/path/to/zig-out/bin:$PATH"

Shared library errors (Linux)

Error: error while loading shared libraries

Solution: Build a static binary:

zig build -Doptimize=ReleaseSmall -Dtarget=x86_64-linux-musl

Next Steps

Quick Start

Configure and run your first agent

Configuration

Learn about config.json and provider setup

Development Guide

Contribute to NullClaw or add custom providers

Deployment

Deploy NullClaw in production environments

---

For advanced build configurations and vtable interface development, see the Development Guide and AGENTS.md in the repository.