index.md

id: index
title: "Rye OS Documentation"
description: Documentation for Rye OS — the MCP server that gives AI agents a portable .ai/ directory system
category: root
tags: [index, documentation, ryeos]
version: "1.0.0"

Rye OS Documentation

Rye OS gives AI agents a portable .ai/ directory system, accessible via MCP server or terminal CLI. Agents interact with it through 3 MCP tools to fetch, execute, and sign three item types: directives (workflow instructions), tools (executable scripts), and knowledge (domain information).

---

Getting Started

• Installation — Install and configure Rye OS as an MCP server
• Quickstart — Create your first directive, tool, and knowledge entry
• The .ai/ Directory — Structure, conventions, and the 3-tier space system

MCP Tools Reference

The 3 tools that agents use to interact with Rye OS:

• rye_fetch — Find items by ID or discover by query
• rye_execute — Execute directives, tools, or knowledge items
• rye_sign — Validate and sign items with integrity hashes

CLI

Terminal-native interface — the same three primitives, from the shell:

• ryeos-cli — Verb mapping, graph operations, test runner, and parameter parsing

Authoring Items

• Directives — Write workflow instructions with XML metadata and process steps
• Tools — Write executable tools in Python, YAML, Bash, or JavaScript
• Custom Runtimes — Add support for new languages by creating runtime YAML configurations
• Knowledge — Write domain information with YAML frontmatter

Orchestration

Thread-based orchestration is the flagship capability — AI agents coordinating multi-step workflows through hierarchical thread trees.

• Overview — The orchestration pattern and why it works
• Thread Lifecycle — Creation, execution, and finalization
• Spawning Children — Spawn, coordinate, and collect results
• Safety and Limits — Cost controls, turn limits, and the SafetyHarness
• Permissions and Capabilities — Capability tokens and fail-closed security
• Continuation and Resumption — Context limit handoffs and user-driven resumption
• State Graphs — Declarative, code-free workflows as YAML graph tools
• Streaming — Real-time token streaming and transcript rendering
• Building a Pipeline — Step-by-step tutorial with a real-world example

Standard Library

The core tools and infrastructure that ship with every Rye OS installation:

• Overview — Full catalog of bundled items
• Bundled Directives — Item creation and thread management directives
• Bundled Tools — File system, bash, MCP, orchestration engine, and more
• Bundled Knowledge — Metadata references for AI agents

Bundles

Optional extension bundles that add domain-specific tools:

• Overview — How bundles work, installation, and the full list
• Web — Search, fetch, and browser automation (ryeos-web)
• Code — NPM, diagnostics, TypeScript, LSP (ryeos-code)
• Email — Provider-agnostic inbound routing, sending, and drafting (ryeos-email)

Internals

For contributors and those who want to understand how Rye OS works under the hood:

• Architecture — Layers, components, and data flow
• Packages and Bundles — pip packages, bundle entry points, and dependency layering
• Executor Chain — Multi-layer tool resolution and execution
• Runtimes — How runtimes configure tool execution, interpreter resolution, and the 7 standard runtimes
• Three-Tier Spaces — Project, user, and system space resolution
• Integrity and Signing — Content hashing, Ed25519, and trust management
• Content-Addressed Store — Immutable objects, blobs, refs, and the CAS object model
• Remote Execution — CAS-native sync, materializer, server endpoints, and trust model
• Node Execution Cache — Deterministic cache keys, config snapshots, and cache invalidation
• Lillux Primitives — The microkernel layer

Registry

• Sharing Items — Push, pull, and discover items through the registry