Skip to main content
A sandbox is a microVM: a real virtual machine with its own Linux kernel, filesystem, and network stack, running as a child process of whatever application creates it. The security boundary here is hardware virtualization, not Linux namespaces. Container escapes are a well-documented class of vulnerability; breaking out of a microVM requires exploiting the hypervisor itself, which is a fundamentally harder problem.

​
Creating a sandbox

At minimum, a sandbox needs a name and an image. Everything else has sensible defaults: 1 vCPU, 512 MiB memory, public-only networking, /bin/sh as the shell. 
let sb = Sandbox::builder("worker")
    .image("python:3.12")
    .create()
    .await?;

​
Configuration options

let sb = Sandbox::builder("worker")
    .image("python:3.12")
    .memory(1024)
    .cpus(2)
    .workdir("/app")
    .env("DEBUG", "true")
    .env("API_PORT", "8000")
    .volume("/app/src", |v| v.bind("./src").readonly())
    .volume("/data", |v| v.named("my-data"))
    .volume("/tmp/scratch", |v| v.tmpfs().size(100))
    .create()
    .await?;
OptionDefaultDescription
image—OCI image, local path, or disk image
cpus1Number of virtual CPUs
memory512Guest memory in MiB
workdir—Default working directory for commands
shell/bin/shShell used by shell() calls
env{}Environment variables
volumes[]Volume mounts (bind, named, or tmpfs)
networkpublicNetwork policy and port mappings
scripts{}Named scripts stored at /.msb/scripts/
cpus and memory are limits, not reservations. Setting memory: 512 doesn’t allocate 512 MiB upfront. Physical pages are only allocated as the guest actually touches them, so you can comfortably run many sandboxes on a single host without worrying about overcommitting.

​
Rootfs sources

microsandbox supports three ways to provide a root filesystem. The choice affects how the filesystem is assembled and what features are available.

​
OCI images

The most common option. microsandbox pulls the image and stacks its layers as a copy-on-write filesystem. Changes inside the sandbox don’t modify the base image. If two sandboxes use the same image, they share the same cached layers on disk. 
Sandbox::builder("worker").image("python:3.12").create().await?;

​
Bind mounts

Use a local directory on the host as the root filesystem directly. The guest sees the directory contents as its /. This is useful for development when you have a pre-built rootfs, or for minimal environments where you’ve assembled the filesystem yourself. 
Sandbox::builder("worker").image("./my-rootfs").create().await?;
The guest agent is automatically included in the rootfs during sandbox creation, regardless of rootfs source. You don’t need to add anything to your image or directory.

​
Disk images

Boot from a QCOW2, Raw, or VMDK disk image. Unlike OCI images (which use a copy-on-write overlay), disk images give the guest raw block device access. See Disk Images for details. 
Sandbox::builder("worker")
    .image(|i| i.disk("./alpine.qcow2").fstype("ext4"))
    .create()
    .await?;