Overview

A sandbox is a microVM with its own Linux kernel, filesystem, and network stack. Your application or the msb CLI starts it as a child process on your machine or on microsandbox cloud, 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.

Create a sandbox

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.

let sb = Sandbox::builder("worker")
    .image("python")
    .create()
    .await?;

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.

Common configuration

let sb = Sandbox::builder("worker")
    .image("python")
    .memory(1024)
    .cpus(2)
    .env("DEBUG", "true")
    .label("user.id", "alice")
    .volume("/tmp/scratch", |v| v.tmpfs().size(100))
    .create()
    .await?;

await using sb = await Sandbox.builder("worker")
    .image("python")
    .memory(1024)
    .cpus(2)
    .env("DEBUG", "true")
    .label("user.id", "alice")
    .volume("/tmp/scratch", (m) => m.tmpfs().size(100))
    .create();

sb = await Sandbox.create(
    "worker",
    image="python",
    memory=1024,
    cpus=2,
    env={"DEBUG": "true"},
    labels={"user.id": "alice"},
    volumes={"/tmp/scratch": Volume.tmpfs(size_mib=100)},
)

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{
        "/tmp/scratch": m.Mount.Tmpfs(m.TmpfsOptions{SizeMiB: 100}),
    }),
)

msb create python --name worker \
  -c 2 \
  -m 1G \
  -e DEBUG=true \
  --label user.id=alice \
  --tmpfs /tmp/scratch:100

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.

cpus and memory are limits, not reservations. Guest memory is allocated as the VM touches pages.

Image sources

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.

Naming conflicts

Creating a sandbox fails if another sandbox already has the same name. Use replace when you want a fresh sandbox with that name:

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.

Where to go next

Lifecycle: start, stop, detach, wait, and remove sandboxes
Tuning: change settings after create
Labels: organize, select, and attribute sandboxes
Secrets: inject credentials without exposing values
Bootstrap: prepare scripts, patches, and PID 1
Commands: run commands and stream output
Volumes: persist or share data
Networking: control egress, ingress, DNS, and ports
SDK reference: per-language API details

Getting Started

Cloud

Sandboxes

Networking

Observability

Images

Troubleshooting

Create a sandbox

Common configuration

Image sources

Naming conflicts

Where to go next

​Create a sandbox

​Common configuration

​Image sources

​Naming conflicts

​Where to go next

Create a sandbox

Common configuration

Image sources

Naming conflicts

Where to go next