zeroclaw Documentation

Fast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 🦀

32,563 stars Rust Rust 1 file · ~3,603 tokens #agent#agentic#ai#infra#ml#openclaw#os#zeroclaw
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy zeroclaw on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name zeroclaw --restart always ghcr.io/zeroclaw-labs/zeroclaw:latest
Configured Services & Ports
⚙️ zeroclaw
image: ghcr.io/zeroclaw-labs/zeroclaw:latest
🔌 Ports: ${HOST_PORT:-127.0.0.1:42617}:${ZEROCLAW_GATEWAY_PORT:-42617}
docker-compose.yml
yaml (docker-compose.yml) 
# ZeroClaw Docker Compose Example
# 
# Quick start:
#   1. Copy this file and set your API key
#   2. Run: docker compose up -d
#   3. Access gateway at http://localhost:42617
#
# For more info: https://github.com/zeroclaw-labs/zeroclaw

services:
  zeroclaw:
    image: ghcr.io/zeroclaw-labs/zeroclaw:latest
    # For ARM64 environments where the distroless image exits immediately,
    # switch to the Debian compatibility image instead:
    # image: ghcr.io/zeroclaw-labs/zeroclaw:debian
    # Or build locally (distroless, no shell):
    # build: .
    # Or build the Debian variant (includes bash, git, curl):
    # build:
    #   context: .
    #   dockerfile: Dockerfile.debian
    container_name: zeroclaw
    restart: unless-stopped
    
    environment:
      # V0.8.0: single env-var override surface — the schema-mirror grammar
      # `ZEROCLAW_=`. Each `__`
      # is a path separator. Legacy `API_KEY`, `ANTHROPIC_API_KEY`,
      # `OPENAI_API_KEY`, `PROVIDER`, `ZEROCLAW_MODEL` (etc.) fallbacks were
      # eradicated.
      #
      # Pick a typed-family alias and set its api_key + model:
      - ZEROCLAW_providers__models__openrouter__default__api_key=${OPENROUTER_API_KEY:-}
      # - ZEROCLAW_providers__models__openrouter__default__model=anthropic/claude-sonnet-4-20250514
      # - ZEROCLAW_providers__models__anthropic__default__api_key=${ANTHROPIC_API_KEY:-}
      # - ZEROCLAW_providers__models__openai__default__api_key=${OPENAI_API_KEY:-}

      # Listen on the container interface so Docker's published port can reach
      # the gateway. Docker bridge traffic never arrives on container loopback,
      # so a persisted `host = "127.0.0.1"` config stays unreachable without
      # this. `allow_public_bind` only acknowledges the non-loopback listener
      # and silences the startup warning; it does not refuse a public bind.
      # Host-side exposure is bounded by the `ports:` mapping below.
      - ZEROCLAW_gateway__host=0.0.0.0
      - ZEROCLAW_gateway__allow_public_bind=true
      # Default gateway port inside container
      - ZEROCLAW_gateway__port=${ZEROCLAW_GATEWAY_PORT:-42617}
      
    volumes:
      # Persist workspace and config (must match WORKDIR/HOME in Dockerfile)
      - zeroclaw-data:/zeroclaw-data
      
    ports:
      # Published on host loopback only. The in-container listener is
      # `0.0.0.0`, so without this prefix the gateway would be reachable from
      # the LAN, and `require_pairing = false` configs answer unauthenticated
      # requests. To serve other hosts, drop the `127.0.0.1:` prefix (or set
      # HOST_PORT to an explicit interface) and enable pairing or a tunnel.
      # Override HOST_PORT if 42617 is taken.
      - "${HOST_PORT:-127.0.0.1:42617}:${ZEROCLAW_GATEWAY_PORT:-42617}"
    
    # Resource limits
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 32M

    # Health check — uses lightweight status instead of full diagnostics.
    # For images with curl, prefer: curl -f http://localhost:42617/health
    healthcheck:
      test: ["CMD", "zeroclaw", "status", "--format=exit-code"]
      interval: 60s
      timeout: 10s
      retries: 3
      start_period: 10s

volumes:
  zeroclaw-data:

File: README.md

🦀 ZeroClaw — Personal AI Assistant

ZeroClaw is an agent runtime — a single Rust binary you configure and run. It talks to LLM providers (Anthropic, OpenAI, Ollama, and ~20 others), reaches the world through 30+ channels (Discord, Telegram, Matrix, email, voice, webhooks, your own CLI), and acts through tools (shell, browser, HTTP, hardware, custom MCP servers). Everything runs on your machine, with your keys, in your workspace.

Read the Philosophy for the four opinions that shape it.

Install

sh
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | sh
"${CARGO_HOME:-$HOME/.cargo}/bin/zeroclaw" quickstart

Use the Rust-free prebuilt PowerShell path in the Windows setup guide. It installs the current release, updates PATH, and runs Quickstart.

For the guided Unix installer, source builds, app and feature selection, and PATH behavior, compare the installation paths.

Run ./install.sh --help for the complete Unix installer flag reference.

Working on the docs? The translated documentation catalogues live in a
git submodule (docs/book/po). The Rust build does not need it, but building
or syncing the docs does. Clone with it, or add it to an existing clone:

bash
git clone --recurse-submodules https://github.com/zeroclaw-labs/zeroclaw.git
git submodule update --init docs/book/po   # existing clone

Platform-specific notes: Linux · macOS · Windows · FreeBSD · NixOS · Docker

Quick start

bash
zeroclaw quickstart               # one-shot setup: pick a provider, write a working config
zeroclaw agent -a <alias>         # interactive chat using the [agents.<alias>] entry
zeroclaw service install          # register as systemd/launchctl/Windows Service
zeroclaw service start            # run it always-on in the background

Full walkthrough: Quick start — or skip the safety gates with YOLO mode for dev boxes.

What ZeroClaw does

  • Multi-channel — one agent answering you across every channel you configure. Inbound messages from Discord, Telegram, Matrix, email, webhooks, CLI — all delivered to the same agent loop.
  • Provider-agnostic — model providers are pluggable. Configure Anthropic, OpenAI, local Ollama, or any OpenAI-compatible endpoint. Fallback chains and routing keep the agent running when a provider flakes.
  • Security-first, with escape hatches — default autonomy is supervised: medium-risk ops require approval, high-risk blocked. Workspace boundaries, command policy, OS-level sandboxes (Landlock / Bubblewrap / Seatbelt / Docker), and cryptographic tool receipts on every action. YOLO mode exists for trusted dev environments.
  • Hardware-capable — GPIO / I2C / SPI / USB on Raspberry Pi, STM32, Arduino, and ESP32 via the Peripheral trait. See Hardware.
  • Gateway + dashboard — HTTP / WebSocket gateway for clients, with a web dashboard for chat, memory browsing, config editing, cron management, and tool inspection.
  • SOP engine — event-triggered Standard Operating Procedures (MQTT / webhook / cron / peripheral) with approval gates and resumable runs.
  • ACP — IDE / editor integration via Agent Client Protocol (JSON-RPC 2.0 over stdio).

Configuration

One TOML file at ~/.zeroclaw/config.toml. Pointers:

A V3 config has at minimum four section headers (<type>.<alias> shaped) — a provider entry, an agent that references it, and a risk profile the agent gates against. See Provider Configuration → Minimal working example for the canonical four-section form with inline type/alias commentary.

For standard OpenAI Codex subscription auth, Quickstart can write the provider
entry for you:

bash
zeroclaw auth login --model-provider openai-codex --import ~/.codex/auth.json  # if already signed in with Codex CLI
zeroclaw quickstart --model-provider openai-codex --model gpt-5.4

The provider entry uses the canonical OpenAI shape; the alias below is an
example:

toml
[providers.models.openai.coding]   # type = openai; alias = coding (you choose)
model = "gpt-5.4"
wire_api = "responses"
requires_openai_auth = true

…and point your agent at it with model_provider = "openai.<alias>".

Notes:

  • Normal OpenAI Codex subscription auth uses stored auth profiles, not an api_key on the provider entry.
  • Claude Max setup-token auth stays on the canonical Anthropic slot: run claude setup-token, choose setup_token in Quickstart, and paste the generated token into the API key/token prompt.
  • Only set api_key / uri on [providers.models.openai.<alias>] when intentionally targeting a custom OpenAI-compatible gateway or endpoint.
  • If you see provider streaming failed, falling back to non-streaming chat, ZeroClaw retries the same request in non-streaming mode. Check zeroclaw auth status before changing provider config.

Architecture

text
┌──────────────────────────────────────────────────────────────┐
│            channels       gateway        ACP                 │
│          (30+ adapters)   (REST/WS)    (JSON-RPC)            │
│                        ↓                                     │
│                   ZeroClaw runtime                           │
│         ┌──────────┬──────────┬──────────┐                   │
│         │  agent   │ security │   SOP    │                   │
│         │   loop   │  policy  │  engine  │                   │
│         └──────────┴──────────┴──────────┘                   │
│              ↓          ↓           ↓                        │
│          providers    tools      memory                      │
│         (Anthropic,  (shell,    (SQLite,                     │
│          OpenAI,     browser,    embeddings)                 │
│          Ollama,     HTTP,                                   │
│          ~20 more)   hardware)                               │
└──────────────────────────────────────────────────────────────┘

Full detail with Mermaid diagrams: Architecture overview · Request lifecycle · Crates.

Contributing

Start with how to contribute. Larger changes go through the RFC process. Real-time chat lives on Discord (the best way to reach the team); durable work tracking is on GitHub issues.

Good places to start:

  • New channel → crates/zeroclaw-channels/
  • New provider → crates/zeroclaw-providers/
  • New tool → crates/zeroclaw-tools/
  • Hardware support → crates/zeroclaw-hardware/
  • Docs → docs/book/src/

AI-assisted PRs are welcome; see Contribution culture (RFC #5615) for the co-authorship norms.

Security

Do not file public issues for security vulnerabilities. Email [email protected]. See SECURITY.md for the full policy.

Official repository & impersonation notice

This is the only official ZeroClaw repository:

https://github.com/zeroclaw-labs/zeroclaw

Any other repository, organization, domain, or package claiming to be "ZeroClaw" or implying affiliation with ZeroClaw Labs is unauthorized and not affiliated with this project.

License

Dual-licensed: MIT OR Apache 2.0. You may choose either. Contributors automatically grant rights under both — see CLA. The ZeroClaw name and logo are trademarks of ZeroClaw Labs.

Credits

Built and maintained by the community — original creator @theonlyhennygod; project lead @JordanTheJet. Full maintainer list in Communication.

Thanks to the communities that incubated early work: Harvard University, MIT, Sundai Club, and every contributor pushing it forward.

File: dev/README.md

ZeroClaw Development Environment

A fully containerized development sandbox for ZeroClaw agents. This environment allows you to develop, test, and debug the agent in isolation without modifying your host system.

Directory Structure

  • agent/: (Merged into root Dockerfile)
    • The development image is built from the root Dockerfile using the dev stage (target: dev).
    • Based on debian:bookworm-slim (unlike production distroless).
    • Includes bash, curl, and debug tools.
  • sandbox/: Dockerfile for the simulated user environment.
    • Based on ubuntu:22.04.
    • Pre-loaded with git, python3, nodejs, npm, gcc, make.
    • Simulates a real developer machine.
  • docker-compose.yml: Defines the services and dev-net network.
  • cli.sh: Helper script to manage the lifecycle.

Usage

Run all commands from the repository root using the helper script:

1. Start Environment

bash
./dev/cli.sh up

Builds the agent from source and starts both containers.

2. Enter Agent Container (`zeroclaw-dev`)

bash
./dev/cli.sh agent

Use this to run zeroclaw CLI commands manually, debug the binary, or check logs internally.

  • Path: /zeroclaw-data
  • User: nobody (65534)

3. Enter Sandbox (`sandbox`)

bash
./dev/cli.sh shell

Use this to act as the "user" or "environment" the agent interacts with.

  • Path: /home/developer/workspace
  • User: developer (sudo-enabled)

4. Development Cycle

  1. Make changes to Rust code in src/.
  2. Rebuild the agent:
    bash
    ./dev/cli.sh build
  3. Test changes inside the container:
    bash
    ./dev/cli.sh agent
# inside container:
zeroclaw --version

5. Persistence & Shared Workspace

The playground/ directory (in repo root) is mounted as the shared workspace:

  • Agent: /zeroclaw-data/workspace
  • Sandbox: /home/developer/workspace

Files created by the agent are visible to the sandbox user, and vice versa. The directory is git-ignored and auto-populated on first run — the agent creates brain.db, sessions.db, personality files (IDENTITY.md, SOUL.md), and hygiene state automatically.

The agent configuration lives in target/.zeroclaw (mounted to /zeroclaw-data/.zeroclaw), so settings persist across container rebuilds.

6. Cleanup

Stop containers and remove volumes and generated config:

bash
./dev/cli.sh clean

Note: This removes target/.zeroclaw (config/DB) but leaves the playground/ directory intact. To fully wipe workspace data, manually delete playground/.

Local CI/CD (Docker-Only)

Use this when you want CI-style validation without relying on GitHub Actions and without running Rust toolchain commands on your host.

1. Build the local CI image

bash
./dev/ci.sh build-image

2. Run full local CI pipeline

bash
./dev/ci.sh all

This runs inside a container:

  • ./scripts/ci/rust_quality_gate.sh
  • cargo test --locked --verbose
  • cargo build --release --locked --verbose
  • cargo deny check licenses sources
  • cargo audit
  • Docker smoke build (docker build --target dev ... + --version check)

To run an opt-in strict lint audit locally:

bash
./dev/ci.sh lint-strict

3. Run targeted stages

bash
./dev/ci.sh lint
./dev/ci.sh test
./dev/ci.sh build
./dev/ci.sh deny
./dev/ci.sh audit
./dev/ci.sh security
./dev/ci.sh docker-smoke
# Optional host-side docs gate (changed-line markdown lint)
./scripts/ci/docs_quality_gate.sh
# Optional host-side docs links gate (changed-line added links)
./scripts/ci/docs_links_gate.sh

Note: local deny focuses on license/source policy; advisory scanning is handled by audit.

4. Enter CI container shell

bash
./dev/ci.sh shell

5. Optional shortcut via existing dev CLI

bash
./dev/cli.sh ci
./dev/cli.sh ci lint

Isolation model

  • Rust compilation, tests, and audit/deny tools run in zeroclaw-local-ci container.
  • Your host filesystem is mounted at /workspace; no host Rust toolchain is required.
  • Cargo build artifacts are written to container volume /ci-target (not your host target/).
  • Docker smoke stage uses your Docker daemon to build image layers, but build steps execute in containers.

Build cache notes

  • Both Dockerfile and dev/ci/Dockerfile use BuildKit cache mounts for Cargo registry/git data.
  • The root Dockerfile also caches Rust target/ (id=zeroclaw-target) to speed repeat local image builds.
  • Local CI reuses named Docker volumes for Cargo registry/git and target outputs.
  • ./dev/ci.sh docker-smoke and ./dev/ci.sh all now use docker buildx local cache at .cache/buildx-smoke when available.
  • The CI image keeps Rust toolchain defaults from rust:1.96-slim and installs pinned toolchain 1.96.1 (no custom CARGO_HOME/RUSTUP_HOME overrides), preventing repeated toolchain bootstrapping on each run.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#agent Browse agent catalog → #agentic Browse agentic catalog → #ai Browse ai catalog → #infra Browse infra catalog → #ml Browse ml catalog → #openclaw Browse openclaw catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →