<aside> 🔄

Pivot Note (March 2025): Ryu has pivoted from "build our own agent layer" to an orchestration layer where users choose any agent engine (OpenClaw, ZeroClaw, Claude Code, etc.) and Ryu wraps it. The technical spec below describes the shared gateway core (ryu-gateway crate) that powers both Ryu App (desktop UI + agent catalog) and Ryu Gateway (standalone proxy). The internal modules (memory, tools, security, workflows, etc.) are unchanged, they are gateway features that wrap around any agent engine. See Ryu 2.0 for the full product vision and Ryu Gateway architecture for the infrastructure layer.

</aside>

Folder Structure

2.0/
│
├── Cargo.toml              # Workspace root
│
├── core/                   # ryu-core (the brain) — rig-core powered
│   ├── Cargo.toml
│   └── src/
│       ├── main.rs
│       ├── server/         # Axum HTTP + WebSocket endpoints
│       ├── agents/         # Agent struct, sessions, execution loop
│       │   ├── mod.rs          # Agent struct, CRUD, model binding
│       │   ├── session.rs      # Session management, history
│       │   ├── executor.rs     # Main agent execution loop
│       │   └── subagent.rs     # Sub-agent spawning, orchestration, permission scoping
│       ├── models/         # Load/unload/track local & cloud models
│       ├── providers/      # rig-core adapters + custom local_llama
│       ├── memory/         # Short-term + long-term memory (sqlite-vec)
│       │   ├── short_term.rs   # Current session window retrieval
│       │   ├── long_term.rs    # Cross-session embedded chat history
│       │   ├── embedder.rs     # Chunk + embed pipeline
│       │   ├── store.rs        # VectorStore trait + adapter selection
│       │   ├── sqlite_vec.rs   # SQLCipher + sqlite-vec backend
│       │   └── lancedb.rs      # LanceDB backend
│       ├── tools/          # MCP client, tool registry (rig::tool::Tool)
│       ├── skills/         # Skill loader (SKILL.md files)
│       ├── heartbeat/      # Cron scheduler + proactive agent triggers
│       ├── workflows/      # Node-based workflow engine
│       │   ├── engine.rs       # DAG executor, node runner
│       │   ├── nodes.rs        # Built-in node types
│       │   ├── graph.rs        # Workflow graph CRUD
│       │   └── autonomy.rs     # Autonomous mode with safety gates
│       ├── security/       # Unified security layer
│       │   ├── sandbox.rs      # Wasmtime WASM runtime + capability enforcement
│       │   ├── credentials.rs  # Encrypted key file + host-boundary injection
│       │   ├── leak_detect.rs  # Outbound secret scanning (regex + entropy)
│       │   ├── network.rs      # Pairing, randomized ports, endpoint allowlist
│       │   ├── prompt_guard.rs # Injection detection + sanitization + policy
│       │   └── builder.rs      # Dynamic WASM tool compiler
│       └── config/         # App config, API keys (SQLCipher encrypted)
│
├── mcp-servers/            # Custom MCP servers (Rust, built with rmcp)
│   ├── spider/             # ryu-mcp-spider — web crawling tools
│   │   ├── Cargo.toml
│   │   └── src/main.rs
│   └── exa/                # ryu-mcp-exa — semantic web search tools
│       ├── Cargo.toml
│       └── src/main.rs
│
├── qmd/                    # ryu-qmd — hybrid search sidecar (BM25 + vector + re-ranking)
│   ├── Cargo.toml
│   └── src/
│       ├── main.rs
│       ├── bm25.rs         # Tantivy-based full-text search
│       ├── vector.rs       # Vector search via llama.cpp embeddings + sqlite-vec
│       ├── rerank.rs       # LLM re-ranking via llama.cpp
│       ├── hybrid.rs       # Score fusion (BM25 + vector + re-rank)
│       ├── indexer.rs      # Document chunking, incremental indexing, file watching
│       └── collections.rs  # Collection management
│
├── cli/                    # ryu-cli (API client)
│   └── Cargo.toml
│
├── bots/                   # ryu-bots (messaging adapters)
│   └── Cargo.toml
│
└── desktop/                # ryu-desktop (Tauri V2)
    ├── package.json
    ├── src/                # React + Vite + Vercel AI SDK frontend
    │   ├── hooks/          # useChat(), useCompletion() from AI SDK
    │   ├── components/     # Chat UI, model picker, agent manager
    │   └── lib/            # API client to ryu-core
    └── src-tauri/          # Thin Tauri wrapper (sidecar launcher)

Rule: Core never imports Tauri. No cross-contamination.

API Endpoints

server/ — Axum HTTP + WebSocket

POST   /chat                 # Send message, get streaming response
POST   /agents               # Create agent
GET    /agents               # List agents
GET    /agents/:id           # Get agent details
PUT    /agents/:id           # Update agent
DELETE /agents/:id           # Delete agent
POST   /agents/:id/delegate  # Spawn sub-agent task(s)
GET    /agents/:id/delegates  # List active sub-agent tasks
GET    /agents/:id/delegates/:did  # Get sub-agent task status/result
POST   /models/load          # Load a local model
POST   /models/unload        # Unload a model
GET    /models               # List available/loaded models
POST   /tools/register       # Register MCP server
WS     /stream               # WebSocket for token streaming

POST   /workflows               # Create workflow
GET    /workflows               # List workflows
GET    /workflows/:id           # Get workflow details
PUT    /workflows/:id           # Update workflow
DELETE /workflows/:id           # Delete workflow
POST   /workflows/:id/run      # Run workflow
POST   /workflows/:id/nodes    # Add node
PUT    /workflows/:id/nodes/:nid  # Update node
DELETE /workflows/:id/nodes/:nid  # Remove node
POST   /workflows/:id/edges    # Add edge

POST   /heartbeat/jobs          # Create scheduled job
GET    /heartbeat/jobs          # List jobs
PUT    /heartbeat/jobs/:id      # Update job
DELETE /heartbeat/jobs/:id      # Delete job
POST   /heartbeat/jobs/:id/run  # Manually trigger

providers/ — Unified LLM Interface

Uses rig-core crate for the unified provider abstraction:

use rig::providers::openai;
use rig::providers::anthropic;
use crate::providers::local_llama;

// All providers implement rig's CompletionModel trait
// giving you: .chat(), .prompt(), .agent() with tool use

rig-core gives you:

• Built-in adapters for OpenAI, Anthropic, Cohere, Google, xAI, DeepSeek
• Agent framework with tool calling and RAG extractors
• Unified CompletionModel and EmbeddingModel traits
• Custom adapter needed only for llama.cpp local models

models/ — Model Manager

• Load/unload llama.cpp models