Ryu

Agents are powerful. Using them shouldn't be.

Warning

Early access — under active development. Ryu is pre-1.0 and moving fast. APIs, schemas, config, on-disk formats, and CLI flags can change without notice, and releases may include breaking changes between versions. Pin a version, expect rough edges, and read the release notes before upgrading. Not yet recommended for production-critical workloads.

End-to-end infrastructure for AI agents. The engines already exist: OpenAI, Claude Code, Pi, OpenClaw, Hermes, any OpenAI-compatible runtime. Ryu is the whole stack around them, so any agent works everywhere, as easily as installing an app.

One control layer governs what each agent can reach, what it costs, and what's safe to send. Memory, routing, observability, and security are built in.

Local-first, encrypted by default, no telemetry. Locked to no provider or ecosystem: bring your own agent, key, and model, and every default is swappable.

• 🔌 Any engine, zero lock-in. Wrap the agent you already use (OpenAI, Claude Code, Pi, OpenClaw, Hermes, and more). Ryu never reimplements the agent loop.
• 🛡️ One control layer. The Gateway governs every model call: routing, firewall, PII/DLP, budgets, evals, audit.
• 🏠 Local-first, no key. First run pulls a fully-local stack (llama.cpp + Gemma 4, nomic embeddings, whisper). Encrypted by default, no telemetry.
• 🔁 BYO everything. Agent, key, model. Every default (model, embedder, reranker, engine, RAG strategy, sandbox) swaps via one registry.
• 📦 Two static binaries. ryu-core and ryu-gateway are the whole self-hostable stack. No database, no cloud.
• 🧩 Standards-native. MCP, ACP, and Agent Skills are first-class. Point any OpenAI-compatible client at the Gateway.

This repository is the open-source core of Ryu: the orchestration engine, the LLM gateway, the CLI, and the developer SDK.

It's everything you need to self-host Ryu or build on it. The desktop, web, and mobile apps are proprietary and developed separately, so they aren't here.

The apps are thin GUIs over this open engine. Everything that touches your data or makes a decision lives here and is auditable: orchestration (Core), model governance (Gateway), and on-device capture (the open Shadow sidecar). The desktop just talks to ryu-core over local HTTP and renders the result.

Download

Most people want the desktop app: install, pick an agent, go.

Every release ships on a single page with desktop installers for macOS, Windows, and Linux, the headless binaries, and the Island companion.

For the wider ecosystem, see Awesome Ryu.

Backed by

Ryu is built with the support of leading startup programs.

                       

_{AWS Activate  ·  BLOCK71  ·  Claude for Startups  ·  OpenAI for Startups  ·  Cloudflare for Startups}

How it fits together

Two Rust services are the whole self-hostable stack, with no database and no cloud.

Core runs your agents. Gateway governs every model call. Core never enforces policy itself; it hands each call to the Gateway. That split is the whole idea: Core decides what runs, the Gateway decides what's allowed.

Footprint

Ryu's self-hostable stack is two small static Rust binaries (ryu-core + ryu-gateway), plus the CLI: no interpreter, no runtime, no Electron, no Docker. Every number below is emitted by scripts/benchmark.mjs; reproduce it with node scripts/benchmark.mjs --build --runtime.

Component	Release binary	Crates	Source (LOC)	Idle RSS	Idle CPU
apps/core	44.2 MB	687	105,168	n/a	n/a
apps/gateway	18.7 MB	405	20,658	17.0 MB	0.0%
apps/cli	5.9 MB	235	10,497	n/a	n/a

Idle RSS and CPU are sampled only for the Gateway (a stateless proxy with a clean idle), and idle CPU is effectively nil. Core boots a full local stack on first run and the CLI is short-lived, so they report size/deps/LOC. Measured on win32.

What's here

Unit	License	What it is
apps/core	Apache-2.0	Orchestration engine, the local backend (:7980)
apps/gateway	AGPL-3.0	The control layer: routing, firewall, cache, evals, audit (:7981)
apps/cli	Apache-2.0	Terminal client for Core
apps/fumadocs	Apache-2.0	Documentation site with interactive OpenAPI
packages/sdk · create-ryu-app	Apache-2.0	Developer SDK and project scaffolder
packages/client	Apache-2.0	Typed Core API client
crates/ryu-sdk{,-ffi,-napi}	Apache-2.0	SDK kernel plus FFI and Node-API bindings
crates/ghost-core	Apache-2.0	Automation primitives Core builds on

Most of Ryu is Apache-2.0. The Gateway is AGPL-3.0: it's the layer teams adopt and Ryu runs as a service, so copyleft keeps it open while requiring hosted forks to share their changes.

All of it is OSI-approved open source. This is open-core, not source-available. See docs/open-core.md and each unit's LICENSE.

Three siblings live in their own repositories: the desktop-automation server Ghost, the capture sidecar Shadow, and the Raycast extension.

Quick start (self-host)

cd apps/core    && cargo build --release   # ryu-core    :7980
cd apps/gateway && cargo build --release   # ryu-gateway :7981

Point any OpenAI-compatible client at the Gateway's /v1/chat/completions.

On first run, Ryu downloads a fully-local stack (llama.cpp with Gemma 4 for chat, nomic embeddings, whisper for speech), so it works with no API key.

Swap any piece later: model, embedder, engine, and RAG strategy are all config.

The TypeScript units (SDK, docs) use Bun:

bun install && bun run build

One-click deploy

Stand up a hosted node (Core + Gateway) on a container host. Each builds the Dockerfile: Core runs the stack and manages the Gateway on loopback, so only Core's port is published.

   

Or run it yourself:

• Docker Compose — docker compose up --build (docker-compose.yml): Core on :7980, Gateway on :7981, model state in a named volume.
• Fly.io — fly launch --copy-config then fly deploy (fly.toml).

Sizing. Core downloads a fully-local model stack on first boot, so pick a plan with ≥ 2 GB RAM (4 GB is comfortable), or set a provider key such as OPENAI_API_KEY to skip the local download and run small.

License. The Gateway is AGPL-3.0: host a modified Gateway and §13 obliges you to offer those changes to its users. Core is Apache-2.0.

The documentation site (apps/fumadocs) is a Next.js app and deploys to Vercel in one click — . Vercel is serverless and cannot host the long-running Core/Gateway; use a container host above for the backend.

Dual-use & consent

Ghost (screen perception and synthetic input) and Shadow (screen and audio capture) are dual-use, exactly the capabilities malware wants.

They're open-sourced for auditability and, inside Ryu, run only behind explicit user consent. If you embed them, gate them behind clear consent and treat them as high-trust dependencies. See each repository's SECURITY.md.

Contributing & security

Contributions are welcome. See each unit's CONTRIBUTING.md for standalone build steps, and SECURITY.md for private vulnerability reporting (or email [email protected]).

License

Open-core: Apache-2.0 for most units, AGPL-3.0 for apps/gateway. Each subdirectory carries its own LICENSE. © 2026 A Major Pte. Ltd.