English · 简体中文

Quick start · Architecture · Comparison · Roadmap

AI agents write code, install packages, open network connections and touch files nobody reviewed. Running that on a shared kernel is a bet. KumaBox gives every task its own KVM microVM with its own kernel, disk and network namespace, and gets you from an OCI image to a running sandbox in one command.

Warning

KumaBox is under active development. The CLI, metadata schema and snapshot format are not yet covered by a stability guarantee. Use disposable Linux/KVM hosts until the first stable release.

What KumaBox is

KumaBox is a microVM sandbox runtime for AI agents and untrusted workloads. It handles images, VM lifecycle, networking, snapshots and guest execution end to end, so you work with sandboxes rather than raw VMMs. Anything that can run a command can drive it today: a coding agent, an agent framework's tool call, an RL or eval harness fanning out thousands of attempts, a CI job, or you at a terminal.

Each sandbox is a real machine:

• Hardware isolation. A dedicated guest kernel behind KVM, with one Cloud Hypervisor process per VM.
• OCI in, microVM out. Digest-pinned OCI images become shared, read-only EROFS layers plus a private copy-on-write disk per VM.
• Real networking. A network namespace per VM, multiqueue TAP and CNI, with multiple NICs at creation.
• Guest execution without SSH. exec over vsock with streamed stdout and stderr, optional stdin and environment variables, and real exit codes.
• Snapshots as first-class artifacts. Save a running VM, restore or hibernate it, clone it with a fresh network identity, or export and import it as a portable archive.
• Built to be scripted. Lifecycle commands offer JSON output and inspect returns indented JSON.

Architecture

Lightweight control plane. Every kumabox call opens durable state, takes resource locks, performs the operation and records the result. Each running VM is backed by its own Cloud Hypervisor process, so one sandbox can never take down another.

Durable lifecycle. SQLite records sandbox and snapshot states. Operations stage artifacts privately, publish complete results, and retain ownership when cleanup must be retried.

Path	Purpose
/var/lib/kumabox	Images, VM records, snapshots, network leases, content
/run/kumabox	PID files, API sockets, operation locks
/var/log/kumabox	VM and runtime logs

Warm once, fork many

Agents retry, branch and explore. Pay the setup cost once: boot, install dependencies, warm caches. Capture a running snapshot of memory and disks, then clone it for every attempt. Each clone gets a private writable disk, network identity and hostname. Cloud Hypervisor v53 uses on-demand memory restore; newer compatible versions can use copy-on-write memory restore.

Quick start

You need Linux amd64 or arm64 with /dev/kvm, and root.

# 1. Build and install
git clone https://github.com/kgpp34/KumaBox.git && cd KumaBox
make build
sudo install -m 0755 bin/kumabox /usr/local/bin/kumabox
sudo install -m 0755 bin/kumabox-check /usr/local/bin/kumabox-check

# 2. Prepare the host once: Cloud Hypervisor, firmware, CNI plugins, EROFS tools
sudo kumabox-check --upgrade
sudo kumabox doctor

# 3. Pull the published guest image
sudo kumabox image pull ghcr.io/kgpp34/kumabox/ubuntu:24.04

# 4. Run a sandbox and talk to it
sudo kumabox create ghcr.io/kgpp34/kumabox/ubuntu:24.04 --name my-vm --cpus 2 --memory 1GiB --storage 10GiB
sudo kumabox start my-vm
sudo kumabox exec my-vm -- uname -a

# 5. Warm once, fork many
sudo kumabox snapshot save my-vm --name base
sudo kumabox clone base --name fresh
sudo kumabox exec fresh -- hostname
sudo kumabox snapshot export base --output base.tar

# 6. Clean up
sudo kumabox stop fresh
sudo kumabox stop my-vm
sudo kumabox rm fresh
sudo kumabox rm my-vm
sudo kumabox snapshot rm base
sudo kumabox image remove ghcr.io/kgpp34/kumabox/ubuntu:24.04

Host and guest artifacts are a matched release pair. Pin a versioned guest tag such as 24.04-v0.1.0, or an OCI digest, when reproducibility matters. sudo kumabox-check alone performs a read-only host audit.

Drive it from an agent

exec streams guest output and preserves the guest command's exit code.

import subprocess

def run_in_sandbox(vm: str, script: str) -> subprocess.CompletedProcess[str]:
    proc = subprocess.run(
        ["sudo", "kumabox", "exec", vm, "--", "sh", "-c", script],
        capture_output=True, text=True,
    )
    return proc

result = run_in_sandbox("fresh", "hostname")
print(result.returncode, result.stdout, result.stderr)

Fan out parallel attempts from one warm snapshot:

for i in $(seq 1 8); do
  sudo kumabox clone base --name try-$i &
done
wait
sudo kumabox ps

The published Ubuntu guest is intentionally minimal. To bake in your own toolchain (Python, Node, browsers), extend oci-images/ubuntu/Dockerfile, which already installs the matching kumabox-agent, kernel and initramfs.

Core commands

Area	Commands
VM lifecycle	run, create, start, stop, rm, ps, inspect
Guest access	exec, console, logs
Images	image pull, image import, image inspect, image ls, image verify, image remove
Snapshots	snapshot save, snapshot ls, snapshot inspect, snapshot export, snapshot import, snapshot rm, restore, clone, hibernate
Operations	doctor, version

kumabox <command> --help is the authoritative reference.

How KumaBox compares

E2B and CubeSandbox are excellent projects that share KumaBox's goal of giving every agent task its own kernel. KumaBox takes a different path in a few places:

• VM-native. Sandboxes are real VMs with isolated guest kernels and processes.
• Snapshots you can hold. A running snapshot is a verifiable, portable package. Export it, move it to another host, import it and clone from it.
• Layered images, shared on disk. OCI layers become read-only EROFS images shared by every VM on the host; each VM only pays for its own copy-on-write writes.
• Minimal to install. One Go binary plus Cloud Hypervisor and CNI plugins. Metadata lives in embedded SQLite, with no external database to operate.
• Correctness you can audit. Explicit state transitions, operation locks and staged artifact publication cover lifecycle, snapshot and clone paths.
• MIT licensed, on amd64 and arm64.

Related projects: Kata Containers, gVisor, Firecracker, Cloud Hypervisor and Cocoon.

Vision

Every agent action should get a disposable computer that is as cheap to fork as a git branch and as safe as a separate machine. KumaBox builds that from the bottom up: first a correct, crash-consistent runtime on every host, then a long-running service and a multi-node control plane on top of the same state machine and metadata, so a sandbox behaves the same on a laptop-sized server and across a fleet.

Roadmap

Proposed direction. Open an issue to weigh in.

• OCI to EROFS images, CNI networking, guest exec over vsock
• Running snapshots, clone, restore, hibernate, export and import
• Hotplug data disks, virtio-fs shares and VFIO PCI devices
• Daemon mode with an HTTP API
• Multi-node control plane and scheduling
• Go, Python and TypeScript SDKs
• E2B-compatible API, so existing E2B code can point at KumaBox
• MCP server, so agents can create and drive sandboxes as tools
• Warm pools and published clone-latency benchmarks
• Per-sandbox egress policy

Build and test

git clone https://github.com/kgpp34/KumaBox.git && cd KumaBox
make build
make test
go vet ./...
./bin/kumabox version --json

VM boot, guest networking and snapshot clone require a Linux/KVM host for end-to-end validation.

README graphics are generated from code. Edit the scripts in assets/readme/src/ and run python3 assets/readme/src/build.py.

Security model

• KumaBox adds a VM boundary, but the VMM, KVM, guest kernel, firmware, images and agent remain in the trusted computing base.
• Host setup changes privileged networking and system configuration. Review scripts/kumabox-check.sh before running --fix or --upgrade.
• Snapshot compatibility depends on host architecture, Cloud Hypervisor version, VM configuration and capture mode.

Report reproducible bugs and security concerns through the issue tracker. Do not attach secrets, private images or production snapshots.

License

KumaBox is available under the MIT License.