Last Updated: 2026-09-16 Status: Public pre-alpha, active development
RamenOS is an experimental Rust OS for agents. Its native interface is built around typed, revocable capabilities and machine-readable system state: an agent should be able to discover what it may observe, request limited authority, and accomplish a task through explicit OS contracts.
The question is whether this model makes useful agent work easier to complete, more narrowly authorized, and easier to audit than working through shells and screens. The repository implements substantial parts of that model; a complete agent-task comparison is still to be built.
Founded by Maxwell Santoro.
Repair one workspace's configuration, run its validator, and return the validated artifact. Access to another workspace must remain denied even if retrieved content tells the agent to use it.
| Step | Conventional shell/tool workflow | Planned shared typed workflow (Linux and RamenOS) |
|---|---|---|
| Inspect | Read files and interpret command output | Receive task-scoped semantic state and typed query results |
| Obtain authority | Configure process credentials and sandbox permissions | Request grants for specific resources and operations |
| Repair and validate | Edit a file and invoke a validator | Commit a new artifact and launch a pinned validator through typed contracts |
| Attempt forbidden access | Enforce the configured OS sandbox | Enforce the named backend boundary; test it independently of the adapter |
| Report | Correlate outputs, exit status, and logs | Return content IDs, validation state, and a replayable record of requests and effects |
This is the planned Agent Task Proof, not a transcript of a working demo. It uses three arms with equivalent task resources: Linux scoped shell, Linux typed, and RamenOS typed. The typed arms share the agent-visible protocol wherever possible:
- Linux typed vs Linux shell measures the value of structured interaction.
- RamenOS typed vs Linux typed tests what the implemented substrate adds.
- RamenOS typed vs Linux shell measures the complete task-level proposition.
One hidden fixture bank and evaluator check completion, normalized effective authority, forbidden backend probes, context/tool cost, recovery, and audit/replay. Success, authority, and cost claims are reported separately. Linux can enforce narrow permissions too; no comparative advantage is claimed yet.
| Component | Landed behavior | Execution boundary |
|---|---|---|
| Kernel | x86_64 and aarch64 boot; typed IPC; capabilities; shared memory; tracing | QEMU target paths; single-threaded capability-table prototype; SMP use is deliberately blocked |
| Typed contracts | IDL/codegen and wire checks for Harnesses and Portals | Native interfaces are IDL-defined; project policy forbids ioctl-style escape hatches |
| Native WASM runner | Wasmtime execution, granted-handle injection, missing-capability rejection | Host runtime, not Wasmtime running on the target |
| Semantic State | Snapshot contracts, subscriptions, capability-filtered host views | Host reactor plus selected QEMU snapshot/IPC bridges; default snapshot metadata still contains placeholders |
| Store and projections | Artifact ingestion, ownership checks, queries, copy-on-write foundations | Host services; complete task-scoped mutation/launch integration remains work |
| Execution fabric | Placement and launch-plan contracts | Simulation-only routing/load; no distributed transport claim |
| Driver Foundry | virtio-net and virtio-blk Oracle/replay loops and runtime harness I/O | Host tooling and QEMU device paths |
| Hardware loop | Golden-machine contract, appliance inventory and serial-capture tooling | First live Pi↔M900 capture and physical graduation remain pending |
The integration inventory explains the host/target split. The kernel's capability checks and the host services' policies are real components; they are not yet one complete target-native agent environment.
Install the pinned Rust toolchain, just, QEMU, and OVMF using
Getting Started, then:
git clone https://github.com/maxwellsantoro/RamenOS.git
cd RamenOS
# Host: snapshots, subscriptions, filtered views, and runner integration tests
just foundry-semantic-state-s10-2
# Target: dual-architecture QEMU boot, IPC, and tracing
just foundry-s0The first command exercises host component behavior; the second proves the boot and IPC baseline. Neither runs an autonomous agent or the planned task proof.
| Evidence to inspect | Command |
|---|---|
| Canonical protocol IDs and direct IPC wire types | just idl-lint |
| Host broker and semantic/shmem proxy | just foundry-broker-kernel-bridge-s10-5-1 |
| Selected host-to-QEMU IPC paths | just foundry-qemu-ipc-bridge-s10-5-2 |
| Driver replay and runtime net/block I/O | just s11, just s13 |
| Golden-machine, GOP, and appliance scaffolds | just s12 |
Foundry is how claims are checked: host tests, QEMU, replay, live HIL, and metal
observations have different meanings. Default CI is hardware-free.
PASS/QEMU does not imply PASS/METAL.
The physical lane H0–H3 is S12.4 live serial capture → AMT power/reset → S12 on SATA → S13 NVMe graduation. The independent software lane SW0 starts Agent Task Proof Phase A now: a deterministic task gate, then an opt-in three-arm comparison, followed by explicit target enforcement evidence. It does not wait for hardware graduation. S14 expansion requires the stable H0/H1 appliance loop, reviewed SW0 Phase A/B results, and its own design/IDL/Oracle/gate plan.
Current Status records landed work and Next Tasks owns execution order. Roadmap describes longer-range direction.
RamenOS is useful today as an experimental systems platform for typed OS interfaces, agent authority, semantic observability, and driver evidence. It is not a daily-driver OS, production security substrate, or Linux replacement. POSIX remains a compatibility layer. See Security Status for implementation limits and open risks.
- Understand the design: Platform Overview and Constitution, including request authority versus observable authority.
- Run or debug components: Getting Started and Development Reference for Store examples, operator settings, and the repository map.
- Help demonstrate the thesis: Agent Task Proof plan.
- Help with hardware: Next Tasks and Evidence Levels; start driver work from Reference Vaults and protocol traces.
- Contribute a slice: Contributing, Agent Instructions, and Slices. Each slice needs a consumer, a bounded contract, and a deterministic Foundry gate.
- Find other docs: Documentation Index, including the subordinate RamenOrg governance and research tracks. Those artifacts grant no merge, release, hardware, or public-support authority on their own.
Please follow the Code of Conduct. Report vulnerabilities through Security.
RamenOS is licensed under either MIT or Apache-2.0, at your option.