Installation

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

Prerequisites

Required Dependencies

macOS
Linux
Windows
ARM/Edge

# Install Zig 0.15.2
brew install [email protected]

# 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

# 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

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

SQLite (optional):

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

# 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

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

Choose your build profile

NullClaw supports multiple build profiles optimized for different use cases:

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

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

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

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

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:

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

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:

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

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)
Linux (systemwide, respects XDG)
Windows
Development (PATH only)

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

# Verify
nullclaw --version

# 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

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

# 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

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"]

Verification

Post-Installation Checks

Check binary size

ls -lh $(which nullclaw)

Expected: ~678 KB for ReleaseSmall

Check startup time

time nullclaw --help

Expected: <10ms on modern hardware

Run system diagnostics

nullclaw doctor

This will check:

Zig version compatibility
Binary integrity
System dependencies
Configuration validity

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:

Clone with full history

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

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

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"

Format code

# Check formatting
zig fmt --check src/

# Apply formatting
zig fmt src/

Troubleshooting

Build Failures

SQLite vendored checksum mismatch

Error: error: VendoredSqliteChecksumMismatchCause: Vendored SQLite files were modified or corruptedSolution:

# 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 listSolution: 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: OutOfMemorySolution: 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 foundSolution: 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 librariesSolution: 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.

Get Started

Core Concepts

Configuration

Deployment

Guides

Installation

Installation

Prerequisites

Required Dependencies

Verify Zig Installation

Building from Source

Memory Backend Selection

Channel Selection

Platform-Specific Builds

Cross-Compilation

Static Binary (Fully Portable)

Binary Size Optimization

Aggressive Size Reduction

Build Options Reference

Installation Methods

System-Wide Installation

Container Deployment

Verification

Post-Installation Checks

Benchmark Your Build

Development Setup

Troubleshooting

Build Failures

Runtime Issues

Next Steps

Quick Start

Configuration

Development Guide

Deployment

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Deployment

Guides

​Installation

​Prerequisites

​Required Dependencies

​Verify Zig Installation

​Building from Source

​Memory Backend Selection

​Channel Selection

​Platform-Specific Builds

​Cross-Compilation

​Static Binary (Fully Portable)

​Binary Size Optimization

​Aggressive Size Reduction

​Build Options Reference

​Installation Methods

​System-Wide Installation

​Container Deployment

​Verification

​Post-Installation Checks

​Benchmark Your Build

​Development Setup

​Troubleshooting

​Build Failures

​Runtime Issues

​Next Steps

Quick Start

Configuration

Development Guide

Deployment

Build docs developers (and LLMs) love

Installation

Prerequisites

Required Dependencies

Verify Zig Installation

Building from Source

Memory Backend Selection

Channel Selection

Platform-Specific Builds

Cross-Compilation

Static Binary (Fully Portable)

Binary Size Optimization

Aggressive Size Reduction

Build Options Reference

Installation Methods

System-Wide Installation

Container Deployment

Verification

Post-Installation Checks

Benchmark Your Build

Development Setup

Troubleshooting

Build Failures

Runtime Issues

Next Steps