<aside> 🔄

Pivot Note (March 2025): Ryu has pivoted from "build our own agent layer" to an orchestration layer where users pick any agent engine (OpenClaw, ZeroClaw, Claude Code, etc.) and Ryu wraps it with UI + gateway infrastructure. See Ryu 2.0 for full product vision and Ryu Gateway for the infrastructure architecture.

</aside>

Vision

Build Ryu as an AI agent orchestration layer, a single Rust binary that sits between users and whatever agent engine they choose. Ryu handles everything the agent itself doesn't: model routing, security, tool management, memory, evals, and budgets. Ships as two products built on the same ryu-gateway crate:

1. Ryu App (UI layer), premium desktop app (Tauri V2) with agent catalog, batteries-included skills/MCPs, visual workflows
2. Ryu Gateway (infrastructure layer), standalone proxy that any agent routes through by swapping one URL

Key Objectives

1. Orchestration-First , Ryu doesn't run the agent loop itself, it wraps whatever engine you choose (OpenClaw, ZeroClaw, Claude Code, etc.)
2. Minimal & Non-Bloated , Clean modular Rust core (ryu-gateway crate), no duplicated logic
3. Local AI Native , Easy local LLM setup via llama.cpp for privacy-first AI
4. Gateway Infrastructure , Firewall/PII scanning, model routing, MCP registry, evals, token budgets, org/team/project hierarchy
5. Ryu Cloud (Platform-as-a-Service) , Models via OpenRouter, integrations via Composio, wrapped and white-labeled as Ryu Cloud
6. Multiple Interfaces , Desktop (Tauri V2), CLI, Messaging Bots (Telegram/Discord/WhatsApp), future mobile + web app
7. Agent Catalog , Browse, install, and switch agent engines with one click. Batteries-included defaults.

Code References

<aside> 📌

Agent Engine Reference: ZeroClaw — Rust-native autonomous agent runtime (13k+ stars). ZeroClaw is one of several supported engines Ryu orchestrates (alongside OpenClaw, IronClaw, Claude Code, etc.). Its trait-based, modular architecture informed the gateway's engine adapter design. Key patterns:

• Trait-driven subsystems — providers, channels, tools, memory, tunnels all defined by swappable traits
• Identity system — IDENTITY.md, SOUL.md, USER.md, AGENTS.md (OpenClaw-compatible)
• Lean binary — <5MB footprint, <10ms startup, runs on 0.6GHz cores
• Security defaults — pairing, strict sandboxing, explicit allowlists, workspace scoping
• No vendor lock-in — OpenAI-compatible provider support + pluggable custom endpoints
• Docs: commands-reference.md, providers-reference.md, channels-reference.md, config-reference.md </aside>

<aside> 🔒

Security Reference: IronClaw + ZeroClaw — Hybrid security model, best of both:

• Credential storage (ZeroClaw) — local AES-256 encrypted key file, no external DB
• Credential access (IronClaw) — host-boundary injection, tools never see raw secrets, domain scoping, leak detection
• Sandboxing (both, no Docker) — WASM-only via Wasmtime: IronClaw capability-based permissions + ZeroClaw explicit allowlists + resource limits
• Network (both) — ZeroClaw key-based pairing + randomized gateway ports + IronClaw endpoint allowlisting (HTTP-only)
• Prompt injection (both) — IronClaw multi-layer defense (detection + sanitization + policy) + ZeroClaw-scale test suite (1,000+ tests target) </aside>

<aside> 🧮

Vector Storage: sqlite-vec — Default vector backend. Successor to sqlite-vss, ultra-efficient SQLite extension for vector search. SIMD-accelerated, 30MB footprint, runs everywhere (WASM, Pi, mobile). Full details in the memory/ section below.

</aside>

<aside> ⚙️

Workflow Engine: Restate — Primary workflow engine. Production-grade durable execution (3.5k stars, company-backed, Rust SDK restate-sdk v0.9.0). Runs as a local sidecar. ⚠️ No Windows — falls back to petgraph DAG executor. Full details in the workflows/ section below.

</aside>

<aside> 🌐

Web Crawling: Spider — High-performance Rust web crawler:

• 200-1000x faster than alternatives, HTTP + Chrome CDP + WebDriver support
• AI automation via spider_agent, headless browser rendering
• Exposed as a custom MCP server (built with rmcp) so agents can crawl websites as a tool
• Crate: spider on crates.io </aside>

<aside> 🔌

MCP SDK: rmcp — Official Rust MCP SDK (3.1k stars):

• Official modelcontextprotocol/rust-sdk — the canonical Rust implementation
• Used to build custom MCP servers in Rust that expose tools to Ryu agents
• Crate: rmcp v0.16.0+ on crates.io, features: ["server"]
• Proc macro support via rmcp-macros for ergonomic tool definitions
• Ryu custom MCP servers (all Rust, built with rmcp):
  1. Spider MCP Server — wraps spider crate, exposes web crawling tools (crawl URL, extract content, screenshot, etc.)
  2. Exa Search MCP Server — wraps Exa API, exposes semantic web search tools (search, find similar, get contents) </aside>