zeroclaw README

The project's README from github.com/zeroclaw-labs/zeroclaw. As one markdown file: README.md.

ZeroClaw

🦀 ZeroClaw — Personal AI Assistant

You own the agent. You own the data. You own the machine it runs on.

Build Status Latest release License Rust Edition 2024 Contributors Discord

Website · Docs · Philosophy · Quick start · Architecture · Discord


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

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:

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

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

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:

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:

[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:

Architecture

┌──────────────────────────────────────────────────────────────┐
│            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:

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.

Star History Chart

ZeroClaw contributors

zeroclaw (zeroclaw-labs/zeroclaw)

email
Searching Database…

What is this?ZeroClaw is a personal AI assistant runtime: a single Rust binary you configure and run yourself, which talks to LLM providers, listens on dozens of channels, and acts through tools like shell, browser and HTTP.
Is this an app or a runtime I configure myself?It is not a hosted app — it is an agent runtime binary you deploy and configure with a TOML file, wiring up providers, channels and tools yourself.
How do I get it running?On Unix, run the install.sh script (install.sh --help shows all flags); on Windows, use the prebuilt PowerShell path from the Windows setup guide, which installs the release, updates PATH, and runs Quickstart.
Which LLM providers does it need an account with?It talks to Anthropic, OpenAI, local Ollama, or about 20 other providers (including any OpenAI-compatible endpoint), configured in a [providers.models.*] block in config.toml.
What's the catch with the config file?A working config needs at least four TOML section headers (a provider entry, an agent referencing it, and a risk profile it gates against); if a provider's streaming fails, ZeroClaw silently retries non-streaming.
Which operating systems does it support?Linux, macOS, Windows, FreeBSD, NixOS, and Docker all have platform-specific install notes.
Where does my data and keys actually live?Everything runs on your own machine with your own API keys and workspace; nothing is routed through a vendor-hosted service.
What stops it from running dangerous commands on my machine?By default autonomy is supervised: medium-risk operations require approval and high-risk ones are blocked, backed by workspace boundaries, command policy and OS-level sandboxes (Landlock, Bubblewrap, Seatbelt, Docker). A YOLO mode exists to skip these gates on trusted dev boxes.
Can it control physical hardware, not just chat?Yes — through the Peripheral trait it can drive GPIO, I2C, SPI and USB on devices like Raspberry Pi, STM32, Arduino and ESP32.
Can it hook into my IDE?Yes, via ACP (Agent Client Protocol), a JSON-RPC 2.0 over stdio integration for editors and IDEs.
What is the SOP engine for?It runs event-triggered Standard Operating Procedures (fired by MQTT, webhook, cron or hardware peripheral events) with approval gates and resumable runs, letting the agent carry out multi-step automated workflows.
Size
254.3 MB
Stars
33K
Age
8mo
Commits · 90 Days