RVM — The Virtual Machine Built for the Agentic Age

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

945 tests. 14 crates. 6 GPU backends. Zero regressions. RVM automatically detects new Claude Code releases, runs full verification with AI-powered discovery analysis, and publishes verified 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

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

Crate Structure

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-hal + rvm-partition + rvm-witness
    ├── 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-cap + rvm-proof + rvm-witness
    └── rvm-kernel ← ALL

Build

# Check (no_std by default)
cargo check

# Run all 945 tests
cargo test --workspace --lib

# Run 21 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)

Benchmarks (All ADR Targets Exceeded)

Run cargo bench for full criterion results with HTML reports.

Implementation Status

Security Audit Results

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

// 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,
};

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

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,
};

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

# 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    # 945 tests, 0 failures

# 2. Run benchmarks
cargo bench -p rvm-benches      # 11 criterion benchmarks

# 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,
};

cd userguide/mcp
npm install && npm run build

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

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

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

RuVector Integration

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

RVF Package Ecosystem (22 crates)

Related ADRs & Research

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}