Lifecycle

A sandbox has a simple lifecycle: create it, use it, stop it when it is idle, start it again when you need it, and remove it when you are finished. Stopping preserves the sandbox’s configuration and filesystem, while removing deletes its sandbox-owned state.

Create a sandbox

Locally, an attached SDK handle stops its sandbox when the client process exits. Cloud sandboxes are service-owned, so stop or remove them explicitly.

Creating a sandbox starts the microVM and waits until it is ready to accept commands. Give each sandbox a name so you can find and manage it later. Names must be non-empty and no longer than 128 UTF-8 bytes.

// Local attached handle: 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();

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

An attached local SDK handle normally stops its sandbox when the client process exits. See Keep a sandbox running when the sandbox should outlive that process.

Stop and start again

Stopping gracefully terminates guest processes and shuts down the VM. The sandbox moves to Stopped, but its configuration and filesystem remain available for the next start. The timeout behavior depends on the backend:

Local: stop() waits up to 10 seconds, then force-kills the sandbox if it is still running.
Cloud: stop() waits up to 6 minutes because shutdown may include creating a durable disk checkpoint. If the deadline expires, the SDK returns its typed stop-timeout error and stops waiting. It does not cancel or force-kill the accepted server-side stop, which may still complete afterward.

Use the explicit timeout option in your SDK to change how long the caller waits. On Cloud this remains an observation deadline, not a cancellation deadline. Use request_stop and wait_until_stopped separately when you want to submit the stop and manage observation yourself.

await sb.stop();

const sb = await Sandbox.start("worker");

sb.stop().await?;

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

await sb.stop()

sb = await Sandbox.start("worker")

_ = sb.Stop(ctx)

sb, err := m.StartSandbox(ctx, "worker")

sb.stop

sb = Microsandbox::Sandbox.start("worker")

msb stop worker
msb start worker

Use restart when you want to stop and start the sandbox in one operation. If it is already stopped or crashed, restart starts it directly. SDK receiver methods preserve the sandbox’s identity and configuration while replacing only the running VM instance.

CLI

msb restart worker

On microsandbox cloud, timeout expiry cannot escalate to a force kill. Force controls are local-only, and detached-start controls affect only local process ownership.

Reuse or create a named sandbox

Use connect_or_create when your application wants a sandbox with a stable name but does not know whether it already exists. This is useful for workers, development environments, and services that reconnect after the client process restarts. The operation:

Connects if the sandbox is running
Starts it if it is stopped or crashed
Creates it if the name does not exist

const sb = await Sandbox.builder("worker")
  .image("python")
  .memory(MiB(1024))
  .connectOrCreate();

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

sb = await Sandbox.connect_or_create(
    "worker",
    image="python",
    memory=1024,
)

sb, err := m.ConnectOrCreateSandbox(ctx, "worker",
    m.WithImage("python"),
    m.WithMemory(1024),
)

sb = Microsandbox::Sandbox.connect_or_create(
  "worker",
  image: "python",
  memory: 1024
)

Creation options are used only when a new sandbox is created. If worker already exists, its saved image, resources, environment, mounts, and other configuration are kept. To apply new configuration, use the local replacement workflow. On microsandbox cloud, where replacement is unavailable, remove the existing sandbox and then create it again.

If you already have a SandboxHandle, use connect_or_start to connect to that exact sandbox or start it when needed.

const handle = await Sandbox.get("worker");
const sb = await handle.connectOrStart();

let handle = Sandbox::get("worker").await?;
let sb = handle.connect_or_start().await?;

handle = await Sandbox.get("worker")
sb = await handle.connect_or_start()

handle, err := m.GetSandbox(ctx, "worker")
sb, err := handle.ConnectOrStart(ctx)

handle = Microsandbox::Sandbox.get("worker")
sb = handle.connect_or_start

Keep a sandbox running

Detach a local sandbox when it should keep running after the client process exits. You can reconnect to it later by name.

const sb = await Sandbox.builder("worker")
  .image("python")
  .detached(true)
  .create();

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

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

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

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

msb run -d python --name worker

You can also detach an existing SDK receiver with detach() (Detach in Go).

List and inspect

List sandboxes to discover what exists, or get one by name when you already know which sandbox you need.

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

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

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

handle = await Sandbox.get("worker")
print(handle.status)

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

msb ls
msb ps worker

Wait for a state

Use wait_until_stopped when another part of your application is responsible for stopping the sandbox and you only need to wait for it to finish.

const result = await sb.waitUntilStopped();

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

result = await sb.wait_until_stopped()

result, err := sb.WaitUntilStopped(ctx)

result = sb.wait_until_stopped

Use wait_for_status (waitForStatus in TypeScript and WaitForStatus in Go) when you need to wait for a specific lifecycle state. It has no built-in timeout, so use the language’s normal timeout or cancellation primitive around it.

Change configuration

Use msb modify, or the SDK modify() methods, to change an existing sandbox without recreating it. Some changes apply immediately, some affect future commands, and some take effect after a restart.

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

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

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 Live Modify for the change model, CPU and memory resize, labels, environment variables, secrets, and storage sizing.

Check health and keep a sandbox active

Ping and touch are currently available only for local sandboxes.

Use ping to check that a running sandbox’s guest agent is reachable. A ping is only a health check and does not reset the idle timer. Use touch when you intentionally want to keep the sandbox active.

const ping = await sb.ping();
console.log(`agent reachable in ${ping.latencyMs.toFixed(1)} ms`);

await sb.touch();

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

sb.touch().await?;

msb ping worker
msb touch worker

# Check health, then keep the sandbox active if it is reachable
msb ping worker --touch

Drain before stopping

Draining is currently available only for local sandboxes. Use a graceful stop on microsandbox cloud.

Use a drain when existing commands should finish but new commands should be rejected. The sandbox moves to Draining, waits for in-flight commands, and then stops. This is useful when rotating worker sandboxes without interrupting active jobs.

await sb.requestDrain();

sb.request_drain().await?;

await sb.request_drain()

err := sb.RequestDrain(ctx)

Stop an unresponsive sandbox

Force kill is currently available only for local sandboxes. Use a graceful stop on microsandbox cloud.

If a sandbox does not respond to a graceful stop, force-kill it. This ends the VM immediately without waiting for guest processes to shut down.

await sb.kill();

sb.kill().await?;

await sb.kill()

err := sb.Kill(ctx)

msb stop --force worker

Destroy or remove

Use destroy when you have an SDK receiver and want to stop and remove that exact sandbox in one operation. It requests a graceful stop by default, escalates after the configured timeout, and refuses to act on a replacement that reused the name.

await sb.destroy();

sb.destroy().await?;

await sb.destroy()

err := sb.Destroy(ctx)

sb.destroy

Use remove when the sandbox is already stopped and you want to delete it by name.

await Sandbox.remove("worker");

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

await Sandbox.remove("worker")

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

Microsandbox::Sandbox.remove("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.

Automatic lifecycle policies

For production workloads, configure a maximum lifetime or idle timeout so sandboxes shut down automatically.

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

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

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),
)

Lifecycle states

Most applications only need to distinguish between Running and Stopped. The complete set is useful for status displays and recovery logic.

Status	Meaning
Created	Configuration has been saved, but the sandbox has not started yet.
Starting	The VM and guest agent are starting. Commands are not ready yet.
Running	The sandbox is ready for `exec`, `shell`, and filesystem operations.
Draining	Existing commands may finish, but new commands are rejected. The sandbox stops when the drain completes.
Stopped	The VM is off. Configuration and sandbox state are preserved for a later start.
Crashed	The VM exited unexpectedly and can be started again.

Some backends can also report Paused. Resume is not currently exposed through the SDKs, so start and connect operations do not treat a paused sandbox as stopped.

Names, handles, and concurrent callers

A sandbox name finds the current sandbox saved under that name. A Sandbox or SandboxHandle also carries an opaque stable ID (ID() in Go) for one exact saved sandbox. Treat the ID as an opaque value and use it for logging, correlation, and equality checks. If worker is removed and a different sandbox is later created with the same name, an old receiver will not act on the replacement. Lifecycle methods return SandboxReplaced or the language’s typed equivalent when they can detect this situation; an ID-addressed cloud request may instead report that the old resource no longer exists. Concurrent callers are safe to use with the named lifecycle APIs. create remains strict, so only one same-name creation succeeds. connect_or_create may reuse the sandbox created by another caller, and connect_or_start remains attached to the exact identity held by its handle. Calls that encounter Starting wait for the sandbox to become ready instead of launching a second runtime.

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.

Reference

For exact lifecycle APIs, see TypeScript, Rust, Python, or Go. For lifecycle commands and the REST surface, see Sandbox commands and the Cloud API.

Getting Started

Sandboxes

Networking

Operations

Troubleshooting

Create a sandbox

Stop and start again

Reuse or create a named sandbox

Keep a sandbox running

List and inspect

Wait for a state

Change configuration

Check health and keep a sandbox active

Drain before stopping

Stop an unresponsive sandbox

Destroy or remove

Automatic lifecycle policies

Lifecycle states

Names, handles, and concurrent callers

Logs and diagnostics

Reference

​Create a sandbox

​Stop and start again

​Reuse or create a named sandbox

​Keep a sandbox running

​List and inspect

​Wait for a state

​Change configuration

​Check health and keep a sandbox active

​Drain before stopping

​Stop an unresponsive sandbox

​Destroy or remove

​Automatic lifecycle policies

​Lifecycle states

​Names, handles, and concurrent callers

​Logs and diagnostics

​Reference

Create a sandbox

Stop and start again

Reuse or create a named sandbox

Keep a sandbox running

List and inspect

Wait for a state

Change configuration

Check health and keep a sandbox active

Drain before stopping

Stop an unresponsive sandbox

Destroy or remove

Automatic lifecycle policies

Lifecycle states

Names, handles, and concurrent callers

Logs and diagnostics

Reference