cersei-vms

cersei-vms is the 15th crate in the workspace. It introduces a pluggable sandbox runtime layer so Cersei agents don't have to execute shell commands and edit files directly on the host machine. The same crate provides three cross-sandbox primitives — Volume, Mailbox, KvStore — that let multiple parallel agents communicate and share state safely.

Why a sandbox layer

Without one, Cersei has three structural weaknesses:

1. Unsafe for untrusted code. A model that emits shellcode runs it with the user's full privileges.
2. No parallel-agent isolation. When cersei-agent::delegate spawns N parallel sub-agents, they share one filesystem and process namespace — they trample each other on writes, cd, env vars.
3. No cross-agent comms primitive. There's send_message between coordinator/worker, but no shared state, no shared volumes, no message bus between independent agents.

cersei-vms fixes all three.

At a glance

60-second example

use cersei::prelude::*;
use cersei::vms::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Spin up a local-process runtime (use DockerRuntime in prod).
    let runtime = LocalProcessRuntime::new()?;

    // 2. Allocate a sandbox.
    let sb = runtime
        .create(SandboxOpts::image("cersei/sandbox-base:latest"))
        .await?;

    // 3. Run a command inside it.
    let out = sb
        .commands()
        .run(RunRequest::new("echo hello && pwd"))
        .await?;
    println!("{} (exit {})", out.stdout.trim(), out.exit_code);

    // 4. Read/write files inside it.
    sb.filesystem().write("/work/note.txt", b"first-party").await?;
    let bytes = sb.filesystem().read("/work/note.txt").await?;
    assert_eq!(&bytes[..], b"first-party");

    // 5. Snapshot mid-run, kill, restore later — state survives.
    let snap = sb.snapshot().await?;
    sb.kill().await?;
    let restored = runtime.restore(&snap).await?;
    let again = restored.filesystem().read("/work/note.txt").await?;
    assert_eq!(&again[..], b"first-party");
    Ok(())
}

Architecture

Multiple sandboxes attach to one host broker for Volume / Mailbox / KvStore. Sandbox-to-sandbox messages always go through the host — there is no requirement for sandboxes to network to each other directly, which keeps the security model simple.

Where it sits in the workspace

What ships in 0.1.9 (Phase 1)

• SandboxRuntime, Sandbox, Commands, Filesystem traits
• LocalProcessRuntime and DockerRuntime backends
• Volume, Mailbox, KvStore primitives
• Snapshot/restore for both backends
• cersei-envd binary + reference Dockerfile for cersei/sandbox-base
• Transparent routing in BashTool + new vm_tools module
• cersei::vms facade re-export
• 9 passing integration tests covering all primitives + snapshots

What's coming in 0.1.10 (Phase 2)

• AgentBuilder::with_sandbox(handle) / with_sandbox_allocator(...) — no more manual extension stuffing.
• cersei-agent::delegate per-task allocator — every parallel worker lands in its own sandbox.
• abstract CLI: --sandbox <local|docker> flag and /vm slash command.
• FirecrackerRuntime (Linux microVMs), E2bRuntime (remote E2B), VercelSandboxRuntime.
• docker pause / unpause, incremental snapshots, snapshot GC.

Reading order

1. This page — concepts and architecture.
2. VMs API — every public type, method, and option, organised by crate module.
3. VMs Cookbook — end-to-end recipes: parallel agents over a shared volume, mailbox-driven coordination, snapshot-driven retries.