Skip to main content
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

StatusDescription
CreatingThe VM is booting. The kernel is loaded, the filesystem is mounted, and the guest agent is initializing (configuring network, setting up the environment).
RunningThe guest agent is ready. You can call exec, shell, and fs.
DrainingGraceful shutdown in progress. Existing commands run to completion, but new exec calls are rejected. Transitions to Stopped when all commands finish.
StoppedThe VM has shut down. Sandbox configuration and state are persisted to the database and can be restarted.
CrashedThe 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?;

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

​
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. 
sb.kill().await?;

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

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

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

​
Remove

Delete a stopped sandbox and its associated state from disk. 
Sandbox::remove("worker").await?;

​
List and inspect

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

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