RavenClaws 0.9.9

Lightweight, secure Rust agent framework with multi-provider LLM support
Documentation

πŸ¦β€β¬› RavenClaws β€” The Ultimate AI Agentic Worker

Secure Β· Small Β· Efficient Β· Robust Β· Simple. Built in Rust.

🌐 https://ravenclaws.io

License CI Verification Binary Library Status

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 (unsafe forbidden), 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 β€” PolicyEngine validates 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 via cargo 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

Quick Start

30 seconds to your first agent

# Build from source (requires Rust)
git clone https://github.com/egkristi/RavenClaws
cd RavenClaws
cargo build --release

# Run with any provider
export LITELLM_API_KEY="your-key"
export RAVENCLAWS__LLM__ENDPOINT="http://localhost:4000"
./target/release/ravenclaws --exec "Summarize the latest release notes"

# …or run a one-shot task and exit
./target/release/ravenclaws --exec "Summarize the latest release notes"

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:

[dependencies]
ravenclaws = "0.9"

Then use the library API in your Rust project:

use ravenclaws::{Config, ChatMessage, create_client, LLMProviderTrait};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load configuration from file/env
    let config = Config::load()?;

    // Create an LLM client
    let mut client = create_client(&config.llm)?;

    // Send a chat request
    let response = client
        .chat(&[ChatMessage {
            role: "user".to_string(),
            content: "Hello! What can you do?".to_string(),
        }])
        .await?;

    println!("{}", response.content);
    Ok(())
}

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 run --rm -it \
  -e LITELLM_API_KEY="your-key" \
  -e RAVENCLAWS__LLM__ENDPOINT="http://litellm:4000" \
  ghcr.io/egkristi/ravenclaws:latest

Docker Compose (with LiteLLM)

docker compose up -d
docker compose logs -f ravenclaws

Kubernetes

kubectl apply -f k8s/deployment.yaml
kubectl -n ravenclaws get pods
kubectl -n ravenclaws logs -l app.kubernetes.io/name=ravenclaws

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:

[llm]
provider = "litellm"
endpoint = "http://litellm:4000"
model = "gpt-4o-mini"
timeout_secs = 30

Ollama (local, no API key):

[llm]
provider = "ollama"
endpoint = "http://localhost:11434"
model = "llama3.1"
timeout_secs = 60

OpenRouter:

[llm]
provider = "openrouter"
model = "anthropic/claude-sonnet-4-20250514"

Anthropic (Native, v0.5.3+):

[llm]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
# No endpoint needed β€” uses https://api.anthropic.com

OpenAI:

[llm]
provider = "openai"
model = "gpt-4o"

OpenAI-Compatible (vLLM, llama.cpp, LM Studio, TGI, Groq, Together AI, etc.):

[llm]
provider = "openai-compatible"
endpoint = "http://localhost:8000/v1"
model = "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):

[[llms]]
provider = "ollama"
endpoint = "http://ollama:11434"
model = "llama3.1"

[[llms]]
provider = "openrouter"
model = "anthropic/claude-sonnet-4-20250514"

[[llms]]
provider = "anthropic"
model = "claude-sonnet-4-20250514"

[[llms]]
provider = "openai"
model = "gpt-4o"

Full config example

[llm]
provider = "litellm"
endpoint = "http://litellm:4000"
model = "gpt-4o-mini"
timeout_secs = 30

# RavenFabric for remote execution and mesh coordination (v0.6.1)
[ravenfabric]
endpoint = "http://ravenfabric:8080"
remote_exec = true
allowed_hosts = ["litellm", "ravenfabric"]

[security]
require_tls = true
token_lifetime_secs = 3600   # agent sessions auto-terminate after 1 hour (0 = unlimited)
audit_log = true             # surface present; enforcement on roadmap (v0.4)

[runtime]
workdir = "/workspace"
max_agents = 10
health_interval_secs = 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

git clone https://github.com/egkristi/RavenClaws
cd RavenClaws

cargo build --release      # release build for current platform
cargo test                 # unit tests
./scripts/verify.sh        # full 114-check verification suite (needs LiteLLM/Docker/kubectl)
docker build -t ravenclaws:latest .

Cross-compile for all architectures

rustup target add \
    x86_64-apple-darwin aarch64-apple-darwin \
    x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu \
    x86_64-unknown-linux-musl

./scripts/build.sh --all                                   # all targets
./scripts/build.sh --target aarch64-unknown-linux-gnu      # one target

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)
.githooks/setup.sh

# Verify hooks are active
.githooks/setup.sh --check

# Remove hooks (restore defaults)
.githooks/setup.sh --remove

Pre-commit (fast β€” runs in seconds):

  1. cargo fmt --check β€” formatting
  2. cargo clippy -D warnings β€” linting
  3. cargo test --locked β€” unit tests
  4. Binary size check β€” warns if over 5MB
  5. Secrets scan β€” no hardcoded API keys/tokens

Pre-push (comprehensive β€” runs in 1-5 minutes):

  1. Full pre-commit suite
  2. Release build (cargo build --release)
  3. Binary integrity (architecture, stripped, size)
  4. Docker build (if Docker available)
  5. Security scan (secrets, setuid, Cargo.lock)

Skip hooks (emergency only):

git commit --no-verify
git push --no-verify

Multi-arch Docker image

docker buildx build \
    --platform linux/amd64,linux/arm64 \
    -t ghcr.io/egkristi/ravenclaws:latest \
    --push .

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:

  • PolicyEngine validates all tool calls against shell/path/network allow-lists
  • Sandbox provides workdir jail with resource limits and timeouts
  • AuditLog records all operations in a tamper-evident HMAC-SHA256 chain
  • No credentials in config files β€” environment variables and K8s Secrets only
  • Memory-safe Rust with unsafe forbidden

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, /metrics endpoints

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

  1. Fork the repo
  2. Create a feature branch (git checkout -b feature/my-feature)
  3. Commit changes (git commit -am 'Add feature')
  4. Push (git push origin feature/my-feature)
  5. 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. πŸ¦β€β¬›