zeroclaw/README.md

ZeroClaw 🦀

Zero overhead. Zero compromise. 100% Rust. 100% Agnostic.

The fastest, smallest, fully autonomous AI assistant — deploy anywhere, swap anything.

~3.4MB binary · <10ms startup · 1,017 tests · 22+ providers · 8 traits · Pluggable everything

Quick Start

git clone https://github.com/theonlyhennygod/zeroclaw.git
cd zeroclaw
cargo build --release

# Quick setup (no prompts)
cargo run --release -- onboard --quick --api-key sk-... --provider openrouter

# Or interactive wizard
cargo run --release -- onboard

# Chat
cargo run --release -- agent -m "Hello, ZeroClaw!"

# Interactive mode
cargo run --release -- agent

# Start the gateway (webhook server)
cargo run --release -- gateway                # default: 127.0.0.1:8080
cargo run --release -- gateway --port 0       # random port (security hardened)

# Check status
cargo run --release -- status --verbose

# List tools (includes memory tools)
cargo run --release -- tools list

# Test a tool directly
cargo run --release -- tools test memory_store '{"key": "lang", "content": "User prefers Rust"}'
cargo run --release -- tools test memory_recall '{"query": "Rust"}'

# List integrations
cargo run --release -- integrations list

Tip: Run cargo install --path . to install zeroclaw globally, then use zeroclaw instead of cargo run --release --.

Architecture

Every subsystem is a trait — swap implementations with a config change, zero code changes.

Subsystem	Trait	Ships with	Extend
AI Models	Provider	22+ providers (OpenRouter, Anthropic, OpenAI, Ollama, Venice, Groq, Mistral, xAI, DeepSeek, Together, Fireworks, Perplexity, Cohere, Bedrock, etc.)	custom:https://your-api.com — any OpenAI-compatible API
Channels	Channel	CLI, Telegram, Discord, Slack, iMessage, Matrix, Webhook	Any messaging API
Memory	Memory	SQLite with hybrid search (FTS5 + vector cosine similarity), Markdown	Any persistence backend
Tools	Tool	shell, file_read, file_write, memory_store, memory_recall, memory_forget, composio (optional)	Any capability
Observability	Observer	Noop, Log, Multi	Prometheus, OTel
Runtime	RuntimeAdapter	Native (Mac/Linux/Pi)	Docker, WASM
Security	SecurityPolicy	Gateway pairing, sandbox, allowlists, rate limits, filesystem scoping, encrypted secrets	—
Tunnel	Tunnel	None, Cloudflare, Tailscale, ngrok, Custom	Any tunnel binary
Heartbeat	Engine	HEARTBEAT.md periodic tasks	—
Skills	Loader	TOML manifests + SKILL.md instructions	Community skill packs
Integrations	Registry	50+ integrations across 9 categories	Plugin system

Memory System (Full-Stack Search Engine)

All custom, zero external dependencies — no Pinecone, no Elasticsearch, no LangChain:

Layer	Implementation
Vector DB	Embeddings stored as BLOB in SQLite, cosine similarity search
Keyword Search	FTS5 virtual tables with BM25 scoring
Hybrid Merge	Custom weighted merge function (vector.rs)
Embeddings	EmbeddingProvider trait — OpenAI, custom URL, or noop
Chunking	Line-based markdown chunker with heading preservation
Caching	SQLite embedding_cache table with LRU eviction
Safe Reindex	Rebuild FTS5 + re-embed missing vectors atomically

The agent automatically recalls, saves, and manages memory via tools.

[memory]
backend = "sqlite"          # "sqlite", "markdown", "none"
auto_save = true
embedding_provider = "openai"
vector_weight = 0.7
keyword_weight = 0.3

Security

ZeroClaw enforces security at every layer — not just the sandbox. It passes all items from the community security checklist.

Security Checklist

#	Item	Status	How
1	Gateway not publicly exposed	✅	Binds 127.0.0.1 by default. Refuses 0.0.0.0 without tunnel or explicit allow_public_bind = true.
2	Pairing required	✅	6-digit one-time code on startup. Exchange via POST /pair for bearer token. All /webhook requests require Authorization: Bearer <token>.
3	Filesystem scoped (no /)	✅	workspace_only = true by default. 14 system dirs + 4 sensitive dotfiles blocked. Null byte injection blocked. Symlink escape detection via canonicalization.
4	Access via tunnel only	✅	Gateway refuses public bind without active tunnel. Supports Tailscale, Cloudflare, ngrok, or any custom tunnel.

Run your own nmap: nmap -p 1-65535 <your-host> — ZeroClaw binds to localhost only, so nothing is exposed unless you explicitly configure a tunnel.

Configuration

Config: ~/.zeroclaw/config.toml (created by onboard)

api_key = "sk-..."
default_provider = "openrouter"
default_model = "anthropic/claude-sonnet-4-20250514"
default_temperature = 0.7

[memory]
backend = "sqlite"              # "sqlite", "markdown", "none"
auto_save = true
embedding_provider = "openai"   # "openai", "noop"
vector_weight = 0.7
keyword_weight = 0.3

[gateway]
require_pairing = true          # require pairing code on first connect
allow_public_bind = false       # refuse 0.0.0.0 without tunnel

[autonomy]
level = "supervised"            # "readonly", "supervised", "full"
workspace_only = true
allowed_commands = ["git", "npm", "cargo", "ls", "cat", "grep"]
forbidden_paths = ["/etc", "/root", "/proc", "/sys", "~/.ssh", "~/.gnupg", "~/.aws"]

[heartbeat]
enabled = false
interval_minutes = 30

[tunnel]
provider = "none"               # "none", "cloudflare", "tailscale", "ngrok", "custom"

[secrets]
encrypt = true                  # API keys encrypted with local key file

[composio]
enabled = false                 # opt-in: 1000+ OAuth apps via composio.dev

Gateway API

Endpoint	Method	Auth	Description
/health	GET	None	Health check (always public, no secrets leaked)
/pair	POST	X-Pairing-Code header	Exchange one-time code for bearer token
/webhook	POST	Authorization: Bearer <token>	Send message: {"message": "your prompt"}

Commands

Command	Description
onboard	Setup wizard (--quick for non-interactive)
agent -m "..."	Single message mode
agent	Interactive chat mode
gateway	Start webhook server (default: 127.0.0.1:8080)
gateway --port 0	Random port mode
status -v	Show full system status
tools list	List available tools
tools test <name> <json>	Test a tool directly
integrations list	List all 50+ integrations

Development

cargo build              # Dev build
cargo build --release    # Release build (~3.4MB)
cargo test               # 1,017 tests
cargo clippy             # Lint (0 warnings)
cargo fmt                # Format

# Run the SQLite vs Markdown benchmark
cargo test --test memory_comparison -- --nocapture

License

MIT — see LICENSE

Contributing

See CONTRIBUTING.md. Implement a trait, submit a PR:

• New Provider → src/providers/
• New Channel → src/channels/
• New Observer → src/observability/
• New Tool → src/tools/
• New Memory → src/memory/
• New Tunnel → src/tunnel/
• New Skill → ~/.zeroclaw/workspace/skills/<name>/

---

ZeroClaw — Zero overhead. Zero compromise. Deploy anywhere. Swap anything. 🦀