Secure · Small · Efficient · Robust · Simple
Secure AI agents in a single ~5 MB binary.
RavenClaws is a lightweight, memory-safe Rust agent framework with multi-provider LLM support. One static binary. Zero runtime dependencies — no Python, no Node, no JVM.
Self-hostable and air-gappable. Your data and tool calls never leave infrastructure you control — and there is no phone-home.
unsafe forbidden
Cosign-signed · SBOM · provenance
No telemetry, ever
AGPLv3 + Commercial
Published on crates.io
Why RavenClaws
Five pillars. No compromises.
We don't win by out-featuring the field. We win by refusing to bend on five things at once — for a single agent and for a swarm of thousands.
Secure
Memory-safe Rust, fail-closed, no creds in config. Every tool call policy-gated, sandboxed, and audited.
Small
One static binary. Distroless image. A lean dependency tree — it runs on a Raspberry Pi.
Efficient
Native performance, low memory, ~5 ms cold start, streaming everywhere. No interpreter tax.
Robust
Graceful degradation, provider fallback, deterministic config — verified across four deployment targets.
Simple
One command to run. Sensible defaults. Zero external services required for single-agent use.
Capabilities
Everything an agentic worker needs — built in.
A real agent loop, a deny-by-default tool system, multi-provider routing, swarms, and autonomous operation. All in one dependency-light binary that's also a library crate.
Agent loop (ReAct)
perceive → plan → act → observe, with conversation memory, a max-iteration guard, streaming output, and an interactive REPL.
Tools & MCP
Built-in shell, file read/write, web fetch and web search — behind a deny-by-default policy. Full MCP client and server over stdio.
Multi-provider routing
Seven providers behind one trait, with round-robin, intelligent fallback chains, a circuit breaker, and token budgets.
Swarm & supervisor orchestration
Run parallel agents with distinct personas, or let a supervisor decompose a task and spawn sub-agents — recursively. Self-provisioning swarms scale from a handful of collaborators to thousands of workers across star, mesh, hierarchical, and hybrid topologies, with an inter-agent message bus plus health & telemetry.
Autonomous heartbeat
assess → plan → act → persist → sleep. Long-horizon tasks survive restarts and resume from the last checkpoint — runs unattended for days.
Security model
PolicyEngine allow-lists, a workdir sandbox jail, an HMAC-SHA256 tamper-evident audit log, secret zeroization, and prompt-injection defense.
Server & observability
--serve HTTP mode with /health, /ready, /metrics, graceful shutdown, opt-in OpenTelemetry tracing, and an official Helm chart.
Library crate
Use RavenClaws as a dependency — ravenclaws on crates.io exposes all 23 modules through a stable, semver-disciplined public API.
WASM plugin system
Extend RavenClaws without recompiling — load .wasm binaries at runtime via Plugin ABI v1. Tools are discovered, enumerated, and registered into the agent's tool registry automatically.
Browser automation
Drive real browsers via CDP — navigate, click, type, extract, screenshot, and more. 10 built-in actions for end-to-end web interaction.
Multi-modal input
Attach images alongside text in chat messages — PNG, JPEG, GIF, WebP. Supported across all 7 providers via --image CLI flag or library API.
Graceful degradation
Token-bucket rate limiting, error tracking with circuit breakers, and configurable load shedding — keeps the agent responsive under pressure.
SQLite persistence
Conversation history backed by SQLite with configurable retention policies — time-based, count-based, token-budget, or unlimited. Survives restarts and enables long-running sessions.
Verified supply chain
Multi-arch images signed with Cosign, SBOM + build provenance, plus CodeQL, cargo-audit, cargo-deny, Trivy, Hadolint, Kubescape and OSSF Scorecard in CI.
Quick start
From install to first agent in 30 seconds.
Install the binary, point it at any provider, and run a one-shot task — or embed the library in your own Rust project.
# Install from crates.io
cargo install ravenclaws
# Point it at any provider (Ollama = fully local)
export RAVENCLAWS__LLM__PROVIDER="ollama"
export RAVENCLAWS__LLM__MODEL="llama3.1"
# Run a one-shot task, then exit
ravenclaws --exec "Summarize the latest release notes"# Cargo.toml
[dependencies]
ravenclaws = "1.1"
// main.rs
use ravenclaws::{Config, ChatMessage, create_client, LLMProviderTrait};
let config = Config::load()?;
let mut client = create_client(&config.llm)?;
let resp = client.chat(&[ChatMessage {
role: "user".into(),
content: "Hello! What can you do?".into(),
}]).await?;
println!("{}", resp.content);docker run --rm -it \
-e LITELLM_API_KEY="…" \
ghcr.io/egkristi/ravenclaws:latesthelm install ravenclaws \
./charts/ravenclaws \
-n ravenclaws --create-namespaceravenclaws --serve # /health /ready /metrics
ravenclaws --repl # interactive sessionNew here? Follow the Getting Started guide → install, configure a provider, and run a multi-step task with tools.
See it in action
Watch the terminal demo.
An automated walkthrough of RavenClaws v1.1.0 — 11 sections covering version info, binary profile, configuration, modules, tests, exec mode, HTTP server, MCP, Docker/K8s, website, and verification suite.
Bring your own model
Seven providers, one unified API.
Route across cloud and local models with a single trait — then fail over between them automatically. Run fully offline with Ollama, or bring any OpenAI-compatible backend.
How it compares
Parity on table stakes. A wedge cloud agents can't copy.
Anything the field can do, RavenClaws aims to do smaller, safer, and simpler — or deliberately not at all.
| Capability | RavenClaws | Cloud assistants | Minimal runtimes |
|---|---|---|---|
| Agent loop + structured tools | ✓ | ✓ | partial |
| MCP client and server | ✓ both | ✓ | ✕ |
| Deny-by-default security model | ✓ wired | bolted on | ✕ |
| Local-first / air-gapped | ✓ Ollama | ✕ | varies |
| ~5 MB single binary, edge-deployable | ✓ | ✕ cloud | varies |
| No telemetry · signed + SBOM | ✓ | ✕ | varies |
| Autonomous heartbeat (days/weeks) | ✓ | ✓ | ✕ |
| Scalable swarm (1000+ workers) | ✓ | ✕ | ✕ |
| Library crate on crates.io | ✓ | ✕ | varies |
Self-reported from the project roadmap (v1.1.0). Capabilities of third-party tools vary by version and configuration. Azure provider added in v1.1.0.
Trust as a feature
Security wired into the core — not bolted on.
RavenClaws ships a deny-by-default model that's invoked on every tool call, with a verifiable supply chain end to end.
PolicyEngine validates every shell, path, and network call against allow-lists. Empty list means deny.
Sandbox jails tool execution to a workdir with resource limits and timeouts.
Audit log records every operation in an HMAC-SHA256 tamper-evident chain.
No phone-home. Observability is opt-in and self-hosted. Secrets are env-only and zeroized on drop.
Licensing
Open core. Commercial when you scale.
A dual-license model: free and source-available for the community, commercial for large or embedded deployments.
AGPLv3 — Open source
Free for personal use, OSS projects, and commercial use up to 50 agents / $5M revenue.
- Full agent runtime & all 7 providers
- Tools, MCP, sandbox, audit log
- Docker & Kubernetes manifests
- Library crate & the full source
Commercial — Enterprise
For large-scale deployments, embedding without AGPL obligations, or managed-service offerings.
- Use without AGPLv3 obligations
- Swarm & routing at scale, RavenFabric
- RBAC, SSO/SAML, compliance reporting
- Air-gap licensing · priority support & SLA
Secure · Small · Efficient · Robust · Simple
Ship an agent you can actually trust.
One static binary. Seven providers. Swarms that scale to thousands. Self-hostable, air-gappable, and verifiable end to end.