Ryu

The universal agent interface & open composable platform for agent orchestration and knowledge sharing. Build plugins that extend capabilities, and apps that leverage pre-built primitives. Ryu is not another agent — it's the whole infrastructure layer.

Backed by

Ryu is built with the support of leading startup programs.

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

About Ryu

Every team building with AI rebuilds the same layers from scratch — agents, memory,
RAG, model routing, sandboxes, voice, tools. Every agent, app, and framework
reinvents them in isolation, then locks its users in.

Ryu is not another agent. It's the infrastructure layer underneath the whole AI
tooling ecosystem: an open, composable platform that turns those layers — the ones
everyone rebuilds over and over again — into primitives. Local AI is exposed as
building blocks you can assemble into apps, extend with plugins, and drive from any
language, SDK, or framework. One universal interface that unifies the fragmented
ecosystem instead of adding to it:

• Works with any existing agent. Claude Code, Codex, OpenClaw, Pi, Hermes — any
  ACP or OpenAI-compatible runtime. One Gateway, shared context, stacked subscriptions.
• Works with any integration. Every MCP server, Composio account, and skill from
  any ecosystem, importable in one click.
• Works with any language, SDK, or framework. TypeScript and Rust SDKs, plus C,
  Node, Python, Go, Swift, Kotlin, and C# bindings.
• Build on top of it. Compose pre-built primitives into apps, or write plugins
  that extend capabilities. The Ryu Marketplace distributes both — signed and governed.

Local-first, encrypted, no telemetry. Works with everything. Locked to nothing.

[!WARNING]
Ryu is pre-1.0 and under active development. Interfaces, APIs, and on-disk formats may change between releases. Not recommended for production use yet.

Features

• Agent teams — named, ordered multi-agent teams with a shared coordination strategy; one conversation routes across members.
• Workflows — durable, crash-recoverable multi-step workflows with a visual builder, templates, and resumable runs.
• Model routing — 400+ models from local to cloud, routed by capability, cost, and eval score through one Gateway. Cheap tasks stay local; cloud handles only what needs it.
• Built on Pi — the flagship "Ryu" agent runs on Pi, the open agent runtime, with the Gateway on top. Bring your own engine and swap it anytime.
• Integrate everywhere — an MCP Gateway, an OpenAI-compatible API, and native channels for Telegram, Slack, WhatsApp, and Discord.
• Works with any existing agent — via ACP: Claude Code, Codex, OpenClaw, Pi, Hermes, and ~30 more, installable from the catalog.
• Works with any integration — every MCP server, Composio tool, and API-backed integration, governed by one firewall and grant system.
• Skill import — import skills from Claude, Cursor, and the wider ecosystem into one catalog with progressive-disclosure injection into any agent.
• Ryu Marketplace — signed plugins and apps (ed25519 + moderation) installable with ryu add, alongside file-based definitions you can version in git.

Why Ryu

• Agents that know what each other did. Shared memory and context across every surface — desktop, mobile, CLI, bots, web.
• Your subscriptions, fully used. Point Claude Code, Codex, and Gemini at one Gateway. Smart routing keeps cheap tasks on local models; cloud handles only what needs it.
• Secure out of the box. Firewall, prompt-injection protection, PII/DLP redaction, per-agent budgets, and a full audit trail — not bolted on, built in.
• One-click setup. Pick an agent from the catalog, install, and go. No MCP wiring, no API-key hunt, no week-long integration.
• Works with everything, locked to nothing. Every layer — model, embedder, reranker, engine, RAG strategy, sandbox — swaps via one registry. BYO agent, key, subscription.

Architecture

The one design rule: if code decides what runs (which agent, session, workflow, tool), it is
Core. If it decides what is allowed, shared, measured, or paid for, it is Gateway. Core
never enforces policy inline — it routes every model call through the Gateway.

Decomposition

Core and the Gateway were decomposed from a monolith into a virtual Cargo workspace of ~75
crates: 52 primitive + app-backend capability crates (43 crates/ryu-* capabilities — crypto,
vault, downloads, engines, RAG, memory, search, durable, voice, image, sandbox… + 9 app backends),
11 gateway-stage crates (crates/ryu-gw-*), plus the ghost/shadow automation crates. Alongside
them live 21 self-contained apps under apps-store/* (16 with UI companions). apps/core shrank
from ~195k to ~143k LoC (−27%); ~88k LoC now lives in swappable crates.

Every layer is a swappable default, never a lock — chat model, embedder, reranker, TTS/STT,
image-gen, engine, RAG strategy, durable engine, sandbox. This repository carries the open-core
subset (apps/core, apps/gateway, the CLI/TUI clients, and the public capability + SDK crates
listed below) plus a source-available tier — apps/desktop, apps/island, and the shared UI
packages — under LICENSE-COMMERCIAL.md. The web, server, mobile,
extension, and identity/billing surfaces remain proprietary and are not part of this mirror.

Quick start (self-host)

Install (prebuilt binaries)

One line pulls the headless stack — ryu-core, ryu-gateway, ryu-cli — into
~/.ryu/bin, puts it on your PATH, and starts Core so the bundled defaults can begin
provisioning. Great for servers, containers, and CI.

macOS & Linux (x86_64 Linux, Apple Silicon macOS):

curl -fsSL https://raw.githubusercontent.com/amajorai/ryu/main/install.sh | sh

Windows (x86_64, PowerShell):

irm https://raw.githubusercontent.com/amajorai/ryu/main/install.ps1 | iex

The installer waits for Core to become healthy, then the bundled models, engines, and
skills continue downloading in the background. Island and Ghost are intentionally not
installed by default yet. Attach with the CLI:

ryu-cli      # attaches to the Core started by the installer — no API key

Or start the node yourself and point clients at it:

ryu-core     # restart Core; it brings up the Gateway + local defaults

GitHub Actions

Use the bundled Ryu action from any workflow to validate a self-hosted or managed
node, run an agent/team/workflow, or call an allowlisted tool:

- uses: amajorai/ryu@v1
  with:
    target: managed
    managed-node-url: ${{ secrets.RYU_MANAGED_NODE_URL }}
    managed-node-token: ${{ secrets.RYU_MANAGED_NODE_TOKEN }}
    operation: run
    agent: review-agent
    prompt: Review the current release candidate.

See the GitHub Actions documentation
for setup, tool calls, outputs, and security behavior.

_{Prebuilt targets: Linux x86_64, macOS Apple Silicon, Windows x86_64. On Intel
Macs or ARM Linux, build from source below. Override the install dir with
RYU_INSTALL_DIR or pin a release with RYU_VERSION=v0.0.4.}

Build from source

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 lives in its own repo, amajorai/ryu-docs
(Next.js), 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.

Batteries-included defaults (all swappable)

• Engine/model: llama.cpp + Gemma 4 — runs on most machines, no key.
• Default agent: "Ryu" = Pi with the Gateway on top (the flagship "car around the engine"). Claude Code, Codex, Gemini CLI, OpenClaw, Hermes, and ~18 more ACP agents are opt-in via the catalog.
• RAG: local nomic embeddings + BGE reranker; vector + GraphRAG.
• Modalities: chat, image-gen, TTS, STT — all first-class, all swappable.
• Standards: Agent Skills + MCP + ACP, all first-class.

Repository layout

This mirror ships two tiers, and the difference matters. Each unit carries its own
LICENSE; the full map is in LICENSING.md.

1. Open source — the orchestration engine, the Gateway, the terminal clients, and the
   public capability + SDK crates. Apache-2.0 (Gateway: AGPL-3.0, Raycast: MIT).
2. Source-available — apps/desktop, apps/island, and the shared UI packages they
   cannot compile without, under LICENSE-COMMERCIAL.md.
   This is not open source. You may read, audit, build locally, and contribute; you
   may not use it in production without an official binary, redistribute it, offer it as
   a service, or build a competing product from it.

The web, server, mobile, extension, and identity/billing surfaces (© 2026 A Major Pte.
Ltd.) remain closed and are not part of this repository.

The Ryu name and logo are not licensed by any file here — a permitted fork must
rebrand. See TRADEMARK.md. Build instructions:
docs/BUILDING.md.

Apps — Apache-2.0 (Gateway: AGPL-3.0)

Capability & SDK crates — Apache-2.0

TypeScript packages — Apache-2.0

Footprint

The native tier ships as a handful of small self-contained Rust binaries: 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.

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 capture/automation tools (Shadow, Ghost) and the CLI have no steady idle, so they report size/deps/LOC. Measured on win32.

Primitives

Ryu's swappable building blocks — memory, RAG, sandboxes, voice, tools,
gateway stages, automation, and the SDK bindings — are each documented on their own page
in the docs: Primitives → docs.ryuhq.com/docs/reference/primitives.

Contributing

Contributions to the OSS units are welcome — see each unit's README for build instructions.
Report security issues privately to [email protected].

Open-source units are Apache-2.0, except the Gateway (AGPL-3.0) and Raycast (MIT).
apps/{desktop,island} and the shared UI packages are source-available, not open
source — see LICENSE-COMMERCIAL.md; contributions to them
are welcome under those terms. The web/server/mobile/extension and identity/billing
surfaces are © 2026 A Major Pte. Ltd. and live in the private monorepo. Each
subdirectory carries its own LICENSE file; LICENSING.md is the map.

Built on the shoulders of kernel.sh (identity vault),
Jan (local-first desktop),
Ghost OS (desktop automation), and
Shadow (capture + semantic memory).