ZeroClaw is a single static Rust binary, which makes installing it unusually simple: get the file onto the machine and put it somewhere on your PATH. Everything below is a variation on that theme. The differences are about who builds the binary, who keeps it updated, and how much you trust each of those parties.
Choosing an installation method
| Method | Best for | Trade-off | |---|---|---| | One-line installer | Fastest path on Linux and macOS | Pipes a remote script to your shell | | Homebrew | macOS and Linuxbrew users | Package updates lag upstream releases | | Cargo | Rust developers | Compiles from source; needs a toolchain | | From source | Contributors, custom builds | Slowest, most control | | Docker | Isolation, servers, CI | Container adds overhead the runtime avoided | | Termux | Android devices | Unofficial territory; expect friction |
If you have no strong preference and you are on Linux or macOS, use Homebrew or the installer. If you already have Rust installed, cargo install is the least surprising option.
Before you start
Check what you actually need. ZeroClaw itself needs almost nothing — a few megabytes of RAM and disk. The model is the expensive part. If you point it at a hosted API, a Raspberry Pi Zero is sufficient. If you plan to run models locally through Ollama, budget for the model: roughly 4GB of RAM for a small 3B model, 8GB or more for a 7B.
Verify what you are downloading. There are several repositories and domains carrying the ZeroClaw name, and not all of them are the project. Install from the official project repository, and if you use the one-line installer, read the script before running it rather than after. This site is an independent guide — we do not distribute the binary.
Method 1: The one-line installer (Linux, macOS)
curl -fsSL https://zeroclawlabs.ai/install.sh | bash
This detects your platform, downloads the matching release binary and places it on your PATH.
Piping a remote script into a shell means executing whatever that URL serves at the moment you run it. If that makes you uncomfortable — and it reasonably might — download it first and read it:
curl -fsSL https://zeroclawlabs.ai/install.sh -o install.sh
less install.sh
bash install.sh
Method 2: Homebrew (macOS, Linuxbrew)
brew install zeroclaw
Homebrew handles the PATH and makes upgrades routine:
brew upgrade zeroclaw
The trade-off is version lag. A package definition is updated after an upstream release, sometimes days later. If you need a specific new feature, one of the source-based methods will get it sooner.
Method 3: Cargo (any platform with Rust)
If you have a Rust toolchain:
cargo install zeroclaw
Cargo compiles from source and installs to ~/.cargo/bin, which its own installer adds to your PATH. Expect several minutes for the first build — Rust compilation is thorough rather than fast, and a release build of a project this size will exercise your CPU.
Don't have Rust? Install it first:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
rustc --version
Upgrading later:
cargo install zeroclaw --force
Method 4: From source
The route for contributors, or for building with non-default features:
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./bootstrap.sh
The bootstrap script handles the build and installation steps. To do it manually instead:
cargo build --release
cargo install --path . --force
The compiled binary lands at target/release/zeroclaw. You can copy that file directly to any machine with the same architecture — no installation step required, which is the whole point of a static binary.
Note that the canonical repository moved from openagen/zeroclaw to zeroclaw-labs/zeroclaw. Older guides — including older pages on this site — reference the previous location.
Method 5: Ubuntu and Debian specifics
Ubuntu has no official ZeroClaw package in the standard repositories, so use the installer, Homebrew on Linux, or Cargo. Build dependencies, if you are compiling:
sudo apt update
sudo apt install -y build-essential pkg-config libssl-dev curl git
build-essential supplies the linker, libssl-dev the TLS headers most builds need. Missing either produces linker errors during compilation that look alarming and mean nothing more than a missing package.
To install system-wide for all users:
sudo cp target/release/zeroclaw /usr/local/bin/
sudo chmod +x /usr/local/bin/zeroclaw
For an agent that should survive reboots, run it under systemd. ZeroClaw can install its own service definition:
zeroclaw service install
zeroclaw service status
Method 6: Windows
Windows has two viable paths.
Native Windows. Install the Rust toolchain from rustup.rs, which will prompt for the Microsoft C++ build tools if they are absent — accept, because the linker is not optional. Then:
cargo install zeroclaw
zeroclaw --version
Cargo adds %USERPROFILE%\.cargo\bin to your PATH. If zeroclaw is not recognised afterwards, open a new terminal — PATH changes do not apply to already-running sessions.
WSL2. Often the smoother option, because most ZeroClaw documentation and community answers assume Linux paths and shell conventions. Install Ubuntu under WSL2 and follow the Ubuntu instructions above. Note that WSL2 filesystem performance across the Windows boundary (/mnt/c/...) is poor — keep your workspace inside the Linux filesystem.
Method 7: Docker
Useful when you want isolation or a reproducible server deployment:
FROM rust:1-slim AS builder
WORKDIR /build
RUN apt-get update && apt-get install -y pkg-config libssl-dev git \
&& rm -rf /var/lib/apt/lists/*
RUN git clone https://github.com/zeroclaw-labs/zeroclaw.git . \
&& cargo build --release
FROM debian:stable-slim
RUN apt-get update && apt-get install -y ca-certificates \
&& rm -rf /var/lib/apt/lists/*
COPY --from=builder /build/target/release/zeroclaw /usr/local/bin/zeroclaw
WORKDIR /workspace
ENTRYPOINT ["zeroclaw"]
Build and run:
docker build -t zeroclaw .
docker run --rm -it -v "$(pwd)/workspace:/workspace" zeroclaw status
There is an irony worth naming: containerising a 3.4MB binary adds a base image far larger than the thing it contains. If your reason for choosing ZeroClaw was its footprint, Docker gives some of that back. Use it for isolation and deployment consistency, not for size.
Method 8: Android via Termux
Not officially supported, but it works often enough to be worth documenting.
pkg update && pkg upgrade
pkg install rust git build-essential
cargo install zeroclaw
Realistic expectations: compilation on a phone is slow — plan for a long build with the device plugged in and the screen awake, since Android will otherwise suspend the process. Use a hosted model provider rather than a local one; phone RAM does not accommodate both a model and the rest of Android. Termux's own storage restrictions apply on top of ZeroClaw's workspace scoping.
Verifying the installation
Regardless of method:
zeroclaw --version
zeroclaw status
zeroclaw doctor
--version confirms the binary is on your PATH. status reports the runtime's view of its own configuration. doctor runs diagnostics and is the first thing to try when something behaves oddly — it checks configuration validity, provider reachability and channel health, and tells you which of those is broken.
First-run configuration
Once installed, run onboarding to create a starter configuration and store credentials encrypted:
# Non-interactive
zeroclaw onboard --api-key sk-... --provider openrouter
# Interactive wizard
zeroclaw onboard --interactive
# Repair channels and allowlists only
zeroclaw onboard --channels-only
Then confirm it responds:
zeroclaw agent -m "Hello"
Before giving it anything real to do, set your workspace and command allowlist. The security guide explains why that ordering matters, and the config.toml reference covers every key.
Common problems
command not found: zeroclaw — the binary is installed but not on your PATH. Check ~/.cargo/bin or /usr/local/bin, open a new terminal, and add the directory to your shell profile if needed.
Linker errors during cargo build — missing system build dependencies. On Debian and Ubuntu, install build-essential and libssl-dev; on Windows, the Microsoft C++ build tools; on macOS, run xcode-select --install.
The build is killed partway through — the compiler ran out of memory, which is common on small boards. Limit parallelism with cargo build --release -j 1, add swap, or cross-compile on a larger machine and copy the binary over. It is a static binary; that works.
zeroclaw doctor reports the provider is unreachable — usually a bad or unset API key, or an outbound firewall rule. Re-run zeroclaw onboard to re-enter credentials.
Permission denied on the workspace — the directory in config.toml does not exist or is not writable by the user running the agent. Create it and check ownership.
Where to go next
- What is ZeroClaw? — the conceptual introduction if you skipped it
- ZeroClaw security — configure this before the agent does anything real
- config.toml reference — every configuration section explained
- Set up ZeroClaw with Ollama and Telegram — a complete first project