Setup Ryu

Set up Ryu

You are setting up Ryu for a user. Work top to bottom. Do not skip the health check before moving on, and do not fabricate endpoints - every route below is real.

What Ryu is

Ryu is a local-first AI node that runs on the user's own machine. Three pieces matter:

• Core: the brain and HTTP API. Listens on http://127.0.0.1:7980. Owns the model catalog, agents, workflows, RAG Spaces, MCP registry, and chat.
• Gateway: the OpenAI-compatible inference gateway on http://127.0.0.1:7981. Serves the active local model and meters usage.
• Desktop app: the Tauri shell most users launch. Starting it boots Core and Gateway for them.

A user can run just Core (headless) or the full desktop app. Either way, everything an external agent needs is the Core HTTP API on :7980.

Step 1 - install and launch

Prefer the desktop app for non-technical users, Core for headless or server setups.

• Desktop: install the Ryu desktop app and open it. It starts Core (:7980) and Gateway (:7981) automatically.
• Headless Core from the repo: from the monorepo run Core directly (it is a Rust binary under apps/core). Use the project's standard run command for apps/core. Core binds :7980.

Always use bun for any JavaScript-side commands in this monorepo.

Step 2 - verify health (do not skip)

Confirm Core is reachable before anything else:

curl -s http://127.0.0.1:7980/api/health

A healthy node returns JSON like {"status":"ok"}. For a fuller picture use GET /api/system/status (reachability + mesh) and GET /api/system/info (hardware: CPU, RAM, GPU). If /api/health does not answer, Core is not up - go back to Step 1.

Step 3 - download and activate a local model

The model catalog is Hugging Face GGUF by default. The engine is derived from the model format, so you usually only pick the model.

1. Search the catalog:

curl -s "http://127.0.0.1:7980/api/models/catalog?query=qwen&format=gguf&sort=trending&limit=10"

2. Inspect a model's quantizations and device-fit:

curl -s "http://127.0.0.1:7980/api/models/catalog/detail?id=<repo_id>&format=gguf"

3. Install one specific GGUF file (verified downloader):

curl -s -X POST http://127.0.0.1:7980/api/models/catalog/install \
  -H 'content-type: application/json' \
  -d '{"id":"<repo_id>","file":"<filename.gguf>","format":"gguf"}'

4. Activate the installed model so the local chat stack serves it:

curl -s -X POST http://127.0.0.1:7980/api/models/active \
  -H 'content-type: application/json' \
  -d '{"id":"<repo_id_or_stem>"}'

Read the current selection with GET /api/models/active. List runnable engines with GET /api/engines. For more depth see [[ryu-local-model]].

Step 4 - point other agents at Ryu (the key step)

Ryu ships an MCP server at apps/mcp that exposes the Core API as MCP tools over stdio. Adding it lets Claude Code, Cursor, or any MCP client drive the node. It reads its target node from RYU_CORE_URL (default http://127.0.0.1:7980); set RYU_CORE_TOKEN if the node requires auth.

Add this to the agent's MCP config (mcpServers). Point the path at this repo's apps/mcp:

{
  "mcpServers": {
    "ryu": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/apps/mcp/src/index.ts"],
      "env": {
        "RYU_CORE_URL": "http://127.0.0.1:7980"
      }
    }
  }
}

The package also exposes a ryu-mcp bin, so after bun install you can launch it by that name instead of the file path.

After connecting, the agent receives the canonical tool list via the MCP tools/list handshake - trust that list for exact names. The tools include ryu_ask, ryu_list_agents, ryu_search_models, ryu_set_active_model, ryu_run_workflow, ryu_call_mcp_tool, and ryu_search_retrieval. Full reference in [[ryu-mcp]].

Step 5 - confirm the loop

Verify the agent can reach Ryu through MCP by calling ryu_health, then ryu_get_active_model. If both succeed, the user's other agents are wired to their Ryu node.

Where to go next

• Drive the node through MCP: [[ryu-mcp]]
• Create an agent on the node: [[ryu-build-agent]]
• Manage local models and engines: [[ryu-local-model]]
• Author a new skill like this one: [[ryu-author-skill]]