Lifecycle

Each sandbox runs as a child process of whatever application creates it. Sandbox.builder(...).create() boots a microVM, starts the guest agent inside it, and establishes a communication channel back to the host. Understanding the lifecycle is useful once you start managing long-running sandboxes, graceful shutdown, or resilient agent workflows.

States

Status	Description
Creating	The VM is booting. The kernel is loaded, the filesystem is mounted, and the guest agent is initializing (configuring network, setting up the environment).
Running	The guest agent is ready. You can call `exec`, `shell`, and `fs`.
Draining	Graceful shutdown in progress. Existing commands run to completion, but new `exec` calls are rejected. Transitions to Stopped when all commands finish.
Stopped	The VM has shut down. Sandbox configuration and state are persisted to the database and can be restarted.
Crashed	The VM exited unexpectedly (e.g., kernel panic, OOM kill).

Create a sandbox

Creating a sandbox boots the microVM, mounts the filesystem, initializes the guest agent, and waits until it’s ready to accept commands. Names must be non-empty and no longer than 128 UTF-8 bytes.

// Attached: sandbox stops when your process exits
let sb = Sandbox::builder("worker").image("python").create().await?;

// Detached: sandbox survives after your process exits
let sb = Sandbox::builder("worker")
    .image("python")
    .detached(true)
    .create()
    .await?;

// Attached: sandbox stops when your process exits
await using sb = await Sandbox.builder("worker").image("python").create();

// Detached: sandbox survives after your process exits
const detached = await Sandbox.builder("worker")
  .image("python")
  .detached(true)
  .create();

# Attached: sandbox stops when your process exits
sb = await Sandbox.create("worker", image="python")

# Detached: sandbox survives after your process exits
sb = await Sandbox.create("worker", image="python", detached=True)
await sb.detach()

// Attached: sandbox stops when your process exits
sb, err := m.CreateSandbox(ctx, "worker", m.WithImage("python"))

// Detached: sandbox survives after your process exits
detached, err := m.CreateSandbox(ctx, "worker",
    m.WithImage("python"),
    m.WithDetached(),
)

# Attached
msb create python --name worker

# Detached
msb run -d python --name worker

Stop and restart

Stopping gracefully terminates guest processes and shuts down the VM. The sandbox moves to Stopped and can be restarted later with all its configuration preserved.

sb.stop().await?;

let sb = Sandbox::start("worker").await?;

await sb.stop()

// Later, resume where you left off
const sb = await Sandbox.start("worker")

await sb.stop()

# Later, resume where you left off
sb = await Sandbox.start("worker")

_ = sb.Stop(ctx)

// Later, resume where you left off
sb, err := m.StartSandbox(ctx, "worker")

msb stop worker

# Later, resume where you left off
msb start worker

# Or stop and start in one command
msb restart worker

msb restart follows the same lifecycle semantics as msb stop followed by msb start. If the sandbox is already stopped or crashed, it starts it directly.

Configuration

Use msb modify, or the SDK modify() methods, to change an existing sandbox without recreating it. Some changes apply live, some affect future execs only, and some need a restart or the next start.

let plan = sb.modify()
    .cpus(4)
    .memory(4096)
    .apply()
    .await?;

const plan = await sandbox.modify({ cpus: 4, memory: 4096 });

plan = await sb.modify(cpus=4, memory=4096)

plan, err := sb.Modify(ctx, m.ModifyOptions{CPUs: 4, MemoryMiB: 4096})

msb modify api --cpus 4 --memory 4G

See Tuning for the change model, CPU and memory resize, labels, environment variables, secrets, and storage sizing.

Ping and touch

Use ping to check that a running sandbox’s guest agent is reachable, and touch to intentionally refresh its idle timer. Ping is a health check only: it does not count as sandbox activity and will not keep an idle sandbox alive by itself. Touch is the explicit keepalive.

let ping = sb.ping().await?;
println!("agent reachable in {:?}", ping.latency);

sb.touch().await?;

msb ping worker
msb touch worker

# Health check and then keep alive if reachable
msb ping worker --touch

Kill immediately

If a sandbox is unresponsive (e.g., stuck in a tight loop or a panic), force-kill it. The sandbox is terminated immediately with no graceful shutdown. On cloud, use a graceful stop.

sb.kill().await?;

await sb.kill()

await sb.kill()

err := sb.Kill(ctx)

msb stop --force worker

Detach

Keeps a sandbox running after the parent process exits. It becomes a background process that you can reconnect to later with Sandbox::get("worker").

sb.detach().await;

await sb.detach()

await sb.detach()

err := sb.Detach(ctx)

Request drain

Trigger a graceful shutdown that lets existing commands finish but rejects new ones. The sandbox moves to Draining and transitions to Stopped when all in-flight commands complete. This is useful for zero-downtime rotation of worker sandboxes.

sb.request_drain().await?;

await sb.requestDrain()

await sb.request_drain()

err := sb.RequestDrain(ctx)

Wait until stopped

Block until the sandbox is observed in a terminal non-running state, without triggering a stop or kill request.

let result = sb.wait_until_stopped().await?;

const result = await sb.waitUntilStopped()

result = await sb.wait_until_stopped()

result, err := sb.WaitUntilStopped(ctx)

Remove

Delete a stopped sandbox. Every local SDK entry point and msb rm uses the same deletion scope.

Sandbox::remove("worker").await?;

await Sandbox.remove("worker")

await Sandbox.remove("worker")

err := m.RemoveSandbox(ctx, "worker")

msb rm worker

For a local sandbox, removal deletes sandbox-owned state while leaving independently managed resources intact:

Removed	Kept
Sandbox record, configuration, status, labels, and run history	Cached OCI images and layers
Managed OCI writable root disk (`upper.ext4`) and its guest filesystem changes	Named volumes and their contents
Captured sandbox logs	Snapshots created from the sandbox
Runtime staging files, including generated scripts	Bind-mounted host files or directories
Root filesystem pin metadata for this sandbox	User-supplied root disk images

Removing a sandbox does not undo writes made to a named volume, bind mount, or user-supplied disk image. On cloud, removal deletes the remote sandbox resource; the local disk details above do not apply.

List and inspect

for handle in Sandbox::list().await?.sandboxes {
    println!("{}: {:?}", handle.name(), handle.status_snapshot());
}

const page = await Sandbox.list();
for (const handle of page.sandboxes) {
    console.log(`${handle.name}: ${handle.status}`);
}

const handle = await Sandbox.get("worker");
console.log(handle.status); // "running" | "stopped" | ...

for handle in (await Sandbox.list()).sandboxes:
    print(f"{handle.name}: {handle.status}")

handle = await Sandbox.get("worker")
print(handle.status)  # "running" | "stopped" | ...

page, err := m.ListSandboxes(ctx)
for _, handle := range page.Sandboxes {
    fmt.Printf("%s: %s\n", handle.Name(), handle.Status())
}

handle, err := m.GetSandbox(ctx, "worker")
fmt.Println(handle.Status()) // "running" | "stopped" | ...

msb ls
msb ps worker

Runtime process architecture

At runtime, your application talks to a host-side sandbox process, and that process relays requests to the guest agent inside the VM. The sandbox process also handles:

Graceful stop and drain signals
Cleanup when the sandbox exits
Idle detection and maximum lifetime enforcement

Logs and diagnostics

Use msb logs or the SDK logs() method to read captured output from running, stopped, or crashed sandboxes. For source semantics, boot errors, and diagnostic flows, see Logs.

Sandbox process policies

For production workloads, configure how the sandbox process handles shutdown, idle detection, and maximum lifetime.

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

await using sb = await Sandbox.builder("worker")
    .image("python")
    .maxDuration(3600)   // maximum sandbox lifetime in seconds
    .idleTimeout(300)    // auto-drain after 5 minutes of inactivity
    .create();

sb = await Sandbox.create(
    "worker",
    image="python",
    max_duration=3600,
    idle_timeout=300,
)

sb, err := m.CreateSandbox(ctx, "worker",
    m.WithImage("python"),
    m.WithMaxDuration(time.Hour),
    m.WithIdleTimeout(5*time.Minute),
)

Getting Started

Cloud

Sandboxes

Networking

Observability

Images

Troubleshooting

States

Create a sandbox

Stop and restart

Configuration

Ping and touch

Kill immediately

Detach

Request drain

Wait until stopped

Remove

List and inspect

Runtime process architecture

Logs and diagnostics

Sandbox process policies

​States

​Create a sandbox

​Stop and restart

​Configuration

​Ping and touch

​Kill immediately

​Detach

​Request drain

​Wait until stopped

​Remove

​List and inspect

​Runtime process architecture

​Logs and diagnostics

​Sandbox process policies

States

Create a sandbox

Stop and restart

Configuration

Ping and touch

Kill immediately

Detach

Request drain

Wait until stopped

Remove

List and inspect

Runtime process architecture

Logs and diagnostics

Sandbox process policies