> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nullclaw/nullclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    # 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):

    ```bash theme={null}
    xcode-select --install
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Windows">
    1. Download Zig 0.15.2 from [ziglang.org](https://ziglang.org/download/0.15.2/)
    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](https://www.sqlite.org/download.html)
    * Use pre-compiled DLL or build from source
  </Tab>

  <Tab title="ARM/Edge">
    ```bash theme={null}
    # 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
    ```

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

### Verify Zig Installation

<Warning>
  You **must** use Zig version 0.15.2 exactly. Other versions will fail to build.
</Warning>

```bash theme={null}
zig version
```

**Expected output:**

```
0.15.2
```

## Building from Source

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/nullclaw/nullclaw.git
    cd nullclaw
    ```

    **Or download a specific release:**

    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Choose your build profile">
    NullClaw supports multiple build profiles optimized for different use cases:

    <CodeGroup>
      ```bash Production (Smallest Binary) theme={null}
      # ReleaseSmall: Optimized for size
      # ~678 KB binary, full optimizations
      zig build -Doptimize=ReleaseSmall
      ```

      ```bash Development (Debug) theme={null}
      # Debug build with symbols
      # Larger binary, easier debugging
      zig build
      ```

      ```bash Release (Fast) theme={null}
      # ReleaseFast: Optimized for speed
      # Larger binary, maximum performance
      zig build -Doptimize=ReleaseFast
      ```

      ```bash Release (Safe) theme={null}
      # ReleaseSafe: Runtime safety checks enabled
      # Balance of speed and safety
      zig build -Doptimize=ReleaseSafe
      ```
    </CodeGroup>

    <Note>
      **Recommended**: Use `ReleaseSmall` for production deployments to achieve the advertised 678 KB binary size.
    </Note>
  </Step>

  <Step title="Configure build options">
    ### Memory Backend Selection

    Choose which memory backends to include:

    ```bash theme={null}
    # 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:

    ```bash theme={null}
    # 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`
  </Step>

  <Step title="Build the binary">
    Run the build:

    ```bash theme={null}
    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`
  </Step>

  <Step title="Verify the build">
    ```bash theme={null}
    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
    ```
  </Step>
</Steps>

## Platform-Specific Builds

### Cross-Compilation

Zig makes cross-compilation trivial:

<CodeGroup>
  ```bash Linux → Windows theme={null}
  zig build -Doptimize=ReleaseSmall -Dtarget=x86_64-windows
  ```

  ```bash macOS → Linux theme={null}
  zig build -Doptimize=ReleaseSmall -Dtarget=x86_64-linux
  ```

  ```bash x86_64 → ARM theme={null}
  zig build -Doptimize=ReleaseSmall -Dtarget=aarch64-linux
  ```

  ```bash x86_64 → RISC-V theme={null}
  zig build -Doptimize=ReleaseSmall -Dtarget=riscv64-linux
  ```

  ```bash WASI (WebAssembly) theme={null}
  zig build -Doptimize=ReleaseSmall -Dtarget=wasm32-wasi
  ```
</CodeGroup>

### Static Binary (Fully Portable)

Create a fully static binary with no dynamic dependencies:

```bash theme={null}
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:

<CodeGroup>
  ```bash Minimal Channels + Engines theme={null}
  # CLI-only, no SQLite
  zig build -Doptimize=ReleaseSmall -Dchannels=cli -Dengines=base
  ```

  ```bash Strip All Symbols (macOS/Linux) theme={null}
  zig build -Doptimize=ReleaseSmall
  strip -s zig-out/bin/nullclaw
  ```

  ```bash UPX Compression (Optional) theme={null}
  # Compress the binary with UPX
  upx --best --lzma zig-out/bin/nullclaw

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

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

### Build Options Reference

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

```zig theme={null}
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

<Tabs>
  <Tab title="Unix-like (macOS/Linux)">
    ```bash theme={null}
    # Copy to /usr/local/bin
    sudo cp zig-out/bin/nullclaw /usr/local/bin/

    # Verify
    nullclaw --version
    ```
  </Tab>

  <Tab title="Linux (systemwide, respects XDG)">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    # 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"
    ```
  </Tab>

  <Tab title="Development (PATH only)">
    ```bash theme={null}
    # 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
    ```
  </Tab>
</Tabs>

### Container Deployment

<CodeGroup>
  ```dockerfile Dockerfile (Alpine) theme={null}
  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"]
  ```

  ```dockerfile Dockerfile (Scratch) theme={null}
  FROM scratch

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

  EXPOSE 3000

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

  ```bash Build and Run theme={null}
  # Build container
  docker build -t nullclaw:latest .

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

## Verification

### Post-Installation Checks

<Steps>
  <Step title="Check binary size">
    ```bash theme={null}
    ls -lh $(which nullclaw)
    ```

    **Expected**: \~678 KB for ReleaseSmall
  </Step>

  <Step title="Check startup time">
    ```bash theme={null}
    time nullclaw --help
    ```

    **Expected**: \<10ms on modern hardware
  </Step>

  <Step title="Run system diagnostics">
    ```bash theme={null}
    nullclaw doctor
    ```

    This will check:

    * Zig version compatibility
    * Binary integrity
    * System dependencies
    * Configuration validity
  </Step>

  <Step title="Run test suite (optional)">
    From the source directory:

    ```bash theme={null}
    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
    ```
  </Step>
</Steps>

### Benchmark Your Build

Measure performance and resource usage:

```bash theme={null}
# 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:

<Steps>
  <Step title="Clone with full history">
    ```bash theme={null}
    git clone https://github.com/nullclaw/nullclaw.git
    cd nullclaw
    ```
  </Step>

  <Step title="Install development tools">
    ```bash theme={null}
    # 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
  </Step>

  <Step title="Build in development mode">
    ```bash theme={null}
    # Debug build with symbols
    zig build

    # Run tests
    zig build test --summary all

    # Run with arguments
    zig build run -- agent -m "Hello"
    ```
  </Step>

  <Step title="Format code">
    ```bash theme={null}
    # Check formatting
    zig fmt --check src/

    # Apply formatting
    zig fmt src/
    ```
  </Step>
</Steps>

## Troubleshooting

### Build Failures

<AccordionGroup>
  <Accordion title="SQLite vendored checksum mismatch">
    **Error**: `error: VendoredSqliteChecksumMismatch`

    **Cause**: Vendored SQLite files were modified or corrupted

    **Solution**:

    ```bash theme={null}
    # Re-clone repository
    git clone https://github.com/nullclaw/nullclaw.git
    cd nullclaw

    # Or reset vendored files
    git checkout HEAD -- vendor/sqlite3/
    ```
  </Accordion>

  <Accordion title="Invalid channels/engines option">
    **Error**: `error: unknown channel 'foo' in -Dchannels list`

    **Solution**: Check the available options:

    ```bash theme={null}
    # Valid channels
    zig build -Dchannels=all
    zig build -Dchannels=cli,telegram,discord

    # Valid engines
    zig build -Dengines=base,sqlite
    ```
  </Accordion>

  <Accordion title="Out of memory during build">
    **Error**: `error: OutOfMemory`

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

    ```bash theme={null}
    zig build -Doptimize=ReleaseSmall -Dchannels=cli -Dengines=base
    ```
  </Accordion>

  <Accordion title="Cross-compilation failures">
    **Error**: `error: unable to find native system library 'c'`

    **Solution**: Install cross-compilation toolchain:

    ```bash theme={null}
    # Ubuntu/Debian
    sudo apt-get install gcc-aarch64-linux-gnu

    # Or use musl for static builds
    zig build -Dtarget=aarch64-linux-musl
    ```
  </Accordion>
</AccordionGroup>

### Runtime Issues

<AccordionGroup>
  <Accordion title="Command not found after installation">
    **Error**: `bash: nullclaw: command not found`

    **Solution**: Verify PATH or use absolute path:

    ```bash theme={null}
    which nullclaw
    echo $PATH

    # Add to PATH
    export PATH="/path/to/zig-out/bin:$PATH"
    ```
  </Accordion>

  <Accordion title="Shared library errors (Linux)">
    **Error**: `error while loading shared libraries`

    **Solution**: Build a static binary:

    ```bash theme={null}
    zig build -Doptimize=ReleaseSmall -Dtarget=x86_64-linux-musl
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Configure and run your first agent
  </Card>

  <Card title="Configuration" icon="gear" href="/essentials/configuration">
    Learn about config.json and provider setup
  </Card>

  <Card title="Development Guide" icon="code" href="/development">
    Contribute to NullClaw or add custom providers
  </Card>

  <Card title="Deployment" icon="server" href="/essentials/deployment">
    Deploy NullClaw in production environments
  </Card>
</CardGroup>

***

For advanced build configurations and vtable interface development, see the [Development Guide](/development) and [AGENTS.md](https://github.com/nullclaw/nullclaw/blob/main/AGENTS.md) in the repository.