Quick Start

Get NullClaw up and running in under 5 minutes - from build to your first AI agent interaction

Quick Start

Get NullClaw running in under 5 minutes. This guide covers building from source, initial setup, and running your first agent command.

Prerequisite: You must use Zig 0.15.2 (exact version).

0.16.0-dev and other Zig versions are currently unsupported and may fail to build.

Verify before building: zig version should print 0.15.2.

Prerequisites

Required

• Zig 0.15.2 (exact version)
• Git for cloning the repository
• libc (standard C library)

Optional

• SQLite (if building with SQLite memory backend - enabled by default)
• Docker (for sandboxed tool execution)
• OpenSSL/LibreSSL (for TLS support in channels)

Install Zig 0.15.2

macOS (Homebrew)

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
export PATH="$PWD/zig-macos-aarch64-0.15.2:$PATH"

Build NullClaw

1. Clone the repository

   git clone https://github.com/nullclaw/nullclaw.git
   cd nullclaw
   
2. Build the binary

   Build with size optimization for the smallest binary:

   zig build -Doptimize=ReleaseSmall
   

   Build output:

   zig build -Doptimize=ReleaseSmall
   └─ install
      └─ zig build-exe nullclaw ReleaseSmall native
         └─ zig build-lib sqlite3 ReleaseSmall native
   

   The binary will be created at zig-out/bin/nullclaw.

   Binary size: The ReleaseSmall build produces a ~678 KB binary on most platforms.

   For development builds (with debug symbols), use:

   zig build
   
3. Verify the build

   Check the binary size and test basic functionality:

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

   Expected output:

   -rwxr-xr-x 1 user staff 678K Feb 26 12:00 zig-out/bin/nullclaw
   nullclaw 2026.2.26
   
4. Optional: Install globally

   For convenient access from anywhere:

   # Copy to a location in your PATH
   sudo cp zig-out/bin/nullclaw /usr/local/bin/
   
   # Or add to PATH
   export PATH="$PWD/zig-out/bin:$PATH"
   

   If you skip global installation, prefix all commands with zig-out/bin/, for example:

   zig-out/bin/nullclaw status
   

Initial Setup

1. Run the onboarding wizard

   NullClaw includes an interactive setup wizard to configure your AI provider and preferences:

   nullclaw onboard --interactive
   

   Or quick setup with API key:

   nullclaw onboard --api-key sk-... --provider openrouter
   

   The wizard will:

   1. Ask for your AI provider (OpenRouter, OpenAI, Anthropic, etc.)
   2. Request your API key (stored encrypted)
   3. Configure default model preferences
   4. Set up security and workspace settings
   5. Optionally configure messaging channels (Telegram, Discord, etc.)
2. Verify configuration

   Check that the configuration was created successfully:

   nullclaw status
   

   Expected output:

   NullClaw Status
   
   ✓ Config: ~/.nullclaw/config.json
   ✓ Provider: openrouter (anthropic/claude-sonnet-4)
   ✓ Memory: sqlite (~/.nullclaw/memory.db)
   ✓ Workspace: ~/.nullclaw/workspace
   ✓ Security: supervised mode, workspace-only access
   
   System Health: OK
   

Run Your First Agent

1. Single message mode

   Send a single message to the agent:

   nullclaw agent -m "Hello, nullclaw!"
   

   Expected output:

   [agent] Hello! I'm NullClaw, a lightweight AI assistant running locally
   on your machine. I'm here to help with tasks, answer questions, and
   assist with your workflow. What would you like to do?
   
2. Interactive chat mode

   Enter interactive mode for a conversation:

   nullclaw agent
   

   You’ll see a prompt where you can type messages:

   NullClaw Agent (interactive mode)
   Type 'exit' or press Ctrl+D to quit
   
   > What's my current directory?
   
   [agent] You're currently in /home/user/projects. Would you like me to
   list the files here or navigate somewhere else?
   
   > List the files
   
   [agent] [Using tool: shell]
   $ ls -la
   
   total 24
   drwxr-xr-x  6 user staff  192 Feb 26 12:00 .
   drwxr-xr-x 10 user staff  320 Feb 26 11:30 ..
   -rw-r--r--  1 user staff  125 Feb 26 12:00 README.md
   drwxr-xr-x  3 user staff   96 Feb 26 12:00 src
   
   You have a README.md file and a src directory in your current location.
   
   > exit
   
   Goodbye!
   
3. Try built-in tools

   NullClaw has access to various tools. Try asking it to:

   nullclaw agent -m "Store a memory: my favorite color is blue"
   

   Expected output:

   [agent] [Using tool: memory_store]
   Stored memory: "favorite color is blue"
   Embedding: [0.123, -0.456, ...] (768 dimensions)
   
   I've stored that memory. I'll remember that your favorite color is blue.
   

   Then recall it:

   nullclaw agent -m "What's my favorite color?"
   

   Expected output:

   [agent] [Using tool: memory_recall]
   Query: "favorite color"
   Results: 1 match (score: 0.95)
   
   Based on what you told me earlier, your favorite color is blue.
   

Start the Gateway (Optional)

For 24/7 operation with messaging channels, run the gateway:

nullclaw gateway

Expected output:

[gateway] Starting NullClaw Gateway
[gateway] Version: 2026.2.26
[gateway] Listening on: http://127.0.0.1:3000
[gateway] Pairing code: 123456
[gateway] 
[gateway] Security: Pairing required, workspace-only mode
[gateway] Channels: 0 active
[gateway] 
[gateway] Ready

The gateway binds to 127.0.0.1:3000 by default and requires pairing for security. Use --port to change the port:

nullclaw gateway --port 8080

Start Specific Channels

After gateway is running, start configured channels:

nullclaw channel start telegram
nullclaw channel start discord
nullclaw channel status

Run as a Service

For production deployment, install NullClaw as a system service:

nullclaw service install
nullclaw service start
nullclaw service status

System Diagnostics

Run comprehensive system checks:

nullclaw doctor

Expected output:

NullClaw Doctor

✓ Zig version: 0.15.2
✓ Binary size: 678 KB
✓ Config: valid
✓ Provider: reachable
✓ Memory: healthy
✓ Workspace: writable
✓ Security: properly configured
✓ Dependencies: all satisfied

All checks passed!

Benchmark Your Installation

Measure startup time and memory usage:

/usr/bin/time -l zig-out/bin/nullclaw --help
/usr/bin/time -l zig-out/bin/nullclaw status

Expected metrics:

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

Next Steps

Configuration Guide

Learn about advanced configuration options and provider setup

Available Tools

Explore the built-in tools NullClaw can use

Security Model

Understand sandboxing, pairing, and access controls

Channel Setup

Configure Telegram, Discord, Slack, and other messaging platforms

Troubleshooting

Build Errors

Zig version mismatch

Error: error: incompatible zig version

Solution: Ensure you’re using exactly Zig 0.15.2:

zig version  # Must show: 0.15.2

SQLite linking error

Error: error: unable to find library 'sqlite3'

Solution: Install SQLite development headers:

# macOS
brew install sqlite

# Ubuntu/Debian
sudo apt-get install libsqlite3-dev

# Or build without SQLite:
zig build -Doptimize=ReleaseSmall -Dengines=base

Permission denied

Error: permission denied: zig-out/bin/nullclaw

Solution: Make the binary executable:

chmod +x zig-out/bin/nullclaw

Runtime Issues

Provider authentication failed

Error: error: provider authentication failed

Solution: Check your API key:

# Re-run onboarding to update API key
nullclaw onboard --interactive

# Or manually edit ~/.nullclaw/config.json

Config file not found

Error: error: config file not found

Solution: Run the onboarding wizard:

nullclaw onboard --interactive

---

For more help, see the full documentation or open an issue on GitHub.