RVM — The Virtual Machine Built for the Agentic Age

Agents don't fit in VMs. They need something that understands how they think.

19 runtime and library crates, plus integration and benchmark packages. RVM automatically detects new Claude Code releases, runs its release workflow, and publishes nightly builds. See Releases | User Guide | pi.ruv.io

Part of the RuVector ecosystem. Uses RuVix kernel primitives and RVF package format. Designed for Cognitum Seed, Appliance, and future chip targets.

Traditional hypervisors were built for an era of static server workloads — long-running VMs with predictable resource needs. AI agents are different. They spawn in milliseconds, communicate in dense, shifting graphs, share context across trust boundaries, and die without warning. VMs are the wrong abstraction.

RVM replaces VMs with coherence domains — lightweight, graph-structured partitions whose isolation, scheduling, and memory placement are driven by how agents actually communicate. When two agents start talking more, RVM moves them closer. When trust drops, RVM splits them apart. Every mutation is proof-gated. Every action is witnessed. The system understands its own structure.

Agent swarm → [RVM Coherence Engine] → Optimal Placement → Witness Proof
                    ↑                                            │
                    └──── Agent Communication Graph ─────────────┘
                          (< 50µs adaptive re-partitioning)

No KVM. No Linux. No VMs. Bare-metal Rust. Built for agents.

Traditional VM:     VM₁  VM₂  VM₃  VM₄    (static, opaque boxes — agents don't fit)
                    ─────────────────────
RVM:                ┌─A──B─┐  ┌─C─┐  D    (dynamic, agent-driven domains)
                    │  ↔   │──│ ↔ │──↔    (edges = agent communication weight)
                    └──────┘  └───┘        (auto-split when trust or coupling changes)

What Agents Need vs What They Get

What Agents Need	VMs / Containers	RVM
Sub-millisecond spawn	Seconds to boot	< 10µs partition switch
Dense, shifting comms graph	Static NIC-to-NIC	Graph-weighted CommEdges, auto-rebalanced
Shared context with isolation	All or nothing	Capability-gated shared memory, proof-checked
Per-agent fault containment	Whole-VM crash	F1–F4 graduated rollback, no reboot needed
Auditable every action	External log bolted on	64-byte witness on every syscall, hash-chained
Hibernate and reconstruct	Kill and restart	Dormant tier → rebuilt from witness log
Run on 64KB MCUs	Needs gigabytes	Seed profile: 64KB–1MB, capability-enforced

Why RVM?

Dynamic Re-isolation and Self-Healing Boundaries. Because RVM uses graph-theoretic mincut algorithms, it can dynamically restructure its isolation boundaries to match how workloads actually communicate. If an agent in one partition begins communicating heavily with an agent in another, RVM automatically triggers a partition split and migrates the agent to optimise placement — no manual configuration. No existing hypervisor can split or merge live partitions along a graph-theoretic cut boundary.

Memory Time Travel and Deep Forensics. Traditional virtual memory permanently overwrites state or blindly swaps it to disk. RVM stores dormant memory as a checkpoint combined with a delta-compressed witness trail. Any historical state can be perfectly rebuilt on demand — days or weeks later — because every privileged action is recorded in a tamper-evident, hash-chained witness log. External forensic tools can reconstruct past states to answer precise questions such as "which task mutated this vector store between 14:00 and 14:05 on Tuesday?"

Targeted Fault Rollback Without Global Reboots. When the kernel detects a coherence violation or memory corruption it does not crash. Instead it finds the last known-good checkpoint, replays the witness log, explicitly skips the mutation that caused the failure, and resumes from a corrected state (DC-14, failure classes F1–F3).

Deterministic Multi-Tenant Edge Orchestration. Existing edge orchestrators rely on Linux-based VMs or containers, inheriting scheduling unpredictability and no guarantee of bounded latency with provable isolation. RVM enables scenarios such as an autonomous vehicle where safety-critical sensor-fusion agents (Reflex mode, < 10 µs switch) are strictly isolated from low-priority infotainment agents, or a smart factory floor running hard real-time PLC control loops safely alongside ML inference agents.

High-Assurance Security on Extreme Microcontrollers. Through its Seed hardware profile (ADR-138), RVM brings capability-enforced isolation, proof-gated execution, and witness attestation to deeply constrained IoT devices with as little as 64 KB of RAM. Delivering this level of zero-trust, auditable security on microcontroller-class hardware is a novel capability not provided by any existing embedded operating system.

Architecture

+----------------------------------------------------------+
|                       rvm-kernel                         |
|                                                          |
|  +-----------+  +-----------+  +------------+            |
|  | rvm-boot  |  | rvm-sched |  | rvm-memory |            |
|  +-----+-----+  +-----+-----+  +------+-----+            |
|        |              |               |                   |
|  +-----+--------------+---------------+------+            |
|  |               rvm-partition               |            |
|  +-----+---------+-----------+----------+----+            |
|        |         |           |          |                 |
|  +-----+--+ +---+------+ +--+-----+ +--+--------+        |
|  | rvm-cap| |rvm-witness| |rvm-proof| |rvm-security|     |
|  +-----+--+ +---+------+ +--+-----+ +--+--------+        |
|        |         |           |          |                 |
|  +-----+---------+-----------+----------+----+            |
|  |               rvm-types                   |            |
|  +-----+-------------------------------------+            |
|        |                                                  |
|  +-----+--+  +----------+  +-------------+               |
|  | rvm-hal|  | rvm-wasm |  |rvm-coherence|               |
|  +--------+  +----------+  +-------------+               |
+----------------------------------------------------------+

Layer 4: Persistent State
         witness log │ compressed dormant memory │ RVF checkpoints
         ─────────────────────────────────────────────────────────
Layer 3: Execution Adapters
         bare partition │ WASM partition │ service adapter
         ─────────────────────────────────────────────────────────
Layer 2: Coherence Engine (OPTIONAL — DC-1)
         graph state │ mincut │ pressure scoring │ migration
         ─────────────────────────────────────────────────────────
Layer 1: RVM Core (Rust, no_std)
         partitions │ capabilities │ scheduler │ witnesses
         ─────────────────────────────────────────────────────────
Layer 0: Machine Entry (assembly, <500 LoC)
         reset vector │ trap handlers │ context switch

First-Class Kernel Objects

Object	Purpose
Partition	Coherence domain container — unit of scheduling, isolation, and migration
Capability	Unforgeable authority token with 7 rights (READ, WRITE, GRANT, REVOKE, EXECUTE, PROVE, GRANT_ONCE)
Witness	64-byte hash-chained audit record emitted by every privileged action
MemoryRegion	Typed, tiered, owned memory (Hot/Warm/Dormant/Cold) with move semantics
CommEdge	Inter-partition communication channel — weighted edge in the coherence graph
DeviceLease	Time-bounded, revocable hardware device access
CoherenceScore	Graph-derived locality and coupling metric
CutPressure	Isolation signal — high pressure triggers migration or split
RecoveryCheckpoint	State snapshot for rollback and reconstruction

Crate Structure

Crate	Purpose
`rvm-types`	Foundation types: addresses, IDs, capabilities, witness records, coherence scores
`rvm-hal`	Platform-agnostic hardware abstraction traits (MMU, timer, interrupts)
`rvm-cap`	Capability-based access control with derivation trees and three-tier proof
`rvm-witness`	Append-only witness trail with hash-chain integrity
`rvm-proof`	Proof-gated state transitions (P1/P2/P3 tiers), TEE pipeline, cryptographic signers (Ed25519, HMAC-SHA256)
`rvm-partition`	Partition lifecycle, split/merge, capability tables, communication edges
`rvm-sched`	Coherence-weighted 2-signal scheduler (deadline urgency + cut pressure)
`rvm-memory`	Guest physical address space management with tiered placement
`rvm-coherence`	Unified coherence engine: graph, mincut, scoring, pressure, adaptive, pluggable backends, edge decay
`rvm-boot`	Deterministic 7-phase boot sequence with witness gating
`rvm-wasm`	Optional WebAssembly guest runtime
`rvm-security`	Unified security gate: capability check + proof verification + witness log
`rvm-kernel`	Full integration: coherence engine, IPC→graph feeding, scheduler, split/merge, security gates, tier management
`rvm-gpu`	GPU compute subsystem: device, context, kernel, buffer, queue, budget (optional, feature-gated)
`rvm-rvf`	RVF loader for RVForge packages: manifest verification, per-segment verification, capability mapping, identity preservation (ADR-155)
`rvm-anchor`	Verifies external evaluation receipts and anchors their commitments into the RVM witness chain (ADR-156)
`rvm-host`	Per-OS adapters and isolation mechanisms: picks the strongest available isolation, places the agent, spawns it
`rvm-launch`	Instance lifecycle over the adapters: `inspect`, `verify`, run, suspend, resume, checkpoint, witness, terminate (ADR-289)
`rvm-context`	Capability-governed `ruv://` names, immutable RVF revisions, CAS aliases, progressive views, and epoch receipts (ADR-157)
`rvm-context-service`	Encrypted REDB persistence, exact-scope RuVector retrieval, receipt draining, canonical RVF compilation, and TLS/MCP/CLI hosting (ADR-158)

Dependency Graph

rvm-types (foundation, no deps)
    ├── rvm-hal
    ├── rvm-cap
    ├── rvm-witness
    ├── rvm-proof ← rvm-cap + rvm-witness
    ├── rvm-partition ← rvm-hal + rvm-cap + rvm-witness
    ├── rvm-sched ← rvm-partition + rvm-witness
    ├── rvm-memory
    ├── rvm-coherence ← rvm-partition + rvm-sched [OPTIONAL]
    ├── rvm-boot ← rvm-hal + rvm-partition + rvm-witness + rvm-sched + rvm-memory
    ├── rvm-wasm ← rvm-partition + rvm-cap + rvm-witness [OPTIONAL]
    ├── rvm-security ← rvm-witness
    ├── rvm-gpu
    ├── rvm-rvf ← rvm-cap + rvm-witness
    ├── rvm-anchor ← rvm-witness
    ├── rvm-host ← rvm-cap + rvm-witness + rvm-partition + rvm-wasm + rvm-rvf
    ├── rvm-launch ← rvm-witness + rvm-wasm + rvm-rvf + rvm-host
    ├── rvm-context ← rvm-cap + rvm-witness + rvm-proof + rvm-rvf
    └── rvm-kernel ← rvm-hal + rvm-cap + rvm-witness + rvm-proof +
                     rvm-partition + rvm-sched + rvm-memory + rvm-coherence +
                     rvm-boot + rvm-wasm + rvm-security + rvm-gpu

Build

# Check (no_std by default)
cargo check

# Run workspace library tests
cargo test --workspace --lib

# Run Criterion benchmarks
cargo bench

# Build with std support
cargo check --features std

# Cross-compile for AArch64 bare-metal
rustup target add aarch64-unknown-none
make build    # or: cargo build --target aarch64-unknown-none -p rvm-kernel --release

# Boot on QEMU (requires qemu-system-aarch64)
make run      # boots at 0x4000_0000, PL011 UART output

Design Constraints (ADR-132 through ADR-140)

ID	Constraint	Status
DC-1	Coherence engine is optional; system degrades gracefully	Implemented — adaptive engine, static fallback
DC-2	MinCut budget: 50 µs per epoch	Implemented — Stoer-Wagner with iteration budget, ~331ns measured
DC-3	Capabilities are unforgeable, monotonically attenuated	Implemented — constant-time P1, 4096-nonce ring
DC-4	2-signal priority: `deadline_urgency + cut_pressure_boost`	Implemented
DC-5	Three systems cleanly separated (kernel + coherence + agents)	Enforced — feature-gated
DC-6	Degraded mode when coherence unavailable	Implemented — enter/exit with witnesses, scheduler zeroes CutPressure
DC-7	Migration timeout enforcement (100 ms)	Implemented — MigrationTracker with auto-abort
DC-8	Capabilities follow objects during partition split	Implemented — scored region assignment
DC-9	Coherence score range [0.0, 1.0] as fixed-point	Implemented — u16 basis points
DC-10	Epoch-based witness batching (no per-switch records)	Implemented
DC-11	Merge requires coherence above threshold + adjacency + resources	Implemented — 3-check validation
DC-12	Max 256 physical VMIDs, multiplexed for >256 partitions	Implemented
DC-13	WASM is optional; native bare partitions are first class	Enforced
DC-14	Failure classes: transient, recoverable, permanent, catastrophic	Implemented — F1-F4 with escalation
DC-15	All types are `no_std`, `forbid(unsafe_code)`, `deny(missing_docs)`	Enforced

Benchmarks (All ADR Targets Exceeded)

Operation	ADR Target	Measured	Ratio
Witness emit	< 500 ns	~17 ns	29x faster
P1 capability verify	< 1 µs	< 1 ns	>1000x faster
P2 proof pipeline	< 100 µs	~996 ns	100x faster
Partition switch (stub)	< 10 µs	~6 ns	1600x faster
MinCut 16-node	< 50 µs	~331 ns	150x faster
Coherence score (16-node)	budgeted	~84 ns	—
Buddy alloc/free cycle	fast	~184 ns	—
FNV-1a hash (64 bytes)	fast	~28 ns	—
Security gate P1	fast	~17 ns	—
Witness chain verify (64 records)	fast	~892 ns	—
GPU context create	< 20 ns	~2.2 ns	9x faster
GPU launch config validate	< 10 ns	~0.26 ns	38x faster
GPU queue enqueue	< 30 ns	~0.26 ns	115x faster
GPU budget reset	< 10 ns	~1.0 ns	10x faster

Run cargo bench for full criterion results with HTML reports.

Implementation Status

The numeric counts below are the repository's legacy documented snapshot, not release evidence for this change. Newer crates are listed without invented counts; use the current CI run for authoritative test results. ADR-157 keeps its acceptance evidence marked planned until that run is attached.

Crate	Tests	Key Features
`rvm-types`	~40 types	64-byte `WitnessRecord` (compile-time asserted), ~40 `ActionKind` variants, 34 error variants
`rvm-hal`	16	AArch64 EL2: stage-2 page tables, PL011 UART, GICv2, ARM generic timer
`rvm-cap`	40	Constant-time P1, nonce ring (4096 + watermark), P3 derivation chain verification, epoch revocation
`rvm-witness`	29	SHA-256 hash chain (FNV-1a fallback), HMAC-SHA256 signing, 16MB ring buffer, `StrictSigner`, RLE-compressed replay
`rvm-proof`	45	Proof engine, context builder, constant-time P2 (all 6 rules), P3 deep verification (SHA-256 + Merkle + WitnessSigner), TEE pipeline, Ed25519/HMAC-SHA256/DualHmac signers
`rvm-partition`	86	Lifecycle state machine, IPC message queues, device leases, scored split/merge, `remove()`
`rvm-sched`	49	2-signal priority, SMP coordinator, VMID-aware switch, `SwitchContext::init()`, degraded fallback
`rvm-memory`	110	Buddy allocator with coalescing, 4-tier management, LZ4-style RLE compression, reconstruction
`rvm-coherence`	59	Unified coherence engine, pluggable MinCut/Coherence backends, edge decay, bridge to ruvector
`rvm-boot`	26	7-phase measured boot, attestation digest, HAL init, entry point
`rvm-wasm`	33	7-state agent lifecycle, `HostContext` trait, section parser (13 section types), migration
`rvm-rvf`	—	Full-container identity, structural and segment checks, capability mapping, verified-package boundary
`rvm-anchor`	—	External receipt verification and domain-separated witness anchoring
`rvm-security`	45	Unified security gate (P1/P2/P3), `SignedSecurityGate` with per-link signature verification, input validation, attestation chain, DMA budget
`rvm-host`	—	Isolation selection and placement for verified RVF packages
`rvm-launch`	—	Verified instance lifecycle, checkpoint lineage, and witnessed refusals
`rvm-context`	—	Strict `ruv://` parser, live capability scopes, immutable RVF objects, CAS aliases, views, and epoch receipts
`rvm-kernel`	62	Full integration: IPC→coherence, scheduler, split/merge, security gates, degraded mode, device leases, tier mgmt
`rvm-gpu`	65	Device/context/kernel/buffer/queue management, 4-dimensional budget, coherence acceleration configs
Integration	48	17 e2e scenarios: agent lifecycle, split pressure, memory tiers, cap chain, boot timing
Benchmarks	21	Criterion benchmarks for all performance-critical paths
Legacy documented total	945	Excludes rows marked —; consult current CI for pass/fail evidence

Security Audit Results

11 findings from formal security review, 8 fixed in code:

Severity	Finding	Status
Critical	P1 timing side channel	Fixed — constant-time bitmask
High	Revocation didn't invalidate descendants	Fixed — iterative subtree sync
High	Cross-partition host memory overlap	Fixed — global overlap check
Medium	Generation counter wrap aliasing	Fixed — skip gen 0
Medium	next_id overflow	Fixed — checked_add
Medium	Recursive revoke stack overflow	Fixed — iterative stack
Medium	Incomplete merge preconditions	Fixed — full validation
Low	Terminated agent slots never freed	Fixed — set None
Medium	Nonce ring too small (64)	Fixed — upgraded to 4096 + watermark
Medium	TOCTOU in quota check	Fixed — atomic check_and_record
Low	NullSigner always-true	Fixed — StrictSigner + deprecation

🔍 RVM vs State of the Art (12 differences)

	RVM	KVM/Firecracker	seL4	Theseus OS
Primary abstraction	Coherence domains (graph-partitioned)	Virtual machines	Processes + capabilities	Cells (intralingual)
Isolation driver	Dynamic mincut + cut pressure	Hardware EPT/NPT	Formal verification + caps	Rust type system
Scheduling signal	Structural coherence (graph metrics)	CPU time / fairness	Priority / round-robin	Cooperative
Memory model	4-tier reconstructable (Hot/Warm/Dormant/Cold)	Demand paging	Untyped memory + retype	Single address space
Audit trail	Witness-native (64B hash-chained records)	External logging	Not built-in	Not built-in
Mutation control	Proof-gated (3-layer: P1/P2/P3)	Unix permissions	Capability tokens	Rust ownership
Partition operations	Live split/merge along graph cuts	Not supported	Not supported	Not supported
Linux dependency	None — bare-metal	Yes (KVM is a kernel module)	None	None
Language	95-99% Rust, <500 LoC assembly	C	C + Isabelle/HOL proofs	Rust
Target	Edge, IoT, agents	Cloud servers	Safety-critical	Research
Boot time	< 250ms to first witness	~125ms (Firecracker)	Varies	N/A
Partition switch	< 10µs	~2-5µs (VM exit)	~0.5-1µs (IPC)	N/A (no isolation)

✨ 6 Novel Capabilities (No Prior Art)

1. Kernel-Level Graph Control Loop

No existing OS uses spectral graph coherence metrics as a scheduling signal. RVM's coherence engine runs mincut algorithms in the kernel's scheduling loop — graph structure directly drives where computation runs, when partitions split, and which memory stays resident.

2. Reconstructable Memory ("Memory Time Travel")

RVM explicitly rejects demand paging. Dormant memory is stored as witness checkpoint + delta compression, not raw bytes. The system can deterministically reconstruct any historical state from the witness log.

3. Proof-Gated Infrastructure

Every state mutation requires a valid proof token verified through a three-tier system: P1 capability (<1µs), P2 policy (<100µs), P3 deep derivation chain verification (walks tree to root, validates ancestor integrity + epoch monotonicity).

4. Witness-Native OS

Every privileged action emits a fixed 64-byte, SHA-256 hash-chained record with HMAC-SHA256 signatures. Tamper-evident by construction. Full deterministic replay from any checkpoint.

5. Live Partition Split/Merge

Partitions split along graph-theoretic cut boundaries and merge when coherence rises. Capabilities follow ownership (DC-8), regions use weighted scoring (DC-9), merges require 7 preconditions (DC-11).

6. Edge Security on 64KB RAM

Capability-based isolation, proof-gated execution, and witness attestation on microcontroller-class hardware (Cortex-M/R, 64KB RAM).

🎯 Success Criteria (v1)

#	Criterion	Target
1	Workspace runtime crates preserve their declared `no_std` and safe-Rust policies	CI gate
2	Cold boot to first witness	< 250ms on Appliance hardware
3	Hot partition switch	< 10 microseconds
4	Witness record is exactly 64 bytes, cache-line aligned	Compile-time asserted
5	Capability derivation depth bounded at 8 levels	Enforced
6	EMA coherence filter operates without floating-point	Implemented
7	Boot sequence is deterministic and witness-gated	Implemented
8	Remote memory traffic reduction ≥ 20% vs naive placement	Target
9	Fault recovery without global reboot (F1–F3)	Target

🏗️ Implementation Phases

Phase 1: Foundation (M0-M1) — "Can it boot and isolate?"

M0: Bare-metal Rust boot on QEMU AArch64 virt. Reset → EL2 → serial → MMU → first witness.
M1: Partition + capability model. Create, destroy, switch. Simple deadline scheduler.

Phase 2: Differentiation (M2-M3) — "Can it prove and witness?"

M2: Witness logging (64-byte chained records) + P1/P2 proof verifier.
M3: 2-signal scheduler (deadline + cut_pressure). Flow + Reflex modes. Zero-copy IPC.

Phase 3: Innovation (M4-M5) — "Can it think about coherence?"

M4: Dynamic mincut integration (DC-2 budget). Live coherence graph. Migration triggers.
M5: Memory tier management. Reconstruction from dormant state.

Phase 4: Expansion (M6-M7) — "Can agents run on it?"

M6: WASM agent runtime adapter. Agent lifecycle.
M7: Seed/Appliance hardware bring-up. All success criteria.

🔐 Security Model

Capability-Based Authority. All access controlled through unforgeable kernel-resident tokens. No ambient authority. Seven rights with monotonic attenuation.

Proof-Gated Mutation. No memory remap, device mapping, migration, or partition merge without a valid proof token. Three tiers with strict latency budgets.

Witness-Native Audit. 64-byte records for every mutating operation. Hash-chained for tamper evidence. Deterministic replay from checkpoint + witness log.

Failure Classification. F1 (agent restart) → F2 (partition reconstruct) → F3 (memory rollback) → F4 (kernel reboot). Each escalation witnessed.

GPU Compute Support (ADR-144)

Overview

RVM provides capability-gated, proof-verified, witness-logged GPU compute access for partitions. GPU support is feature-gated — zero cost when disabled.

Quick Start

// Enable in Cargo.toml
// rvm-kernel = { features = ["gpu"] }

use rvm_kernel::gpu::{
    context::GpuContext,
    kernel::LaunchConfig,
    budget::GpuBudget,
    queue::{GpuQueue, QueueCommand},
    buffer::{GpuBuffer, BufferUsage},
    GpuTier, GpuStatus,
};
use rvm_types::PartitionId;

// Create a GPU context for a partition
let budget = GpuBudget::new(
    1_000_000_000,  // 1 second compute budget
    512 * 1024 * 1024,  // 512 MB memory
    1_000_000_000,  // 1 GB transfer budget
    1000,  // max 1000 kernel launches per epoch
);
let ctx = GpuContext::new(PartitionId::new(1), 0, budget);

// Configure a kernel launch (3D workgroups)
let config = LaunchConfig {
    workgroups: [64, 64, 1],      // 64x64 workgroups
    workgroup_size: [256, 1, 1],  // 256 threads each
    shared_memory_bytes: 16384,    // 16 KB shared memory
    timeout_ns: 100_000_000,       // 100ms timeout
};
assert!(config.validate().is_ok());
println!("Total threads: {}", config.total_threads()); // 1,048,576

// Create and manage GPU buffers
let buffer = GpuBuffer {
    id: BufferId::new(1),
    partition_id: PartitionId::new(1),
    size_bytes: 1024 * 1024,  // 1 MB
    usage: BufferUsage::Storage,
    host_mapped: false,
};

Backends

Backend	Feature Flag	Platform	Use Case
CUDA	`cuda`	NVIDIA GPUs	ML inference, HPC
WebGPU	`webgpu`	Cross-platform	Portable compute
Metal	`metal`	Apple Silicon	macOS/iOS acceleration
OpenCL	`opencl`	Any GPU	Legacy hardware
Vulkan	`vulkan`	Any GPU	Low-level compute
WASM SIMD	`wasm-simd`	CPU only	Seed profile fallback

Architecture

WASM Agent ──→ HostFunction::GpuLaunch ──→ SecurityGate ──→ GpuContext ──→ GPU
                                              │
                              CapRights::EXECUTE + WRITE
                              DmaBudget check
                              WitnessRecord emission

Security Model

Capability-gated: requires EXECUTE | WRITE rights on device
IOMMU isolated: per-partition GPU page tables
DMA budgeted: bytes transferred per epoch
Witnessed: every kernel launch, transfer, and allocation logged
Timeout enforced: kernel execution deadline (100ms default)
Budget enforcement: 4 dimensions — compute time, memory, transfers, launches

Coherence Engine Acceleration

MinCut and scoring algorithms can be offloaded to GPU:

use rvm_gpu::accel::{GpuMinCutConfig, GpuScoringConfig};

let mincut_cfg = GpuMinCutConfig {
    max_nodes: 32,
    budget_iterations: 31,
    use_gpu: true,
};

let scoring_cfg = GpuScoringConfig {
    max_partitions: 256,
    use_gpu: true,
};

Source

GPU compute is powered by cuda-rust-wasm (source), providing CUDA→Rust transpilation with WebGPU/Metal/Vulkan backends. Full source available in the cuda-wasm/ submodule.

See ADR-144 for the complete architecture decision record.

🖥️ Target Platforms

Platform	Profile	RAM	Coherence Engine	WASM
Seed	Tiny, persistent, event-driven	64KB–1MB	No (DC-1)	Optional
Appliance	Edge hub, deterministic orchestration	1–32GB	Yes (full)	Yes
Chip	Future Cognitum silicon	Tile-local	Hardware-assisted	Yes

📚 ADR References

ADR	Topic
ADR-132	RVM top-level architecture and 15 design constraints
ADR-133	Partition object model and split/merge semantics
ADR-134	Witness schema and log format (64-byte records)
ADR-135	Three-tier proof system (P1/P2/P3)
ADR-136	Memory hierarchy and reconstruction
ADR-137	Bare-metal boot sequence
ADR-138	Seed hardware bring-up
ADR-139	Appliance deployment model
ADR-140	Agent runtime adapter
ADR-141	Coherence engine kernel integration and runtime pipeline
ADR-142	TEE-backed cryptographic verification (SHA-256, Ed25519, HMAC-SHA256, TEE pipeline)
ADR-143	Nightly verified release pipeline
ADR-144	GPU compute support via cuda-rust-wasm
ADR-145	IPC protocol semantics
ADR-146	SMP scheduling model
ADR-147	Hardware abstraction layer contract
ADR-148	Error model and recovery state machine
ADR-149	RVF integration for RVM
ADR-150	Device lease lifecycle protocol
ADR-151	GPU witness event registry
ADR-152	GPU MinCut correctness model
ADR-153	Multi-node mesh protocol
ADR-154	Formal verification roadmap
ADR-155	RVF execution contract for RVForge packages
ADR-156	External receipt anchoring into the witness chain
ADR-157	Capability-governed `ruv://` context namespace
ADR-158	Durable hosted `ruv://` context service

🔧 Development

Prerequisites

Rust 1.77+ with aarch64-unknown-none target
QEMU 8.0+ (for AArch64 virt machine emulation)

rustup target add aarch64-unknown-none
brew install qemu  # macOS

Project Conventions

#![no_std] everywhere — the kernel runs on bare metal
#![forbid(unsafe_code)] where possible; unsafe blocks audited and commented
#![deny(missing_docs)] — every public API documented
Move semantics for memory ownership (OwnedRegion<P> is non-copyable)
Const generics for fixed-size structures (no heap allocation in kernel paths)
Every state mutation emits a witness record

📖 User Guide & Tutorial

Quick Start (5 Minutes)

# 1. Clone and verify (--recurse-submodules pulls ruvector + rudevolution)
git clone --recurse-submodules https://github.com/ruvnet/rvm.git && cd rvm
cargo test --workspace --lib    # Run the current workspace library suite

# 2. Run benchmarks
cargo bench -p rvm-benches      # Criterion benchmark suite

# 3. Build for bare metal
rustup target add aarch64-unknown-none
cargo install cargo-binutils && rustup component add llvm-tools
make build                      # AArch64 release binary

# 4. Boot in QEMU
brew install qemu               # macOS (or apt install qemu-system-aarch64)
make run                        # Boots at 0x4000_0000, PL011 UART output

# 5. Use as a library
# Add to Cargo.toml: rvm-kernel = { path = "crates/rvm-kernel" }

use rvm_kernel::{
    types, hal, cap, witness, proof, partition,
    sched, memory, coherence, boot, wasm, security,
};

Full User Guide

The userguide/ directory contains 16 numbered chapters covering the kernel, artifact, and governed-context subsystems:

Chapter	Topic
01 Quick Start	Build, test, and boot in 5 minutes
02 Core Concepts	Partitions, capabilities, witnesses, proofs, coherence
03 Architecture	Layer diagram, data flow, boot sequence, feature flags
04 Crate Reference	Workspace crate types, APIs, and dependencies
05 Capabilities & Proofs	7 rights, delegation trees, 3 proof tiers, TEE
06 Witness & Audit	64-byte records, hash chains, signing, querying
07 Partitions & Scheduling	Lifecycle, IPC, split/merge, 2-signal scheduler
08 Memory Model	4 tiers, buddy allocator, reconstruction
09 WASM Agents	Module validation, 7-state lifecycle, migration
10 Security	3-stage gate, attestation, audit results
11 Performance	Benchmark methodology, build profiles, tuning
12 Bare Metal	Linker script, QEMU, measured boot, Seed/Appliance
13 Advanced & Exotic	6 novel capabilities, fault rollback, RuVector
14 Troubleshooting	12 categories of common issues
15 Glossary	60+ terms with cross-references
16 Governed `ruv://` Context	Canonical names, capabilities, immutable RVF revisions, CAS aliases, views, and receipts
Cross-Reference	Concept index, API finder, "I want to..." tasks

🔌 MCP Documentation Tools

RVM ships with an MCP (Model Context Protocol) server and CLI for AI-assisted documentation search and navigation.

Installation

cd userguide/mcp
npm install && npm run build

Register with Claude Code

claude mcp add rvm-docs -- node /path/to/rvm/userguide/mcp/dist/index.js

MCP Tools (6 tools)

Tool	Description	Example
`docs_search`	Full-text keyword search across all docs	`{ "query": "witness chain" }`
`docs_navigate`	Browse table of contents or read a chapter	`{ "chapter": "05" }`
`docs_xref`	Find all cross-references for a concept	`{ "concept": "coherence" }`
`docs_glossary`	Look up a term definition	`{ "term": "partition" }`
`docs_api`	Find documentation for an RVM type/function	`{ "symbol": "SecurityGate" }`
`docs_howto`	Task-oriented "I want to..." search	`{ "task": "build rvm" }`

CLI Usage

cd userguide/mcp
node dist/cli.js search "capability"      # Full-text search
node dist/cli.js nav                       # Table of contents
node dist/cli.js nav 05                    # Read chapter 05
node dist/cli.js xref "witness"            # Cross-references
node dist/cli.js glossary "partition"       # Term lookup
node dist/cli.js api "CapToken"            # API documentation
node dist/cli.js howto "build rvm"         # Task-oriented guide

Shorthand Aliases

node dist/cli.js s "proof"    # search
node dist/cli.js n 03         # navigate
node dist/cli.js x "memory"   # xref
node dist/cli.js g "EMA"      # glossary
node dist/cli.js a "verify"   # api
node dist/cli.js h "deploy"   # howto

Governed `ruv://` Context

→ Read the illustrated guide — why ambient authority breaks down for agents, how the namespace works, and how to wire it up.

In plain terms

Almost every system decides access the same way: you name a thing, the system works out who you are, then it decides. Your authority is ambient — it surrounds your identity and applies to anything you can name. Unix permissions work like this. So do database row filters and most role-based access layers.

That has a failure mode with a name and a sixty-year history: the confused deputy. Something holding more authority than its caller gets talked into spending that authority on the caller's behalf. It isn't compromised and isn't buggy in any local sense — it simply can't tell which of its powers the request was entitled to, because the request only carried a name, and anyone can write a name down.

Agents make this sharp. An agent is a deputy: it holds tools, credentials, and memory, and it takes instructions from text it just retrieved — text someone else may have authored. If naming a resource is enough to reach it, then any string that reaches the model is a possible instruction to reach it.

ruv:// separates the two things ambient systems fuse:

The name is inert. A ruv:// URI is just an address. Parsing one grants nothing. Resolving a skill does not execute it. You can paste one in a ticket without leaking access.
The right arrives separately. A capability handle is handed over deliberately, can be narrowed on the way, and can be revoked. It never travels in the URI and never appears in ordinary logs.
The check happens first. Authorization and its witness record run before the resolver or the search index is touched — not after, and not as a filter on results.

So an agent that talks itself into naming another tenant's memory gets nothing back. Not an empty filtered result — nothing, from a backend that was never asked.

Instead of	Which fails because	`ruv://`
A token in the URL	The URL is the credential — it leaks via logs, referrers, screenshots	Handles never appear in the URI
Checking the ACL after lookup	Existence leaks through timing and errors that differ by cause	Authorization precedes the resolver; four causes return one identical error
`WHERE tenant_id = ?`	One forgotten clause is a breach; every query still traverses everyone's data	A separate physical index per scope — isolation is a different file, not a filter
Path-prefix tenancy	`/project` silently captures `/project-archive`	Segment-wise matching; text prefixes are never used
Soft-deleting a row	The bytes remain and "deleted" is a flag anything can ignore	Destroy the per-object key; the ciphertext becomes noise for everyone

The contract

rvm-context adds a canonical logical namespace for resources, memories, and skills while keeping authority in live RVM capabilities:

# Mutable, human-friendly alias
ruv://context.example/acme/agent/researcher/skills/web-search?view=overview

# Immutable citation to the complete RVF bytes
ruv://context.example/acme/agent/researcher/skills/web-search?rev=sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&view=content

Property	Contract
Identity	A pinned revision is SHA-256 over the complete RVF byte stream
Authority	Capability handle and exact namespace grant travel out of band; a URI never grants access
Retrieval boundary	Authorization and its witness record occur before resolver access or search enumeration
Mutation	Pinned bytes are immutable; versionless aliases advance by full-snapshot compare-and-swap
Representation	Abstract, overview, and content views are digest-bound through a profile in the existing RVF `PROFILE` segment
Execution	Reading a skill never executes it; `EXECUTE` requires a pinned URI and returns a permit for the verified launch path
Audit durability	Contiguous RVM witness ranges are signed as epoch receipts and committed through the existing RVF `WITNESS` segment

The implementation takes inspiration from OpenViking's unified hierarchy and progressive context patterns, but it is an independent RVM-native design and does not copy OpenViking code. ruv:// is a logical identifier, not a network transport or a registered public URI scheme.

The hosted adapter adds encrypted durable storage, an exact-scope RuVector active index, receipt persistence with backpressure, deterministic RVF compilation, TLS-only HTTP, MCP, and a certificate-validating CLI. HTTPS and MCP share one dispatcher, so canonical URI parsing and authorization behavior are identical on both surfaces. The bundled local key provider is development-only; production deployments inject their KMS and replica/cache purge providers.

See the user guide, ADR-157, and ADR-158 for the grammar, threat model, durable service boundary, recovery behavior, and acceptance evidence.

RuVector Integration

The full RuVector ecosystem is available via the ruvector/ submodule. See Integration Map for detailed path references.

Crate	Submodule Path	Role in RVM
`ruvector-mincut`	`ruvector/crates/ruvector-mincut/`	Partition placement and isolation decisions
`ruvector-sparsifier`	`ruvector/crates/ruvector-sparsifier/`	Compressed shadow graph for Laplacian operations
`ruvector-solver`	`ruvector/crates/ruvector-solver/`	Effective resistance → coherence scores
`ruvector-coherence`	`ruvector/crates/ruvector-coherence/`	Spectral coherence tracking
`ruvix`	`ruvector/crates/ruvix/`	Kernel primitives (Task, Capability, Region, Queue, Timer, Proof)
`rvf`	`ruvector/crates/rvf/`	Package format for boot images, checkpoints, and cold storage

RVF Package Ecosystem (22 crates)

Crate	Path	Purpose
`rvf-types`	`ruvector/crates/rvf/rvf-types/`	Core types, manifest, vectors
`rvf-crypto`	`ruvector/crates/rvf/rvf-crypto/`	Cryptographic signing/verification
`rvf-index`	`ruvector/crates/rvf/rvf-index/`	HNSW vector indexing
`rvf-kernel`	`ruvector/crates/rvf/rvf-kernel/`	Kernel-level RVF integration
`rvf-runtime`	`ruvector/crates/rvf/rvf-runtime/`	Runtime execution environment
`rvf-wasm`	`ruvector/crates/rvf/rvf-wasm/`	WASM runtime for RVF containers
`rvf-quant`	`ruvector/crates/rvf/rvf-quant/`	Quantization for memory reduction
`rvf-federation`	`ruvector/crates/rvf/rvf-federation/`	Federated distribution

Related ADRs & Research

Resource	Path
Core architecture	`ruvector/docs/adr/ADR-001-ruvector-core-architecture.md`
Coherence engine	`ruvector/docs/adr/ADR-014-coherence-engine.md`
Memory management	`ruvector/docs/adr/ADR-006-memory-management.md`
Security review	`ruvector/docs/adr/ADR-007-security-review-technical-debt.md`
Architecture docs	`ruvector/docs/architecture/`
Benchmarks	`ruvector/docs/benchmarks/`

RVForge Integration

One signed agent artifact, one identity, wherever it runs. RVForge (@ruvector/rvforge) authors, verifies, signs, and publishes a canonical .rvf agent container; RVM is the execution side of that contract. An illustrated walkthrough of the whole path — authoring a signed artifact through running it under the capability gate — is at https://ruvnet.github.io/RuVector/rvforge/.

Three crates carry that contract here: rvm-rvf verifies the package and maps its capabilities, rvm-host decides what it runs inside, and rvm-launch drives one execution through its lifecycle.

agent.rvf ──[RVForge: author · sign · publish]──→ registry + bundles
     │
     ├──[rvm-rvf:    verify → map capabilities → witness]──→ rvm-cap rights
     ├──[rvm-host:   pick isolation → place → spawn]
     └──[rvm-launch: run · suspend · resume · checkpoint · terminate]

Implemented here

Property	How
Identity preserved	`rvfIdentity` (SHA-256 of the canonical RVF) read and carried, never re-minted
Verify before load	Root manifest verified before executable memory is allocated; every segment verified before it loads
Nothing runs unverified	`Instance::create` takes a `VerifiedPackage` whose only constructor rejects a failed report — there is no path from a failed verify to a running instance
Inspection ≠ execution	`inspect` and `verify` read headers, hash payloads and check signatures without mapping a segment or resolving an entry point — safe to point at hostile artifacts
Nothing undeclared	15 capability classes, default-deny, mapped total into `rvm-cap`
Refusal, not degradation	An unsupported capability class is a witnessed refusal, never a silent partial start
Illegal transitions are errors	The lifecycle state machine permits nothing outside its table, and each refusal is witnessed before it is returned
State binds to lineage	A checkpoint carries the base RVF identity it was produced under; restoring against a different base is refused (ADR-288 §4)
Auditable results	Every verification outcome — pass or fail — emits a witness record
Policy-gated sizes	Segment size limits come from signed policy; `rvm-wasm`'s 1 MB `MAX_MODULE_SIZE` remains the executor-side backstop

Not yet in this repo — rvm-ffi and rvm-node (the embedding surfaces that let Tauri and @ruvector/rvforge drive RVM directly), and streaming WASM validation to replace the fixed module limit. Bare-metal outputs (Agent.rvm.img and friends) remain roadmap. Hosted mode is os-sandbox+wasm and is never described as bare-metal partition isolation.

The rvm-rvf crate owns the boundary between the format and the machine — manifest reading, signature and hash verification, segment resolution, version rejection, capability mapping, and identity preservation. Forge consults the published compatibility matrix and refuses to build combinations RVM has not validated; RVM independently refuses incompatible RVFs at load. Both gates are required — packages outlive matrix revisions.

See ADR-155 for the decision record and RVForge Integration Map for the crate-by-crate division of responsibility and roadmap.

License

Licensed under either of:

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

_{EPIC · Research Gist · pi.ruv.io Brain}

Name		Name	Last commit message	Last commit date
.cargo		.cargo
.github/workflows		.github/workflows
benches		benches
crates		crates
cuda-wasm @ 46f6f8a		cuda-wasm @ 46f6f8a
docs		docs
rudevolution @ 53af4c0		rudevolution @ 53af4c0
ruvector @ 682e1c7		ruvector @ 682e1c7
scripts		scripts
tests		tests
userguide		userguide
.gitignore		.gitignore
.gitmodules		.gitmodules
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Makefile		Makefile
README.md		README.md
rvm.ld		rvm.ld

Latest commit

History

Folders and files

Repository files navigation

RVM — The Virtual Machine Built for the Agentic Age

Agents don't fit in VMs. They need something that understands how they think.

What Agents Need vs What They Get

Why RVM?

Architecture

First-Class Kernel Objects

Crate Structure

Dependency Graph

Build

Design Constraints (ADR-132 through ADR-140)

Benchmarks (All ADR Targets Exceeded)

Implementation Status

Security Audit Results

1. Kernel-Level Graph Control Loop

2. Reconstructable Memory ("Memory Time Travel")

3. Proof-Gated Infrastructure

4. Witness-Native OS

5. Live Partition Split/Merge

6. Edge Security on 64KB RAM

Phase 1: Foundation (M0-M1) — "Can it boot and isolate?"

Phase 2: Differentiation (M2-M3) — "Can it prove and witness?"

Phase 3: Innovation (M4-M5) — "Can it think about coherence?"

Phase 4: Expansion (M6-M7) — "Can agents run on it?"

Overview

Quick Start

Backends

Architecture

Security Model

Coherence Engine Acceleration

Source

Prerequisites

Project Conventions

Quick Start (5 Minutes)

Full User Guide

Installation

Register with Claude Code

MCP Tools (6 tools)

CLI Usage

Shorthand Aliases

Governed ruv:// Context

In plain terms

The contract

RuVector Integration

RVF Package Ecosystem (22 crates)

Related ADRs & Research

RVForge Integration

Related

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Governed `ruv://` Context