This guide covers the main installation paths for macOS, Linux, and Windows.

Who this page is for

• First-time users installing NullClaw on a local machine
• Operators choosing between package install, container deployment, and source build
• Contributors validating the baseline runtime before deeper setup

Read this next

• Open Configuration after the binary is installed and on your PATH
• Open Usage and Operations when you are ready to run first commands and service mode
• Open README if you want the broader English docs map before going deeper

If you came from ...

• README: this page is the concrete first-run path after choosing the installation track
• Commands: come here first if the CLI is missing or nullclaw --help does not work yet
• Development: return here if a contributor workflow also needs a clean local binary setup

• If building from source, use Zig 0.16.0.
• Git (required for source install).

Check Zig version:

zig version

The output must be 0.16.0.

brew install nullclaw
nullclaw --help

If the command works, installation is complete.

NullClaw publishes an official OCI image at ghcr.io/nullclaw/nullclaw.

The container stores its persistent state under /nullclaw-data:

• config: /nullclaw-data/config.json
• workspace: /nullclaw-data/workspace

The bundled starter config already uses the current schema (agents.defaults.model.primary plus models.providers), so latest should boot cleanly before you customize provider credentials.

docker run --rm -it \
  -v nullclaw-data:/nullclaw-data \
  ghcr.io/nullclaw/nullclaw:latest status

Initialize config interactively:

docker run --rm -it \
  -v nullclaw-data:/nullclaw-data \
  ghcr.io/nullclaw/nullclaw:latest onboard --interactive

Run the interactive agent:

docker run --rm -it \
  -v nullclaw-data:/nullclaw-data \
  ghcr.io/nullclaw/nullclaw:latest agent

Run the HTTP gateway:

docker run --rm -it \
  -p 127.0.0.1:3000:3000 \
  -v nullclaw-data:/nullclaw-data \
  ghcr.io/nullclaw/nullclaw:latest

The repository ships a docker-compose.yml that uses the official image by default.

Interactive onboarding:

docker compose --profile agent run --rm agent onboard --interactive

Inside the official container flow, pressing Enter at the workspace prompt keeps the volume-backed default:

• workspace: /nullclaw-data/workspace

Interactive agent session:

docker compose --profile agent run --rm agent

Long-running gateway:

docker compose --profile gateway up -d gateway

Profile behavior:

• agent: one-off interactive CLI container
• gateway: long-running HTTP gateway published on host loopback port 3000

If you need LAN or public exposure, change the published host IP deliberately and review Security first.

To pin a release tag or switch registries later, override NULLCLAW_IMAGE:

NULLCLAW_IMAGE=ghcr.io/nullclaw/nullclaw:v2026.3.11 docker compose --profile gateway up -d gateway

git clone https://github.com/nullclaw/nullclaw.git
cd nullclaw
zig build -Doptimize=ReleaseSmall
zig build test --summary all

Build output:

• zig-out/bin/nullclaw

There are three different Android / Termux paths:

• download an official pre-built Android / Termux binary from releases
• build directly inside Termux on the Android device
• cross-compile an Android binary from another machine

pkg update
pkg install git zig
git clone https://github.com/nullclaw/nullclaw.git
cd nullclaw
zig version
zig build -Doptimize=ReleaseSmall
./zig-out/bin/nullclaw --help

Notes:

• Use Zig 0.16.0 exactly.
• If zig build fails immediately, verify the Zig version first.
• This uses the native target of the current Termux environment, so you usually do not need -Dtarget.
• On Android / Termux, prefer foreground use first (agent, gateway) before trying to manage it as a background service.
• Official releases publish pre-built Android / Termux binaries for aarch64, armv7, and x86_64.
• For the fuller Android / Termux path, including troubleshooting, see Termux Guide.

If you are building on another machine for a Termux / Android device, pass an explicit Zig target and an Android libc/sysroot file. -Dtarget alone is not enough:

zig build -Dtarget=aarch64-linux-android.24 -Doptimize=ReleaseSmall --libc /path/to/android-libc-aarch64.txt

Common Android targets:

• aarch64-linux-android.24
• arm-linux-androideabi.24 with -Dcpu=baseline+v7a
• x86_64-linux-android.24

Use the target that matches the phone or emulator architecture. See .github/workflows/release.yml for a complete example of generating the --libc file from the Android NDK. Official releases also attach matching Android / Termux binaries built for Android API 24.

zig build -Doptimize=ReleaseSmall -p "$HOME/.local"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
# bash users: use ~/.bashrc
source ~/.zshrc

zig build -Doptimize=ReleaseSmall -p "$HOME\.local"

$bin = "$HOME\.local\bin"
$user_path = [Environment]::GetEnvironmentVariable("Path", "User")
if (-not ($user_path -split ";" | Where-Object { $_ -eq $bin })) {
  [Environment]::SetEnvironmentVariable("Path", "$user_path;$bin", "User")
}
$env:Path = "$env:Path;$bin"

Download the Windows .zip archive from the releases page, extract it, and then run the following commands with administrator privileges in Powershell to add the directory containing nullclaw.exe to the Windows PATH environment variable:

$old = [Environment]::GetEnvironmentVariable("Path", "Machine")
$new = "$old;x:\path\to\nullclaw"
[Environment]::SetEnvironmentVariable("Path", $new, "Machine")

nullclaw --help
nullclaw --version
nullclaw status

If status returns component state successfully, runtime basics are ready.

• update:

brew update
brew upgrade nullclaw

• uninstall:

brew uninstall nullclaw

• update: nullclaw update

• uninstall: delete the nullclaw binary file and remove the entry of the directory containing the binary file in environment variables PATH if it exists.

• Upgrade: git pull, then rebuild with zig build -Doptimize=ReleaseSmall.
• Uninstall: delete the installed nullclaw binary and remove the PATH entry.

• Run nullclaw onboard --interactive, then continue with Configuration
• Use Usage and Operations for first-run commands, service mode, and troubleshooting
• Keep Commands nearby if you want a task-based CLI reference after install

• README
• Termux Guide
• Configuration
• Usage and Operations
• Commands