[AGENTS.md](https://jiaweing.notion.site/AGENTS-md-826dba217bcf4556a3885299dadeb8bc)

Tasks

<aside> 🔄

Pivot Note (March 2026): Ryu has evolved from a ZeroClaw-only wrapper into a two-product orchestration layer. Users choose whatever agent engine they want (ZeroClaw, OpenClaw, IronClaw, or any compatible runtime), and Ryu provides two products on top: Ryu App (the UI layer: desktop/mobile/web) and Ryu Gateway (model routing, PII scanning, rate limits, evals, org-level management). ZeroClaw-specific details below are retained as reference for that engine option. See Ryu Gateway, The Orchestration Layer for the full gateway architecture.

</aside>

How Ryu actually works under the hood. This page covers every layer of the stack, what each component does, and how they connect.

Architecture Overview

Ryu is a two-product orchestration system. Users choose their agent engine (ZeroClaw, OpenClaw, IronClaw, or any compatible runtime), and Ryu provides the layers above and around it: Ryu App (UI) and Ryu Gateway (middleware). The agent runtime is not built from scratch, it's whichever engine the user installs, extended through the Gateway and Ryu's batteries-included ecosystem.

┌─────────────────────────────────────────────────┐
│  Interfaces (thin clients)                      │
│  Desktop (Tauri V2) · CLI · 16+ Channels        │
└──────────────────┬──────────────────────────────┘
                   │ HTTP / WS
┌──────────────────▼──────────────────────────────┐
│  ryu-core (Rust binary)                         │
│  ═══════════════════════════════════════════     │
│  Interface layer — routes requests, manages     │
│  all sidecars (including ZeroClaw), serves      │
│  desktop app, extends ZeroClaw via config +     │
│  MCP + skills (Spaces, workflows, cloud)        │
└──────────────────┬──────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────┐
│  ZeroClaw (agent core)                          │
│  ═══════════════════════════════════════════     │
│  Agents · Sub-agents · Memory (SQLite + vec)    │
│  RAG · Encryption · Web Search (DuckDuckGo)     │
│  Channels (Telegram, Discord, CLI) · MCP client │
│  Providers (BYOK, Codex, llama.cpp) · Security  │
│  (pairing, allowlists, workspace isolation)      │
│  Agent Browser · Composio · Skills              │
└──────────────────┬──────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────┐
│  Sidecars (optional local processes)            │
│  ─────────────────────────────────────────      │
│  Temporal (workflow engine, native binary)       │
│  llama.cpp (local model inference)              │
└──────────────────┬──────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────┐
│  MCP Servers (tool integrations)                │
│  ─────────────────────────────────────────      │
│  Screenpipe (screen + audio, via MCP)           │
│  Spider (web crawling, Rust)                    │
│  + any user-installed MCP servers               │
└──────────────────┬──────────────────────────────┘
                   │ (optional)
┌──────────────────▼──────────────────────────────┐
│  Ryu Cloud (PaaS)                               │
│  OpenRouter (300+ models) · Composio (OAuth)    │
│  Usage tracking · Billing · BYOS routing        │
└─────────────────────────────────────────────────┘

Minimum viable Ryu: Any supported agent engine + one API key = working AI assistant. The Gateway, cloud tier, and everything else is opt-in.

Layer 1: Agent Engine (Swappable)

The agent engine is the foundation, and it's your choice. Ryu supports multiple engines: ZeroClaw, OpenClaw, IronClaw, or any compatible runtime. Users install their preferred engine, and Ryu orchestrates it through the Gateway + UI layers.

ZeroClaw (Reference Engine)

ZeroClaw is the default reference engine. It's a Rust-native autonomous agent runtime that compiles to a ~3.4MB binary with sub-10ms startup and <8MB RAM usage. Ryu downloads the ZeroClaw binary at install time (just like Temporal, Screenpipe, and llama.cpp) and extends it entirely through config, MCP servers, and skills, no fork needed.

Why no fork?

ZeroClaw's architecture is trait-based and config-driven. Every major subsystem is swappable without touching source code:

Extension method What it covers How Ryu uses it
Config (config.toml) Providers, channels, security, memory backend OpenRouter as custom provider (custom:<url>), channel toggles, workspace isolation settings
MCP servers Tool integrations registered in [mcp.servers] Screenpipe, Spider, Ryu-specific tools (Spaces, workflow triggers)
Skills Community-contributed agent capabilities loaded from a directory Ryu-specific skills for Spaces management, document indexing, workflow helpers
Custom providers custom:<url> or anthropic-custom:<url> in config Route through Ryu Cloud's OpenRouter proxy when subscribed

This means: