Ryeos

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

╭──────────────╮  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

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

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

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

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:

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:

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:

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

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:

{
  "mcpServers": {
    "ryeos": {
      "command": "ryeosd-mcp"
    }
  }
}

The MCP tool accepts argv for ryeos:

{
  "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.

./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
• Source: leolilley/ryeos
• License: MIT

Install and usage instructions live in the source repository linked above.