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

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

<Note>
  **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`.
</Note>

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

<CodeGroup>
  ```bash macOS (Homebrew) theme={null}
  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"
  ```

  ```bash Linux theme={null}
  # Download and extract
  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"

  # Verify
  zig version
  ```

  ```bash Windows theme={null}
  # Download from https://ziglang.org/download/0.15.2/
  # Extract and add to PATH
  # Verify in PowerShell:
  zig version
  ```
</CodeGroup>

## Build NullClaw

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

  <Step title="Build the binary">
    Build with size optimization for the smallest binary:

    ```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
    ```

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

    <Note>
      **Binary size**: The ReleaseSmall build produces a \~678 KB binary on most platforms.

      For development builds (with debug symbols), use:

      ```bash theme={null}
      zig build
      ```
    </Note>
  </Step>

  <Step title="Verify the build">
    Check the binary size and test basic functionality:

    ```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 zig-out/bin/nullclaw
    nullclaw 2026.2.26
    ```
  </Step>

  <Step title="Optional: Install globally">
    For convenient access from anywhere:

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

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

      ```bash theme={null}
      zig-out/bin/nullclaw status
      ```
    </Warning>
  </Step>
</Steps>

## Initial Setup

<Steps>
  <Step title="Run the onboarding wizard">
    NullClaw includes an interactive setup wizard to configure your AI provider and preferences:

    ```bash theme={null}
    nullclaw onboard --interactive
    ```

    **Or quick setup with API key:**

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

  <Step title="Verify configuration">
    Check that the configuration was created successfully:

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

## Run Your First Agent

<Steps>
  <Step title="Single message mode">
    Send a single message to the agent:

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

  <Step title="Interactive chat mode">
    Enter interactive mode for a conversation:

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

  <Step title="Try built-in tools">
    NullClaw has access to various tools. Try asking it to:

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

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

## Start the Gateway (Optional)

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

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

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

  ```bash theme={null}
  nullclaw gateway --port 8080
  ```
</Note>

### Start Specific Channels

After gateway is running, start configured channels:

```bash theme={null}
nullclaw channel start telegram
nullclaw channel start discord
nullclaw channel status
```

## Run as a Service

For production deployment, install NullClaw as a system service:

```bash theme={null}
nullclaw service install
nullclaw service start
nullclaw service status
```

## System Diagnostics

Run comprehensive system checks:

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

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

<CardGroup cols={2}>
  <Card title="Configuration Guide" icon="gear" href="/essentials/configuration">
    Learn about advanced configuration options and provider setup
  </Card>

  <Card title="Available Tools" icon="wrench" href="/ai-tools">
    Explore the built-in tools NullClaw can use
  </Card>

  <Card title="Security Model" icon="shield" href="/essentials/security">
    Understand sandboxing, pairing, and access controls
  </Card>

  <Card title="Channel Setup" icon="message" href="/essentials/channels">
    Configure Telegram, Discord, Slack, and other messaging platforms
  </Card>
</CardGroup>

## Troubleshooting

### Build Errors

<AccordionGroup>
  <Accordion title="Zig version mismatch">
    **Error**: `error: incompatible zig version`

    **Solution**: Ensure you're using exactly Zig 0.15.2:

    ```bash theme={null}
    zig version  # Must show: 0.15.2
    ```
  </Accordion>

  <Accordion title="SQLite linking error">
    **Error**: `error: unable to find library 'sqlite3'`

    **Solution**: Install SQLite development headers:

    ```bash theme={null}
    # macOS
    brew install sqlite

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

    # Or build without SQLite:
    zig build -Doptimize=ReleaseSmall -Dengines=base
    ```
  </Accordion>

  <Accordion title="Permission denied">
    **Error**: `permission denied: zig-out/bin/nullclaw`

    **Solution**: Make the binary executable:

    ```bash theme={null}
    chmod +x zig-out/bin/nullclaw
    ```
  </Accordion>
</AccordionGroup>

### Runtime Issues

<AccordionGroup>
  <Accordion title="Provider authentication failed">
    **Error**: `error: provider authentication failed`

    **Solution**: Check your API key:

    ```bash theme={null}
    # Re-run onboarding to update API key
    nullclaw onboard --interactive

    # Or manually edit ~/.nullclaw/config.json
    ```
  </Accordion>

  <Accordion title="Config file not found">
    **Error**: `error: config file not found`

    **Solution**: Run the onboarding wizard:

    ```bash theme={null}
    nullclaw onboard --interactive
    ```
  </Accordion>
</AccordionGroup>

***

For more help, see the [full documentation](/essentials) or open an issue on [GitHub](https://github.com/nullclaw/nullclaw/issues).