Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/openagen/zeroclaw/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers common setup and runtime failures and the fastest path to resolving each one. For any issue, run zeroclaw doctor first — it performs a full configuration and connectivity check and often identifies the root cause immediately. 
zeroclaw doctor
If doctor does not surface the problem, use the category sections below to dig deeper.

​
Startup and installation issues

Symptom: bootstrap exits with cargo is not installed.Install Rust toolchain via the installer flag:
./install.sh --install-rust
Or install directly from rustup.rs.
Symptom: build fails due to compiler or pkg-config errors.
./install.sh --install-system-deps
Symptoms:
  • cargo build --release is killed (signal: 9, OOM killer, or cannot allocate memory)
  • Build crashes after adding swap because disk space runs out
Runtime memory is under 5 MB for common operations, but a full source build can require 2 GB RAM + swap and 6+ GB free disk. Enabling swap on a small disk avoids RAM OOM but can still fail from disk exhaustion.
1

Use a prebuilt binary (preferred)

./install.sh --prefer-prebuilt
For binary-only mode with no source fallback:
./install.sh --prebuilt-only
2

If you must compile from source

Only add swap if you also have enough free disk for both swap and build output. Then limit cargo parallelism:
CARGO_BUILD_JOBS=1 cargo build --release --locked
3

Reduce heavy features

When Matrix is not required, build with a smaller feature set:
cargo build --release --locked --features hardware
4

Cross-compile on a stronger machine

Compile on a host with adequate resources and copy the binary to the target host.
Symptoms:
  • cargo check / cargo build appears stuck at Checking zeroclaw for a long time
  • Repeated Blocking waiting for file lock on package cache or build directory
ZeroClaw’s Matrix E2EE stack (matrix-sdk, ruma, vodozemac) is large and expensive to type-check. TLS and crypto native build scripts (aws-lc-sys, ring) add noticeable compile time. rusqlite with bundled SQLite compiles C code locally. Running multiple cargo jobs or worktrees in parallel causes lock contention.Generate a timing report:
cargo check --timings
The report is written to target/cargo-timings/cargo-timing.html. Check for duplicate dependencies:
cargo tree -d
For faster local iteration when Matrix channel is not needed:
cargo check
To check with Matrix support:
cargo check --features channel-matrix
To check with Matrix, Lark, and hardware support:
cargo check --features hardware,channel-matrix,channel-lark
To find and stop competing cargo processes causing lock contention:
pgrep -af "cargo (check|build|test)|cargo check|cargo build|cargo test"
Symptom: install succeeds but the shell cannot find zeroclaw.
export PATH="$HOME/.cargo/bin:$PATH"
which zeroclaw
Persist this in your shell profile (~/.bashrc, ~/.zshrc, etc.) to survive new sessions.

​
Channel issues

Cause: multiple pollers are using the same bot token.Stop all extra zeroclaw daemon or zeroclaw channel start processes so only one runtime is active for that token.
Run the channel-specific health check:
zeroclaw channel doctor
Then verify the channel’s credentials and allowlist fields in ~/.zeroclaw/config.toml.

​
Gateway and auth issues

Run diagnostics:
zeroclaw status
zeroclaw doctor
Check ~/.zeroclaw/config.toml for the following fields:
  • [gateway].host — default 127.0.0.1
  • [gateway].port — default 42617
  • allow_public_bind — only set this when intentionally exposing LAN or public interfaces
1

Confirm pairing completed

Ensure the /pair flow was completed successfully.
2

Verify bearer token

Confirm the bearer token is current and has not expired.
3

Re-run diagnostics

zeroclaw doctor

​
Service mode issues

Check service state:
zeroclaw service status
Restart the service:
zeroclaw service stop
zeroclaw service start
On Linux, inspect journald logs:
journalctl --user -u zeroclaw.service -f

​
Collecting diagnostics for a bug report

If you are still stuck after following the steps above, collect these outputs before filing an issue: 
zeroclaw --version
zeroclaw status
zeroclaw doctor
zeroclaw channel doctor
Include your OS, install method, and sanitized config snippets with all secrets removed.

​
Install script

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash

Build docs developers (and LLMs) love

Get started for freeTalk to us