docs/sandboxes/overview.mdx
A sandbox is a local microVM with its own Linux kernel, filesystem, and network stack. Your application or the msb CLI starts it as a child process, then talks to the guest agent to run commands, move files, and control lifecycle.
The security boundary is hardware virtualization, not Linux namespaces. That makes sandboxes a good fit for untrusted workloads: user-submitted code, AI agent actions, plugins, dependency installs, CI jobs, scrapers, and tools that should not inherit the host process's full privileges.
At minimum, a sandbox needs a name and an image. Everything else has defaults: 1 vCPU, 512 MiB memory, public-only networking, and /bin/sh as the default shell.
await using sb = await Sandbox.builder("worker")
.image("python")
.create();
sb = await Sandbox.create("worker", image="python")
sb, err := m.CreateSandbox(ctx, "worker", m.WithImage("python"))
msb create python --name worker
Sandbox names must be non-empty and no longer than 128 UTF-8 bytes.
await using sb = await Sandbox.builder("worker")
.image("python")
.memory(1024)
.cpus(2)
.env("DEBUG", "true")
.label("user.id", "alice")
.volume("/app/src", (m) => m.bind("./src").readonly())
.create();
sb = await Sandbox.create(
"worker",
image="python",
memory=1024,
cpus=2,
env={"DEBUG": "true"},
labels={"user.id": "alice"},
volumes={"/app/src": Volume.bind("./src", readonly=True)},
)
sb, err := m.CreateSandbox(ctx, "worker",
m.WithImage("python"),
m.WithMemory(1024),
m.WithCPUs(2),
m.WithEnv(map[string]string{"DEBUG": "true"}),
m.WithLabels(map[string]string{"user.id": "alice"}),
m.WithMounts(map[string]m.MountConfig{
"/app/src": m.Mount.Bind("./src", m.MountOptions{Readonly: true}),
}),
)
msb create python --name worker \
-c 2 \
-m 1G \
-e DEBUG=true \
--label user.id=alice \
-v ./src:/app/src:ro
| Option | Default | Description |
|---|---|---|
image | required | OCI image, local rootfs path, or disk image |
cpus | 1 | Virtual CPU limit |
max_cpus | same as cpus | Boot-time maximum possible virtual CPUs |
memory | 512 | Guest memory limit in MiB |
max_memory | same as memory | Boot-time maximum hotpluggable memory in MiB |
workdir | image default | Default working directory for commands |
shell | /bin/sh | Shell used by shell() calls |
env | empty | Environment variables |
labels | empty | Key/value metadata for metric attribution |
volumes | empty | Bind, named, tmpfs, or disk-image mounts |
network | public-only | Network policy and published ports |
scripts | empty | Named scripts mounted at /.msb/scripts/ |
max_cpus and max_memory reserve live resize headroom. They default to the
starting cpus and memory values, so set them higher when a sandbox may need
to grow later. See Tuning for the full change
model.
Labels are arbitrary key=value metadata attached to a sandbox. They can be set
at create time or changed while the sandbox is running, and they also select
sandboxes in bulk. See Labels for naming guidance, bulk
actions, metric attribution, and OCI image labels.
Most sandboxes start from an OCI image:
msb create python --name worker
You can also use a host directory as the root filesystem:
msb create ./my-rootfs --name worker
Or boot from a disk image:
msb create ./alpine.qcow2 --name worker
OCI images use a copy-on-write overlay so sandboxes can share cached base layers. Disk images are attached as block devices, so each sandbox should use its own disk image copy unless the image format handles its own snapshotting.
See Images and Disk Images for the full image model.
Creating a sandbox fails if another sandbox already has the same name. Use replace when you want a fresh sandbox with that name:
<CodeGroup> ```rust Rust let sb = Sandbox::builder("worker") .image("python") .replace() .create() .await?; ```await using sb = await Sandbox.builder("worker")
.image("python")
.replace()
.create();
sb = await Sandbox.create("worker", image="python", replace=True)
sb, err := m.CreateSandbox(ctx, "worker",
m.WithImage("python"),
m.WithReplace(),
)
msb create --replace python --name worker
When replacing a running sandbox, microsandbox attempts graceful shutdown before force-killing it. Use replace_with_timeout or --replace-with-timeout when the workload needs a longer grace period.