# Ryeos > A data-driven, cryptographically signed, registry-backed AI operating system, with capability-scoped execution and graph-executable workflows — living inside your projects, running through a recursive MCP that goes as deep as you dare. - **Type:** MCP server - **Install:** `agentstack add mcp-leolilley-ryeos` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [leolilley](https://agentstack.voostack.com/s/leolilley) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [leolilley](https://github.com/leolilley) - **Source:** https://github.com/leolilley/ryeos ## Install ```sh agentstack add mcp-leolilley-ryeos ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # RyeOS > _In Linux, everything is a file. In RyeOS, everything is data._ RyeOS is portable verified execution. (_RYE Your Execution_.) Work in RyeOS — a tool run, a multi-step workflow, a scheduled job — is data: signed, content-addressed, durable. Because it is data, it can prove what it is, who authorized it, and what it actually did. And because it is data, it can move: to another machine, across a restart, into the future. A run whose process dies resumes from its own record. Work pushed to another node carries its trust with it instead of borrowing the machine's. That is the whole idea. Everything in this repository is that one property at a different layer: - **Signed items and bundles** — behavior you can install and trust, because what runs is exactly what was signed. - **Threads** — every execution has an identity and a durable event log. The log _is_ the run: tail it live, replay it, resume it, cancel it. - **Keys** — the only actors. An operator, a node, an agent: each is a signing key, and anything that acts, acts by signing. Every piece of work traces back to the key that stands behind it, and trust is always a decision about a key, never about a machine. - **Remotes** — push work to another node with signed requests and scoped grants. Trust travels as data, never as ambient machine access. - **Content-addressed state** — history is the source of truth; databases and even running processes are rebuildable projections of it. None of this is AI-specific — remove every LLM runtime and the property stands. But an execution substrate that doesn't care what the executor is turns out to be exactly what LLM work needs: directives make an LLM call into a signed, durable, resumable execution like any other, and an agent is simply a signing key with a body of signed work — not a process, not a session. ## Mental model ```text ╭──────────────╮ MCP: one cli tool │ AI client │──────╮ ╰──────────────╯ ▼ ╭──────────────╮ ╭──────────────╮ ╭──────────────╮ ╭─────────────╮ │ operator │─▶│ ryeos CLI │ HTTP │ ryeosd node │ signed requests │ other nodes │ ╰──────────────╯ │ bundle verbs │──────▶│ execution + │◀───────────────▶│ │ ╰──────────────╯ │ state │ CAS sync ╰─────────────╯ ╰──────┬───────╯ │ ╭─────────────────────────┴─────────────────────────╮ │ signed bundles, CAS objects, refs, threads, vault │ ╰───────────────────────────────────────────────────╯ ``` The node, `ryeosd`, is where data becomes act: it holds keys, checks signatures, executes at the frontier, and owns durable state. It is deliberately the least special part of the system — any node with the right trust can be the site of an execution, because everything that matters is in the data. RyeOS is built around a few primitives: | Primitive | Meaning | | -------------- | ------------------------------------------------------------------------------------------------------------------- | | **Item** | A signed unit of behavior or context: `tool:`, `directive:`, `knowledge:`, graph, service, config, runtime, schema. | | **Bundle** | A signed distribution unit containing items, schemas, binaries, CLI descriptors, and publisher trust metadata. | | **Node** | The local daemon and system space. It verifies bundles, executes items, owns state, and exposes HTTP services. | | **Thread** | A tracked execution: event log, lifecycle, lineage, continuation chain, receipts, cancellation, and replay. | | **CAS** | The authoritative append-only state store. Hashes identify events, snapshots, manifests, and project objects. | | **Ref** | A signed mutable pointer into CAS, such as a project head, chain head, or bundle registration. | | **MCP bridge** | A local single-user adapter exposing one `cli` tool that shells out to the `ryeos` binary. | ## What you can do with it ### Execute signed behavior ```bash ryeos execute tool:ryeos/core/identity/public_key ryeos execute directive:ryeos/examples/continuing_research ``` Tools are executable programs. Directives are LLM-evaluated programs with permissions, limits, context, and inheritance. Both are resolved from signed bundle or project data before execution. ### Trace, steer, and replay executions ```bash ryeos thread list ryeos thread get ryeos thread tail # live event stream ryeos thread children # lineage-linked child threads ryeos thread chain # continuation chain ryeos thread cancel ryeos events replay ``` The event log is the execution, so tailing a thread is watching the execution object grow at its frontier, and replay is reading it back. Steering and cancellation act on the same control plane the node uses internally. ### Run declarative workflows State graphs describe multi-step programs as YAML DAGs with conditional edges, foreach execution, hooks, caching, and persisted state. Graphs run through the same signed execution and thread machinery as tools and directives: long runs continue across segment cuts as chained threads, and work fans out into detached, lineage-linked child threads. ### Schedule recurring work ```bash ryeos scheduler register ryeos scheduler list ryeos scheduler pause ryeos scheduler show-fires ``` Schedules fire items on cron or interval rules. Each fire creates a normal thread with normal history and result inspection. ### Push work to another node ```bash ryeos remote configure --descriptor ./prod.remote.yaml ryeos remote admit \ --remote prod \ --token "" \ --label dev-machine \ --scopes "ryeos.execute.service.objects/has,ryeos.execute.service.objects/put,ryeos.execute.service.objects/get,ryeos.execute.service.system/push-head" ryeos remote doctor --remote prod ryeos remote execute \ --remote prod \ --item-ref tool:my/heavy-compute \ --project /absolute/path/to/project ``` Remote execution uses node keys, signed requests, scoped grants, and content-addressed sync. A descriptor is a trust pin, not a credential; runtime authority lives in the target node's authorized-key store. ## Install ### Arch Linux / AUR AUR packages (`ryeos`, `ryeos-mcp`) are coming soon. Once published: ```bash yay -S ryeos ryeos-mcp ryeos init ryeos start ryeos node status ``` `ryeos init` discovers packaged bundles under `/usr/share/ryeos`, installs them into the system space, creates operator and node keys, initializes trust and vault material, and writes node configuration. `ryeos start` launches `ryeosd`. The user lifecycle surface is intentionally small: ```bash ryeos init # bootstrap operator keys, trust, and bundles ryeos start # bring the local node online ryeos stop # stop it ryeos node status # local node lifecycle status ryeos node doctor # offline "why won't it start" checklist ``` ### Docker image The release workflow publishes a composed daemon image: ```bash docker pull ghcr.io/leolilley/ryeos-standard:latest ``` The image includes `ryeosd`, `ryeos`, core tools, and signed bundle trees. The entrypoint runs `ryeos init` on every boot (idempotent) before starting `ryeosd`; the app root lives at `/data/app` on the persistent `/data` volume, so keys, trust, and runtime state survive redeploys. ### From source ```bash git clone https://github.com/leolilley/ryeos.git cd ryeos cargo build ./scripts/pkg/install-local-direct.sh ``` `scripts/pkg/install-local-direct.sh` installs the current built artifacts into the local packaged layout and initializes the user system space. It does not refresh bundle artifacts by default. Use `scripts/pkg/install-local-direct.sh --populate` only when bundle-owned binaries, CAS manifests, or signed bundle outputs actually need to be regenerated. ## Using RyeOS from an AI client The MCP adapter is deliberately thin. It exposes one tool, `cli`, which invokes the `ryeos` binary. The available commands come from the installed signed bundles, so adding a bundle can add CLI verbs without redeploying the MCP server. Example MCP configuration: ```json { "mcpServers": { "ryeos": { "command": "ryeosd-mcp" } } } ``` The MCP tool accepts argv for `ryeos`: ```json { "tool": "cli", "args": ["execute", "tool:ryeos/core/identity/public_key"], "project_path": "/path/to/project" } ``` The MCP server is for local single-user stdio use. Do not expose it directly on the network without a separate authentication boundary. ## Bundles and trust RyeOS behavior is shipped as bundles — installable signed `.ai/` trees. A bundle may contain: - item YAML and Markdown; - schemas and composer rules; - runtime and handler binaries; - CLI command descriptors; - knowledge docs; - publisher trust metadata; - content-addressed manifests and refs. Installed bundles are verified before use. Bundle-owned binaries live inside the signed bundle tree and are resolved by hash; they are not arbitrary programs copied onto `PATH`. The repository currently includes bundles such as: | Bundle | Purpose | | -------------- | ---------------------------------------------------------------------------------------- | | `core` | Node, trust, identity, signing, state, service, and bundle primitives. | | `standard` | Execution-facing workflows: directives, tools, graphs, threads, scheduler, and runtimes. | | `web` | Web-oriented tools and runtimes. | | `browser` | Browser automation tools. | | `ryeos-ui` | UI/operator-facing bundle assets. | | `hosted-node` | Policy for exposing a node as a hosted remote target. | | `central-auth` | Reusable app-level auth primitives for RyeOS-backed projects. | ## State model RyeOS state follows a three-tier truth model: | Tier | Mutable? | Rebuildable? | Purpose | | ----------------- | -------: | -----------: | ---------------------------------------------------------------- | | CAS objects | No | N/A | Authoritative events, snapshots, manifests, and project objects. | | Signed refs | Yes | No | Entry points into the CAS graph. | | SQLite projection | Yes | Yes | Query performance only. | Writes are CAS-first. If a projection update fails after the CAS write succeeds, the daemon can rebuild the projection later by walking signed heads through CAS. That makes the event graph the source of truth, not an incidental database file. The same tiering applies one level up: a running process is a rebuildable projection of its thread's durable state. ## Repository map | Path | Purpose | | ------------------------------ | ----------------------------------------------------------------------------------- | | `crates/kernel/lillux` | Low-level signing, hashing, atomic IO, process, and primitive execution support. | | `crates/engine/ryeos-engine` | Item resolution, composition, policy facts, and execution planning. | | `crates/engine/ryeos-executor` | Execution dispatch and runtime integration. | | `crates/daemon/*` | Daemon crates: app core, HTTP API, bundle install, node lifecycle, and UI assets. | | `crates/bin/cli` | `ryeos`, the operator CLI and MCP target. | | `crates/bin/daemon` | `ryeosd`, the local node daemon. | | `crates/clients/*` | Client surfaces: shared ryeos-ui base, terminal, and web. | | `crates/runtimes/*` | Directive, graph, and knowledge runtimes. | | `crates/state/*` | Durable state, scheduler, and vault crates. | | `crates/tools/*` | Bundle-owned tool binaries and handler protocols. | | `bundles/*` | Signed bundle source trees. | | `integrations/mcp/ryeosd` | Python MCP stdio adapter exposing the `cli` tool. | | `scripts/` | Bundle population, validation, local install, and development workflows. | | `deploy/` | Container entrypoints and package metadata. | ## Development Use the repository scripts rather than hand-editing derived bundle state. ```bash ./scripts/gate.sh # run workspace tests without refreshing bundles ./scripts/gate.sh --refresh-bundles # explicit expensive bundle refresh, then tests ./scripts/pkg/install-local-direct.sh # install current built artifacts into packaged layout ./scripts/pkg/install-local-direct.sh --populate # expensive: refresh bundles first ``` Common loops: | Change type | Recommended loop | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | Rust-only compile feedback | `cargo build` or targeted `cargo test -p ` | | Rust affecting bundled binaries | Targeted `cargo build --release -p `, then explicit bundle refresh only if needed. | | Bundle YAML, schemas, tools, or runtimes | Targeted signing/publish flow; use `./scripts/gate.sh --refresh-bundles` only for release validation. | | Browser UI assets | `./scripts/dev-ui-assets.sh --background --open`; no bundle refresh. | | Daemon/CLI behavior with installed bundles | `./scripts/pkg/install-local-direct.sh` after building touched user-facing binaries. | | Packaged layout repair | `./scripts/pkg/install-local-direct.sh --populate` only when artifacts must be regenerated. | Hard rules for contributors and agents: - Do not manually copy bundle-owned binaries into `/usr/bin` as a fix. - Do not edit signed bundle YAML and leave stale signatures. - Do not add hardcoded fallbacks for stale bundle state; regenerate bundles. - Restart a running daemon after reinitializing bundles so in-memory registries match disk. ## License MIT. ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [leolilley](https://github.com/leolilley) - **Source:** [leolilley/ryeos](https://github.com/leolilley/ryeos) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-leolilley-ryeos - Seller: https://agentstack.voostack.com/s/leolilley - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.