harald/zeroclaw

Fork 0

argenis de la rosa 12112772c5 docs: fix README stats — 8 traits, 9 subcommands, 17,800+ lines, 7 lib modules

2026-02-14 03:36:48 -05:00

17 KiB

Raw Blame History

ZeroClaw

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.

ZeroClaw Architecture

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.

Layer 1: Gateway Hardening

# Default — localhost only, pairing required
zeroclaw gateway

# Random port — OS assigns ephemeral port (49152-65535)
zeroclaw gateway --port 0

# With tunnel — public access via secure tunnel only
zeroclaw gateway  # with [tunnel] configured

On startup, the gateway prints a 6-digit pairing code:

🔐 PAIRING REQUIRED — use this one-time code:
   ┌──────────────┐
   │  482917  │
   └──────────────┘
   Send: POST /pair with header X-Pairing-Code: 482917

After pairing, all subsequent requests use Authorization: Bearer zc_<token>.

[gateway]
require_pairing = true      # default: true
allow_public_bind = false   # default: false — NEVER set true without tunnel

Layer 2: Channel Authentication

Every channel validates the sender before the message reaches the agent loop:

Channel	Auth Method	Config
Telegram	`allowed_users` list (username match)	`[channels.telegram] allowed_users`
Discord	`allowed_users` list (user ID match)	`[channels.discord] allowed_users`
Slack	`allowed_users` list (user ID match)	`[channels.slack] allowed_users`
Matrix	`allowed_users` list (MXID match)	`[channels.matrix] allowed_users`
iMessage	`allowed_contacts` list	`[channels.imessage] allowed_contacts`
Webhook	`X-Webhook-Secret` header (shared secret)	`[channels.webhook] secret`
CLI	Local-only (inherently trusted)	—

Note: An empty allowed_users list or ["*"] allows all users (open mode). Set specific IDs for production.

Layer 3: Rate Limiting

Sliding-window tracker — counts actions within a 1-hour rolling window
max_actions_per_hour — hard cap on tool executions (default: 20)
max_cost_per_day_cents — daily cost ceiling (default: $5.00)

Layer 4: Filesystem Sandbox

Workspace-only mode (default) — all paths must be relative to workspace
14 system directories blocked — /etc, /root, /home, /usr, /bin, /sbin, /lib, /opt, /boot, /dev, /proc, /sys, /var, /tmp
4 sensitive dotfiles blocked — ~/.ssh, ~/.gnupg, ~/.aws, ~/.config
Null byte injection — blocked at the path validation layer
Path traversal — .. in any position is rejected
Symlink escape detection — is_resolved_path_allowed() verifies canonicalized paths stay inside workspace
Command allowlisting — only approved shell commands (git, cargo, ls, etc.)
Autonomy levels — ReadOnly, Supervised (default), Full

Layer 5: Secure Tunnels

Expose your gateway securely — bring your own tunnel provider:

Provider	Binary	Use Case
none	—	Local-only (default)
cloudflare	`cloudflared`	Cloudflare Zero Trust tunnel
tailscale	`tailscale`	Tailnet-only (`serve`) or public (`funnel`)
ngrok	`ngrok`	Quick public URLs, custom domains
custom	Any	Bring your own: bore, frp, ssh, WireGuard, etc.

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

[tunnel.tailscale]
funnel = true            # true = public internet, false = tailnet only

# Or use Cloudflare:
# [tunnel]
# provider = "cloudflare"
# [tunnel.cloudflare]
# token = "your-tunnel-token"

# Or ngrok:
# [tunnel]
# provider = "ngrok"
# [tunnel.ngrok]
# auth_token = "your-ngrok-token"
# domain = "my-zeroclaw.ngrok.io"  # optional

# Or bring your own:
# [tunnel]
# provider = "custom"
# [tunnel.custom]
# start_command = "bore local {port} --to bore.pub"
# url_pattern = "https://"         # regex to extract URL from stdout
# health_url = "http://localhost:4040/api/tunnels"  # optional

The tunnel starts automatically with zeroclaw gateway and prints the public URL.

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"}`

Random Port Mode

Use --port 0 for OS-assigned random ephemeral ports (security hardening against port scanning):

zeroclaw gateway --port 0
# Output: 🦀 ZeroClaw Gateway listening on http://127.0.0.1:54321 (random port)

The actual port is printed on startup and passed to the tunnel system automatically.

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

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

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

Test Coverage

Module	Tests	Covers
Memory (SQLite)	100+	FTS5, vector search, hybrid merge, embeddings, chunker, SQL injection, unicode
Security (Policy)	50+	Path traversal, null bytes, forbidden dirs, workspace scoping, symlink escapes
Security (Pairing)	20+	Code generation, token issuance, constant-time comparison, replay prevention
Gateway	20+	Port 0, random port allocation, header extraction, port conflicts
Config	30+	Serde roundtrip, backward compat, secure defaults, gateway config
Providers	30+	Factory, custom URLs, auth styles
Tools	20+	Schema validation, tool specs, serde
Integrations	15+	Registry completeness, status functions, categories
Tunnel	20+	Factory, constructors, async behavior

Project Structure

src/
├── main.rs              # CLI (clap) — 9 subcommands
├── lib.rs               # Library exports (7 modules)
├── agent/               # Agent loop + memory context injection
│   ├── mod.rs
│   └── loop_.rs
├── channels/            # Channel trait + 7 implementations
│   ├── traits.rs        # Channel trait definition
│   ├── cli.rs           # Local terminal
│   ├── telegram.rs      # Telegram Bot API
│   ├── discord.rs       # Discord bot
│   ├── slack.rs         # Slack bot
│   ├── matrix.rs        # Matrix protocol
│   ├── imessage.rs      # macOS iMessage
│   └── mod.rs           # System prompt builder
├── config/              # TOML config schema
│   ├── schema.rs        # All config structs + defaults
│   └── mod.rs
├── cron/                # Scheduled tasks
├── gateway/             # HTTP gateway (raw TCP + tokio)
│   └── mod.rs           # /health, /pair, /webhook endpoints
├── heartbeat/           # Periodic task engine
│   ├── engine.rs
│   └── mod.rs
├── integrations/        # 50+ integration registry
│   ├── registry.rs      # All integrations across 9 categories
│   └── mod.rs
├── memory/              # Memory trait + hybrid search engine
│   ├── traits.rs        # Memory trait definition
│   ├── sqlite.rs        # SQLite + FTS5 + vector embeddings
│   ├── markdown.rs      # Append-only markdown
│   ├── embeddings.rs    # EmbeddingProvider trait + OpenAI + Noop
│   ├── vector.rs        # Cosine similarity + serialization + hybrid merge
│   ├── chunker.rs       # Markdown-aware document splitting
│   └── mod.rs           # Factory
├── observability/       # Observer trait + 3 backends
│   ├── traits.rs
│   ├── noop.rs
│   ├── log.rs
│   └── multi.rs
├── onboard/             # Interactive setup wizard
│   └── wizard.rs
├── providers/           # Provider trait + 22+ providers
│   ├── traits.rs        # Provider trait definition
│   ├── openrouter.rs    # OpenRouter (default)
│   ├── anthropic.rs     # Anthropic direct
│   ├── openai.rs        # OpenAI direct
│   ├── ollama.rs        # Local Ollama
│   ├── compatible.rs    # OpenAI-compatible adapter (18+ providers)
│   └── mod.rs           # Factory
├── runtime/             # RuntimeAdapter trait + Native
│   ├── traits.rs
│   └── native.rs
├── security/            # Security policy + gateway pairing + secrets
│   ├── policy.rs        # SecurityPolicy, path validation, rate limiting
│   ├── pairing.rs       # PairingGuard, OTP, bearer tokens
│   ├── secrets.rs       # Encrypted secret store (XOR + local key file)
│   └── mod.rs
├── skills/              # Skill loader (TOML manifests)
│   └── mod.rs
├── tools/               # Tool trait + 7 tools
│   ├── traits.rs        # Tool trait definition
│   ├── shell.rs         # Shell command execution
│   ├── file_read.rs     # Sandboxed file reading
│   ├── file_write.rs    # Sandboxed file writing
│   ├── memory_store.rs  # Store to memory
│   ├── memory_recall.rs # Search memory
│   ├── memory_forget.rs # Delete from memory
│   ├── composio.rs      # Composio OAuth tools (optional)
│   └── mod.rs           # Registry
└── tunnel/              # Tunnel trait + 5 implementations
    ├── none.rs          # Local-only (default)
    ├── cloudflare.rs    # Cloudflare Zero Trust
    ├── tailscale.rs     # Tailscale serve/funnel
    ├── ngrok.rs         # ngrok
    ├── custom.rs        # Bring your own
    └── mod.rs           # Factory

examples/
├── custom_provider.rs
├── custom_channel.rs
├── custom_tool.rs
└── custom_memory.rs

tests/
└── memory_comparison.rs  # SQLite vs Markdown benchmark

64 source files · 17,800+ lines of Rust · 1,017 tests · 0 clippy warnings

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. 🦀

17 KiB Raw Blame History