rust-nano-vm

A single-binary Rust microVM for AI-agent code execution.

Rust 1.94+ Linux + macOS x86_64 + aarch64 Apache-2.0 / MIT

Star on GitHub Install Read the trick Regulated deployments

~12 mscold start, p50 (snapshot → fork)

~0.5 MiBprivate memory per fork (Pss, N=50)

>90%shared via MAP_PRIVATE CoW

~30 000concurrent forks per 16 GiB host*

* For minimal-footprint guests. Measured on an i5 laptop, 8 GiB RAM, vanilla Linux + KVM. Reproduce with cargo run -p bench --features kvm --release -- --count 100 --alive 50.

The problem

Every AI coding agent — Claude Code, Cursor, Devin, OpenHands, aider, SWE-bench-style evals — needs to run generated code somewhere safe and cheaply. Today the options force a bad trade-off:

• E2B — 150–400 ms cold start, closed managed service.
• Firecracker directly — fast (~125 ms restore) but a general-purpose serverless VMM; no native fork; bring your own control plane, jailer, agent, and snapshot fan-out.
• Containers — weak isolation; namespaces share a kernel with the attacker's untrusted code.

The shape of the solution

A single-binary Rust VMM + guest agent + REST control plane, snapshot-first, with snapshot → fork as a first-class primitive. An eval pipeline can spawn 1000 variants of a base image at ~12 ms each. The kernel keeps the shared 6–7 MiB golden image actually shared across all of them via MAP_PRIVATE copy-on-write.

Comparison

Axis	E2B	Firecracker	rust-nano-vm
Cold start (p50)	150–400 ms	~125 ms	~12 ms
Snapshot → fork	service-side	not native	first-class
Per-fork memory	opaque	~5 MiB+ RSS	~0.5 MiB Pss
Distribution	SaaS only	VMM + jailer + your code	one binary
License	proprietary	Apache-2.0	Apache-2.0 / MIT
Control plane	included (proprietary)	bring your own	included (axum)

What's special

1. Cold start is a mmap away. Fork doesn't re-boot a kernel — it maps the snapshot's RAM file MAP_PRIVATE and lets the kernel serve the read-only golden pages to every child. Read the write-up →
2. Faithful KVM snapshot/restore in <1000 lines. Full vCPU + LAPIC + FPU + MSR + IRQCHIP + PIT capture, JSON-serialized via kvm-bindings's serde feature. Read the write-up →
3. Honest accounting. The bench reports Pss (proportional set size, from /proc/self/smaps_rollup), not RSS. RSS double-counts shared pages and overstates fork cost by 5–10×.
4. A production-shaped control plane. Bearer-token auth, per-token token-bucket quota on the expensive /fork route, per-caller usage metering, Prometheus /metrics endpoint. ~330 lines of axum, no magic.

Install & try

One-command demo (any platform with Rust)

Boots an in-process control plane on a free port, drives the full create → snapshot → fork lifecycle, prints a report. Works identically on Linux, macOS, and Windows. Only prerequisite is a Rust toolchain (rustup).

git clone https://github.com/ip888/Rust-nano-vm.git
cd Rust-nano-vm
cargo run -p control-plane --example demo --release

To see the wire calls instead, see the "Driving the REST API by hand" section of the README.

Prebuilt binaries (no Rust toolchain needed on the host)

Every tagged release ships native-built binaries for three targets, each with a sidecar SHA256 you can verify before deployment. Browse all assets on the latest release page.

Target	Use it on	Real KVM backend
x86_64-unknown-linux-gnu	Generic Linux servers, AWS x86 instances, dev laptops	✅
aarch64-unknown-linux-gnu	AWS Graviton, Ampere Altra, Oracle A1, Linux on RPi-class	planned
aarch64-apple-darwin	Apple Silicon Macs (M1/M2/M3/M4) for dev	n/a (macOS has no /dev/kvm)

Use cases this is built for

• AI agent eval pipelines. Fan out 1000 variants of a base image to run a benchmark in parallel; throw them away in milliseconds. See 12 ms fan-out for AI-agent eval pipelines → for the worked numbers vs containers.
• Self-hosted code interpreters. Drop-in OSS alternative to E2B for teams that need on-prem (healthcare, finance, defense, EU data residency). See Running AI agents in regulated environments → for the audit-narrative angle.
• CI for untrusted PRs. Stronger isolation than a container, faster than a fresh VM, with a REST API your runner can drive.
• Per-user sandboxes for AI products. One snapshot per language toolchain, forked per request.