π¦ββ¬ RavenClaws β The Ultimate AI Agentic Worker
Secure Β· Small Β· Efficient Β· Robust Β· Simple. Built in Rust.
RavenClaws is a lightweight, secure Rust agent framework with multi-provider LLM support. One static binary, zero runtime dependencies β no Python, no Node, no JVM.
Status: v0.9.6 (2026-06-02). HTTP agent execution API (
/chat,/execute,/tools,/tasks/{id},/health/deep), MCP TOML config section ([mcp]), multi-MCP-client support via[[mcp.servers]], swarm profile TOML shorthand ([swarm.profiles.name]), config hot-reload (SIGHUP), eval harness tool call assertions (ToolCalled,ToolNotCalled), server mode docs. The provider layer (6 providers), one-shot execution (--exec), reproducible multi-arch builds, verification + supply-chain pipeline, agent loop, tool-use, MCP client, retry/fallback chains, token budgets, native Anthropic integration, swarm mode, supervisor mode, RavenFabric mesh client, MCP server, HTTP server mode, autonomous heartbeat agent, long-horizon task persistence, scheduling/triggers, inter-agent communication bus, swarm health & telemetry, library crate (on crates.io), and eval harness all work today. This README marks β built vs. π planned β honestly. Trust is a feature; we don't inflate it.
| Footprint | Security | Providers | Deployment |
|---|---|---|---|
| ~5.2 MB binary | Memory-safe Rust | 5 providers | Binary Β· Docker Β· K8s |
| 0 runtime deps | Signed images + SBOM | Multi-model | 472 unit tests + 114 verification checks |
| Library crate | 18 modules | crates.io | AGPLv3 + Commercial |
Vision
RavenClaws aims to be the ultimate AI agentic assistant and worker β and the preferred alternative to the field: Nemoclaw, Hermes Agent, TrustClaw, ZeroClaw, PicoClaw, NanoClaw, Claude Cowork, Manus, Perplexity Computer, Kimi Claw, and Vellum.
We don't aim to win by out-featuring them. We win by refusing to compromise on five pillars at once:
- Secure β memory-safe Rust (
unsafeforbidden), fail-closed, no creds in config, verified supply chain. - Small β one static binary (~5 MB), distroless image, lean dependency tree.
- Efficient β native performance, low memory, fast cold start, streaming everywhere.
- Robust β graceful degradation, provider fallback, deterministic config, verified across 4 deployment targets.
- Simple β one command to run, sensible defaults, no external services required for single-agent use.
See the ROADMAP for how we get from here to there.
Why RavenClaws?
Small & efficient
- ~5.2 MB stripped release binary (measured) β no interpreter, no runtime image baggage.
- Single static binary β no Python, no Node, no JVM, zero runtime dependencies.
- Native Rust with
lto+panic=abort. Design targets (benchmarked toward v1.0 via the verification suite): < 50 ms cold start, < 20 MB RSS, < 15 MB binary across all targets.
Secure & trustworthy
- Memory-safe Rust β whole classes of memory-corruption bugs eliminated at compile time.
- No credentials in config β environment variables and Kubernetes Secrets only.
- Hardened containers β distroless, non-root, read-only root filesystem, dropped capabilities, seccomp.
- Verified supply chain β multi-arch images signed with Cosign, SBOM (Syft) and build provenance attestation, plus CodeQL, cargo-audit, cargo-deny, Trivy, Hadolint, Kubescape, and OSSF Scorecard in CI.
- TLS enforced by default for non-local endpoints.
- Deny-by-default tool policy β
PolicyEnginevalidates all tool calls against shell/path/network allow-lists. - Sandboxed tool execution β workdir jail, resource limits, and timeouts via
Sandbox. - Tamper-evident audit log β HMAC-SHA256 chained, structured JSON trail of every tool call.
Multi-provider, multi-model
- LiteLLM β OpenAI-compatible proxy fronting 100+ models.
- OpenAI β native GPT-4o, o-series, and more.
- OpenRouter β unified API for many hosted models.
- Ollama β local, private, air-gapped models.
- Anthropic β direct Claude API (Sonnet, Opus, Haiku) with native tool use.
- Multi-model mode β round-robin + intelligent fallback chains with circuit breaker (v0.5.1+).
Verified across every target
- 452 Rust unit tests across 18 modules (incl.
mockito-backed provider request/response/error paths for all 5 providers, plus RavenFabric, swarm, heartbeat, eval, and scheduler tests), runnable anywhere viacargo test. - Plus a 114-check verification suite (
scripts/verify.sh) spanning 10 modules across 4 deployment targets β local binary, Docker, cross-compiled Linux, and Kubernetes β including security, performance, LLM quality, swarm, and eval checks. - Note: the 114 verification checks are system/integration level (shell-orchestrated, requiring live services such as LiteLLM/Docker/kubectl).
Documentation
- Getting Started Guide β install, configure, and run your first agent
- Configuration Reference β all config options, env vars, and CLI flags
- Swarm Mode Guide β multi-agent orchestration with flat and hierarchical topologies
- MCP Integration Guide β connect to MCP servers or expose tools via MCP
- Heartbeat Mode Guide β autonomous long-running agents
- Server Mode Guide β HTTP API, endpoints, deployment, config hot-reload
- Examples β runnable Rust examples using the library API
- Migration Guide β upgrading between versions (v0.1 β v1.0)
- API Reference β full rustdoc API documentation
Quick Start
30 seconds to your first agent
# Build from source (requires Rust)
# Run with any provider
# β¦or run a one-shot task and exit
Note: Pre-built binaries publish automatically on tagged releases. See the GitHub Releases page for downloads.
Use as a library
RavenClaws is published on crates.io as both a binary and library crate.
Add it to your Cargo.toml:
[]
= "0.9"
Then use the library API in your Rust project:
use ;
async
The library exposes all 18 modules with a stable public API:
| Module | Purpose |
|---|---|
ravenclaws::agent |
Agent implementations, agent loop, conversation memory |
ravenclaws::llm |
LLM provider abstraction + 5 client implementations |
ravenclaws::config |
Configuration structs, TOML/env loading, validation |
ravenclaws::tools |
Tool abstraction, registry, 5 built-in tools |
ravenclaws::policy |
Deny-by-default policy engine |
ravenclaws::sandbox |
Sandboxed execution (workdir jail, resource limits) |
ravenclaws::audit |
Tamper-evident audit log (HMAC-SHA256 chained) |
ravenclaws::mcp |
MCP client + server (JSON-RPC 2.0 over stdio) |
ravenclaws::swarm |
Swarm orchestration, worker profiles, health monitoring |
ravenclaws::heartbeat |
Autonomous heartbeat agent |
ravenclaws::background |
Background task manager with disk persistence |
ravenclaws::scheduler |
Scheduling & triggers (cron, webhook, file-watch) |
ravenclaws::server |
HTTP server mode (health, readiness, metrics, agent execution API) |
ravenclaws::telemetry |
OpenTelemetry tracing (OTLP gRPC/stdout) |
ravenclaws::ravenfabric |
RavenFabric mesh client |
ravenclaws::eval |
Eval harness with assertions, run traces, tool call assertions |
ravenclaws::error |
Unified error types |
Docker
Docker Compose (with LiteLLM)
Kubernetes
Server mode (
--serve) provides a full HTTP API with/health,/ready,/metrics,/health/deep,/chat,/execute,/tasks/{id},/tools, and/tools/{name}endpoints. Supports graceful shutdown, config hot-reload (SIGHUP), and configurable port. See the Server Mode Guide for details.
Configuration
Environment variables
| Variable | Description | Default |
|---|---|---|
RAVENCLAWS__LLM__PROVIDER |
Provider: litellm, openrouter, ollama, openai, anthropic, openai-compatible | litellm |
RAVENCLAWS__LLM__ENDPOINT |
LLM endpoint URL | (provider-dependent) |
RAVENCLAWS__LLM__MODEL |
Default model | gpt-4o-mini |
LITELLM_API_KEY |
API key for LiteLLM/OpenRouter/OpenAI | (required for cloud) |
RAVENCLAWS__LLMS |
JSON array for multi-model config | β |
RAVENCLAWS__RAVENFABRIC__ENDPOINT |
RavenFabric endpoint (optional) | β |
RAVENCLAWS__SECURITY__REQUIRE_TLS |
Enforce TLS | true |
RAVENCLAWS__RUNTIME__MAX_AGENTS |
Max concurrent agents | 10 |
RUST_LOG |
Log level | info |
Single provider mode
LiteLLM:
[]
= "litellm"
= "http://litellm:4000"
= "gpt-4o-mini"
= 30
Ollama (local, no API key):
[]
= "ollama"
= "http://localhost:11434"
= "llama3.1"
= 60
OpenRouter:
[]
= "openrouter"
= "anthropic/claude-sonnet-4-20250514"
Anthropic (Native, v0.5.3+):
[]
= "anthropic"
= "claude-sonnet-4-20250514"
# No endpoint needed β uses https://api.anthropic.com
OpenAI:
[]
= "openai"
= "gpt-4o"
OpenAI-Compatible (vLLM, llama.cpp, LM Studio, TGI, Groq, Together AI, etc.):
[]
= "openai-compatible"
= "http://localhost:8000/v1"
= "meta-llama/Llama-3.1-8B-Instruct"
# No API key required for local inference; set via env var for cloud:
# export RAVENCLAWS__LLM__API_KEY="your-key"
Multi-model mode
Configure several providers at once (basic round-robin today):
[[]]
= "ollama"
= "http://ollama:11434"
= "llama3.1"
[[]]
= "openrouter"
= "anthropic/claude-sonnet-4-20250514"
[[]]
= "anthropic"
= "claude-sonnet-4-20250514"
[[]]
= "openai"
= "gpt-4o"
Full config example
[]
= "litellm"
= "http://litellm:4000"
= "gpt-4o-mini"
= 30
# RavenFabric for remote execution and mesh coordination (v0.6.1)
[]
= "http://ravenfabric:8080"
= true
= ["litellm", "ravenfabric"]
[]
= true
= 3600 # agent sessions auto-terminate after 1 hour (0 = unlimited)
= true # surface present; enforcement on roadmap (v0.4)
[]
= "/workspace"
= 10
= 60
Agent modes
| Mode | Status | Description |
|---|---|---|
single |
β Working | Sends prompt to LLM, logs response (agent loop with ReAct planning) |
single (multi-model) |
β Working | Iterates all configured providers, logs each response |
--exec "<task>" |
β Working | One-shot task execution with streaming, then exit |
--no-final-required |
β v0.9.4 | Don't require FINAL: marker β any non-tool-call response completes the loop |
--repl |
β Working | Interactive REPL with /exit, /reset commands |
--require-approval |
β v0.8 | Human-in-the-loop approval for sensitive tool calls |
--serve |
β v0.7.1 | Long-running HTTP server with health, metrics, agent execution API |
--mcp-server |
β v0.7.0 | Expose RavenClaws tools over MCP protocol |
swarm |
β Working | multiple parallel agents with different personas (single + multi-model); RavenFabric-aware |
supervisor |
β Working | Task decomposition + sub-agent spawning + result aggregation (single + multi-model); RavenFabric-aware |
Building from source
Prerequisites
- Rust 1.86+
- For Linux cross-compilation on macOS:
brew install FiloSottile/musl-cross/musl-cross
Build for host
Cross-compile for all architectures
Git Hooks (Pre-Commit / Pre-Push)
The project includes git hooks that run automated verification before every commit and push:
# Install hooks (one-time setup after cloning)
# Verify hooks are active
# Remove hooks (restore defaults)
Pre-commit (fast β runs in seconds):
cargo fmt --checkβ formattingcargo clippy -D warningsβ lintingcargo test --lockedβ unit tests- Binary size check β warns if over 5MB
- Secrets scan β no hardcoded API keys/tokens
Pre-push (comprehensive β runs in 1-5 minutes):
- Full pre-commit suite
- Release build (
cargo build --release) - Binary integrity (architecture, stripped, size)
- Docker build (if Docker available)
- Security scan (secrets, setuid, Cargo.lock)
Skip hooks (emergency only):
Multi-arch Docker image
Downloads
Note: Pre-built binaries publish automatically on tagged releases. See the GitHub Releases page for downloads.
| Architecture | Target Triple |
|---|---|
| Apple Silicon (M1+) | aarch64-apple-darwin |
| Intel Mac | x86_64-apple-darwin |
| Linux ARM64 | aarch64-unknown-linux-gnu |
| Linux x86_64 (glibc) | x86_64-unknown-linux-gnu |
| Linux x86_64 (musl/static) | x86_64-unknown-linux-musl |
Container images target both linux/amd64 and linux/arm64.
Architecture
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β RavenClaws Agent β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β Agent Modes (β
All Working) β β
β β Single Β· --exec Β· REPL Β· Swarm Β· Supervisor β β
β β (single-provider + multi-model for all modes) β β
β ββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββ β
β β β
β ββββββββββββββββββββββββ΄ββββββββββββββββββββββββββββ β
β β Agent Core β β
β β perceive β plan β act β observe (ReAct loop) β β
β β ConversationMemory Β· max-iteration guard β β
β ββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββ β
β β β
β ββββββββββββββββββββββββ΄ββββββββββββββββββββββββββββ β
β β LLM Provider Abstraction Layer β β
β β ββββββββββ ββββββββββ ββββββββββ ββββββββββ β β
β β βLiteLLM β β OpenAI β βOpenRtr β β Ollama β β β
β β ββββββββββ ββββββββββ ββββββββββ ββββββββββ β β
β β ββββββββββββ ββββββββββββββββββββββββ β β
β β βAnthropic β β MultiModelManager β β β
β β ββββββββββββ β round-robin Β· fallbackβ β β
β β β circuit breaker β β β
β β ββββββββββββββββββββββββ β β
β ββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββ β
β β β
β ββββββββββββββββββββββββ΄ββββββββββββββββββββββββββββ β
β β Security & Infrastructure Layer β β
β β ββββββββββββ ββββββββββββ ββββββββββ ββββββββ β β
β β βPolicy β β Sandbox β βAudit β β MCP ββRaven β β β
β β βEngine β β (jail) β βLog β βClientββFabric β β β
β β ββββββββββββ ββββββββββββ ββββββββββ βββββββββββββββββ β β
β β TLS Β· env-only secrets Β· non-root Β· RBAC β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
ββββββββββββββββββββββββ
β Deployment Targets β
β Binary Β· Docker Β· K8s β
ββββββββββββββββββββββββ
What's implemented vs. planned
| Component | Status | Details |
|---|---|---|
| Single agent (single + multi-model) | β Working | Sends prompt(s), logs response(s) |
| LLM providers (5) | β Working | LiteLLM, OpenAI, OpenRouter, Ollama, Anthropic (unified trait) |
| CLI & env-var overrides | β Working | --provider, --endpoint, --model; layered TOMLβenvβflags |
| Config validation | β Working | TLS enforcement, endpoint checks |
| Container & K8s security | β Working | Distroless, non-root, read-only FS, dropped caps, seccomp, RBAC |
| CI/CD pipeline | β Implemented | fmt + clippy + test, 5-target builds, multi-arch images, Cosign + SBOM + provenance + Trivy, crates.io publish, releases |
| Security scanning | β Implemented | CodeQL, cargo-audit, cargo-deny, Trivy (FS + config), Hadolint, Kubescape, OSSF Scorecard |
| Verification suite | β Working | 114 system/integration checks Β· 10 modules Β· 4 targets (scripts/verify.sh) |
| Rust unit tests | β Working | 452 tests across 18 modules, incl. mockito-backed provider request/response/error paths, RavenFabric, swarm, heartbeat, eval, scheduler |
| Reproducible builds | β Working | Cargo.lock committed (--locked), multi-arch Docker cross-linker, RavenFabric agent checksum-verified |
--exec one-shot mode |
β Working | Run a single task, then exit |
| Interactive REPL | β Working | --repl with /exit, /reset commands |
| Agent loop / ReAct planning | β Working | perceiveβplanβactβobserve with max-iteration guard |
| Tool-use / function calling | β Working | ToolImpl trait + ToolRegistry + 4 built-in tools + agent loop wiring |
| Streaming responses | β Working | SSE streaming for LiteLLM, default fallback for others |
| Conversation memory | β Working | ConversationMemory with configurable max history |
| System prompt / persona | β Working | LLMConfig.system_prompt, CLI --system-prompt, env var |
| Swarm mode | β Working | multiple parallel agents with different personas (single + multi-model) |
| Supervisor mode | β Working | Task decomposition + sub-agent spawning + result aggregation (single + multi-model) |
| MCP client | β Working | JSON-RPC over stdio, tool discovery and registration |
| MCP server | β v0.7.0 | Expose RavenClaws tools over stdio via MCP protocol; --mcp-server flag; policy-checked and audited |
| HTTP server mode | β v0.7.1 | Long-running server with /health, /ready, /metrics; --serve flag; graceful shutdown |
| OpenTelemetry tracing | β v0.7.2 | Opt-in distributed tracing with OTLP gRPC/stdout exporter; #[instrument] spans on agent loop, HTTP server, tools, LLM calls |
| Retry / fallback chains | β Working | Exponential backoff, circuit breaker, token budgets |
| Deny-by-default policy | β Working | PolicyEngine with shell/path/network allow-lists |
| Sandboxed execution | β Working | Workdir jail, resource limits, timeouts |
| Tamper-evident audit log | β Working | HMAC-SHA256 chained, structured JSON |
| Multi-model routing | β Working | next_client() round-robin wired into agent modes |
| RavenFabric integration | β v0.6.1 | Full client module (RavenFabricClient) with health, list_agents, execute, broadcast; wired into all agent modes; 12 unit tests |
How RavenClaws intends to win
RavenClaws is positioned against the field β Nemoclaw, Hermes Agent, TrustClaw, ZeroClaw, PicoClaw, NanoClaw, Claude Cowork, Manus, Perplexity Computer, Kimi Claw, and Vellum β by category:
- vs. cloud / hosted assistants (Claude Cowork, Manus, Perplexity Computer, Kimi Claw): RavenClaws is self-hostable, offline-capable, and source-available under AGPLv3. Your data and tool calls never leave infrastructure you control β and there is no phone-home.
- vs. minimal agent runtimes (ZeroClaw, PicoClaw, NanoClaw, TrustClaw): RavenClaws matches their footprint while adding a real security model (memory-safe core, verified supply chain, deny-by-default tool policy, sandboxing, tamper-evident audit log) plus multi-provider routing with fallback chains.
- vs. SDK / platform plays (Vellum, Hermes Agent, Nemoclaw): RavenClaws is a single dependency-light binary, not a service you rent or a framework you marry. Embed it, ship it, forget it.
| Our commitment | How we back it |
|---|---|
| Memory-safe core | Rust with unsafe forbidden |
| Tiny footprint | ~5.2 MB binary, distroless image, 0 runtime deps |
| Trustworthy releases | Cosign signing Β· SBOM Β· provenance Β· CodeQL Β· Trivy Β· OSSF Scorecard |
| Runs anywhere, privately | Self-hostable, air-gappable, no telemetry |
| Honest about status | β /π markers everywhere; benchmarks published, not asserted |
Where we intend to lead β measurably, by v1.0: smallest footprint in class, sub-50 ms cold start, zero known CVEs, fully self-hostable, signed + SBOM-attested. These are targets we will benchmark and publish, not marketing.
Roadmap
See ROADMAP.md for the full phased plan and the feature gap analysis versus the field.
β
v0.2 β build honest & green (complete): Cargo.lock committed (reproducible
--locked builds), multi-arch Docker cross-linker fixed, RavenFabric agent
checksum-verified, --exec wired, swarm/supervisor fail loudly, version synced, and
a 100+-test mockito-backed Rust suite.
β v0.3 β a real agent (complete): the perceiveβplanβactβobserve loop, interactive REPL, conversation memory, and streaming.
β v0.4 β tools, safety & MCP (complete): function-calling, built-in tools behind a deny-by-default policy, sandboxing, a tamper-evident audit log, and MCP client β the single highest-leverage step to tap the entire tool ecosystem.
β v0.5 β providers and routing (complete): unified OpenAI-compatible client, retry/fallback chains with circuit breaker, token budgets, MCP client integration, native Anthropic provider.
β v0.6 β swarm, supervisor (complete): parallel swarm agents, task-decomposing supervisor, both single-provider and multi-model variants.
The five that matter most toward being preferred: MCP (v0.5.2) Β· agent loop + tools + sandbox (v0.3βv0.4) Β· local-first security model (v0.4) Β· async/background + scheduling (v0.7) Β· RavenFabric distributed execution (v0.6.1).
FAQ
What makes RavenClaws different from other agent frameworks?
RavenClaws is a single static binary (~5.2 MB) with zero runtime dependencies β no Python, no Node.js, no JVM. It's designed to be embedded, shipped, and forgotten. Most agent frameworks are SDKs or services you integrate; RavenClaws is a tool you run.
Do I need an API key?
For local-only use, yes β use Ollama (fully local, no API key). For cloud providers (OpenAI, Anthropic, etc.), you'll need their respective API keys.
Can I use RavenClaws offline?
Yes. With the Ollama provider, everything runs locally with no internet connection required.
How is security handled?
RavenClaws uses a deny-by-default security model:
PolicyEnginevalidates all tool calls against shell/path/network allow-listsSandboxprovides workdir jail with resource limits and timeoutsAuditLogrecords all operations in a tamper-evident HMAC-SHA256 chain- No credentials in config files β environment variables and K8s Secrets only
- Memory-safe Rust with
unsafeforbidden
What's the difference between --exec, --repl, and --serve?
--exec "<task>"β Run a single task and exit (one-shot)--replβ Start an interactive REPL session for back-and-forth conversation--serveβ Start a long-running HTTP server with/health,/ready,/metricsendpoints
Can I use RavenClaws as a library in my Rust project?
Yes. RavenClaws is published on crates.io as both a binary and library crate. Add ravenclaws = "0.9" to your Cargo.toml and use the public API via use ravenclaws::.... See the examples directory for runnable code samples.
How do I upgrade from an older version?
See the Migration Guide for detailed upgrade paths from v0.1 through v1.0.
What deployment targets are supported?
- macOS (aarch64, x86_64) β native binary
- Linux (aarch64, x86_64) β native binary or Docker
- Docker β distroless multi-arch images on GHCR and Docker Hub
- Kubernetes β production-grade manifests with RBAC, network policies, PDBs
How is RavenClaws licensed?
RavenClaws uses a dual-license model β see LICENSING.md for details.
License
RavenClaws uses a dual-license model:
- AGPL-3.0-or-later β open source core. Free for personal use, OSS projects, and commercial use up to 50 agents / $5M revenue.
- Commercial β for large commercial deployments or embedding without AGPL obligations.
See LICENSING.md for the full breakdown.
Contributing
- Fork the repo
- Create a feature branch (
git checkout -b feature/my-feature) - Commit changes (
git commit -am 'Add feature') - Push (
git push origin feature/my-feature) - Open a Pull Request
All contributions require signing a Contributor License Agreement (CLA) β see LICENSING.md.
RavenClaws β Secure Β· Small Β· Efficient Β· Robust Β· Simple. Simply the best. π¦ββ¬