Quick Start Guide

Get your first ZeroClaw agent running in under 5 minutes

Quick Start

Get ZeroClaw installed and running your first AI agent in minutes.

Prerequisites

You’ll need an API key from one of the supported providers. We recommend OpenRouter for quick starts (supports 200+ models with a single key).

Get one at openrouter.ai/keys — free tier available.

Installation

Choose your preferred installation method:

Homebrew (macOS/Linux)

brew install zeroclaw

Fastest method for macOS and Linuxbrew users. Pre-built binaries, no compilation needed.

Clone + Bootstrap

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./bootstrap.sh

This method builds from source. Requires:

• 2GB RAM (+ swap recommended)
• 6GB free disk space
• Rust toolchain (installed automatically with --install-rust)

Cargo Install

cargo install zeroclaw

Compiles from source via crates.io. Same resource requirements as bootstrap method.

Pre-built Binary

For low-resource systems (Raspberry Pi, embedded):

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./bootstrap.sh --prefer-prebuilt

Downloads the latest release binary for your platform. Falls back to source build if no match found.

Use --prebuilt-only to fail instead of falling back to source builds.

First-Time Setup

Run the onboarding wizard to configure your agent:

zeroclaw onboard

You’ll be prompted for:

1. Provider Selection

   Choose your AI provider (default: openrouter)

   Popular options:

   • openrouter — Multi-provider gateway (200+ models)
   • anthropic — Claude models
   • openai — GPT-4, GPT-5
   • ollama — Local models
2. API Key

   Enter your API key (securely encrypted at rest using ChaCha20-Poly1305)

   # Environment variable (temporary)
   export API_KEY="sk-or-v1-..."
   zeroclaw onboard
   
   # Or provide inline (non-interactive)
   zeroclaw onboard --api-key "sk-or-v1-..." --provider openrouter
   
3. Model Selection

   Pick a default model (optional — smart defaults provided)

   Examples:

   • anthropic/claude-sonnet-4.6 (default for OpenRouter)
   • gpt-5.2 (OpenAI)
   • llama3.2 (Ollama)
4. Memory Backend

   Choose how to store conversation history:

   • sqlite (default) — Embedded, zero-config
   • markdown — Human-readable, git-friendly
   • postgres — Distributed, multi-instance
   • lucid — High-performance vector search
   • none — Stateless mode
5. OTP Pairing (Recommended)

   Enable gateway authentication with time-based OTP?

   Recommended for security. Prevents unauthorized API access.

   Skip with --no-totp if testing locally behind a firewall.

Skip the wizard? Use non-interactive mode:

zeroclaw onboard \
  --api-key "$API_KEY" \
  --provider openrouter \
  --model "anthropic/claude-sonnet-4.6" \
  --memory sqlite

Start Your Agent

Option 1: Interactive Chat

Direct command-line chat session:

zeroclaw chat "Hello! What can you help me with?"

For multi-turn conversations, start the agent loop:

zeroclaw agent

Type your messages and press Enter. The agent can:

• Execute shell commands (with approval)
• Read and write files in your workspace
• Search the web
• Call custom tools

By default, all tool executions require user approval. Configure autonomy levels in config.toml to adjust this behavior.

Option 2: Gateway + Dashboard

Start the HTTP gateway server with web UI:

zeroclaw gateway

By default, the gateway listens on http://127.0.0.1:3000/

1. Access Dashboard

   Open the URL shown in startup logs (usually http://127.0.0.1:3000/)

2. Pair Device (if OTP enabled)

   Enter the 6-digit TOTP code from your authenticator app

3. Send Messages

   Use the web UI or POST to /api/chat:

   curl -X POST http://127.0.0.1:3000/api/chat \
     -H "Content-Type: application/json" \
     -d '{"message": "List files in current directory"}'
   

The gateway supports Server-Sent Events (SSE) for streaming responses. Connect via /api/stream for real-time output.

Option 3: Channel Integration

Connect to communication platforms:

Telegram

zeroclaw channel setup telegram
# Follow prompts to enter bot token

zeroclaw channel run telegram

Run multiple channels simultaneously with the daemon mode:

zeroclaw service start

This starts all configured channels in the background.

Example Workflows

1. File Operations

zeroclaw chat "Create a README.md with project description"
zeroclaw chat "Search for TODO comments in src/ directory"
zeroclaw chat "Count lines of Rust code in this project"

2. Web Research

zeroclaw chat "Search for latest Rust async best practices"
zeroclaw chat "Fetch and summarize https://blog.rust-lang.org/"

3. Code Analysis

zeroclaw chat "Analyze the architecture of src/agent/mod.rs"
zeroclaw chat "Suggest performance improvements for this codebase"

4. System Administration

zeroclaw chat "Check disk usage and clean up logs older than 30 days"
zeroclaw chat "Monitor CPU temperature and alert if over 80°C"

Shell commands execute with your user permissions. Review approval prompts carefully before accepting destructive operations.

Configuration Files

After onboarding, you’ll find:

~/.zeroclaw/
├── config.toml          # Main configuration
├── .secret_key          # Encryption key (DO NOT COMMIT)
├── workspace/           # Agent workspace directory
└── memory/              # Conversation history (sqlite/markdown)

Quick Config Edits

# ~/.zeroclaw/config.toml

# Change default model
default_model = "anthropic/claude-sonnet-4.6"
default_temperature = 0.7

# Adjust autonomy (approve, auto, supervised)
[autonomy]
level = "approve"  # Require approval for all tools
file_operations = "auto"  # Auto-approve file reads
shell_commands = "approve"  # Always ask for shell commands

# Configure gateway
[gateway]
host = "127.0.0.1"
port = 3000
pairing_required = true

See Configuration Guide for full reference.

Next Steps

Installation Details

Platform-specific instructions, Docker setup, hardware builds

Configuration Guide

Deep dive into config.toml, environment variables, advanced settings

Tool Reference

Built-in tools, custom tool creation, WASM plugins

Channel Setup

Configure Telegram, Discord, Slack, Matrix, and more

Troubleshooting

Command not found: zeroclaw

Ensure ~/.cargo/bin is in your PATH:

export PATH="$HOME/.cargo/bin:$PATH"

# Add to ~/.bashrc or ~/.zshrc to persist
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc

Build fails with 'out of memory'

Source builds need ~2GB RAM. Solutions:

1. Use pre-built binaries: ./bootstrap.sh --prefer-prebuilt
2. Enable swap space:
   sudo dd if=/dev/zero of=/swapfile bs=1M count=2048
   sudo mkswap /swapfile
   sudo swapon /swapfile
   
3. Reduce parallelism: CARGO_BUILD_JOBS=1 ./bootstrap.sh

Provider returns 401 Unauthorized

Check your API key:

# Re-run onboarding
zeroclaw onboard --force

# Or edit config directly
nano ~/.zeroclaw/config.toml

Verify the key is valid at your provider’s dashboard.

Gateway won't start (port in use)

Another service is using port 3000:

# Find the process
lsof -i :3000

# Change ZeroClaw port
zeroclaw gateway --port 3001

# Or edit config
# [gateway]
# port = 3001

For more troubleshooting, see the Troubleshooting Guide in the repository.