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.

await using sb = await Sandbox.builder("worker")
    .image("python")
    .create();

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

sb = await Sandbox.create("worker", image="python")

sb, err := m.CreateSandbox(ctx, "worker", m.WithImage("python"))

sb = Microsandbox::Sandbox.create("worker", image: "python")

msb create python --name worker

Sandbox names must be non-empty and no longer than 128 UTF-8 bytes.

Common configuration

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();

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?;

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
`thp`	`madvise`	Guest transparent huge-page policy selected at boot
`guest_clock`	`sync`	Follow host time (`sync`) or stop host clock updates after boot (`off`). Local Rust SDK and CLI only
`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 Live Modify 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 for the full OCI and disk image model.

Naming conflicts

Creating a sandbox fails if another sandbox already has the same name. Use connect_or_create when you want to reuse the current persisted identity and its configuration. Use replace when you explicitly want a fresh sandbox with that name:

await using sb = await Sandbox.builder("worker")
    .image("python")
    .replace()
    .create();

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

sb = await Sandbox.create("worker", image="python", replace=True)

sb, err := m.CreateSandbox(ctx, "worker",
    m.WithImage("python"),
    m.WithReplace(),
)

sb = Microsandbox::Sandbox.create("worker", image: "python", replace: true)

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.

Reference

For the complete sandbox API, see TypeScript, Rust, Python, or Go. For terminal and REST workflows, see Sandbox commands and the Cloud API.

Where to go next

Lifecycle: start, stop, detach, wait, and remove sandboxes
Commands: run commands and stream output
Filesystem: read, write, and transfer files
Secrets: inject credentials without exposing values
Images: choose OCI, directory, or disk-image roots
Volumes: persist or share data
SSH: connect with SSH and SFTP clients
Snapshots: capture and reuse writable sandbox state
Live Modify: change settings after create
Labels: organize, select, and attribute sandboxes
Logs: inspect workload and runtime output
Metrics: monitor sandbox resource usage
Bootstrap: prepare scripts, patches, and PID 1
Networking: control egress, ingress, DNS, and ports

Getting Started

Sandboxes

Networking

Deep dive

Troubleshooting

Create a sandbox

Common configuration

Image sources

Naming conflicts

Reference

Where to go next

​Create a sandbox

​Common configuration

​Image sources

​Naming conflicts

​Reference

​Where to go next

Create a sandbox

Common configuration

Image sources

Naming conflicts

Reference

Where to go next