Sandbox - microsandbox

See Overview for configuration examples and Lifecycle for state management.

Static methods

Sandbox::builder()

fn builder(name: impl Into<String>) -> SandboxBuilder

Create a builder for configuring a new sandbox. The builder lets you set the image, resources, volumes, networking, secrets, and other options before booting the VM. See SandboxBuilder for all available options. Parameters

Name	Type	Description
name	`impl Into<String>`	Sandbox name - must be unique among running sandboxes

Returns

Type	Description
`SandboxBuilder`	Builder for configuring the sandbox

Sandbox::get()

async fn get(name: &str) -> MicrosandboxResult<SandboxHandle>

Get a handle to an existing sandbox (running or stopped). The handle provides status, configuration, and lifecycle control without requiring a full connection to the guest agent. Parameters

Name	Type	Description
name	`&str`	Sandbox name

Returns

Type	Description
`SandboxHandle`	Handle with status and lifecycle control

Sandbox::list()

async fn list() -> MicrosandboxResult<Vec<SandboxHandle>>

List all sandboxes (running, stopped, and crashed). Returns

Type	Description
`Vec<SandboxHandle>`	All sandbox handles

Sandbox::remove()

async fn remove(name: &str) -> MicrosandboxResult<()>

Delete a stopped sandbox and all its state from disk (configuration, logs, runtime directory). Fails if the sandbox is still running - stop it first. Parameters

Name	Type	Description
name	`&str`	Sandbox name

Sandbox::start()

async fn start(name: &str) -> MicrosandboxResult<Sandbox>

Restart a previously stopped sandbox. The VM reboots using the persisted configuration. The sandbox enters attached mode - it stops when your process exits. Parameters

Name	Type	Description
name	`&str`	Name of a stopped sandbox

Returns

Type	Description
`Sandbox`	Running sandbox

Sandbox::start_detached()

async fn start_detached(name: &str) -> MicrosandboxResult<Sandbox>

Restart a stopped sandbox in detached mode. The sandbox survives after your process exits. Parameters

Name	Type	Description
name	`&str`	Name of a stopped sandbox

Returns

Type	Description
`Sandbox`	Running sandbox

Instance methods

config()

fn config(&self) -> &SandboxConfig

Access the sandbox’s full configuration. Returns

Type	Description
`&SandboxConfig`	Sandbox configuration

detach()

async fn detach(self)

Release the handle without stopping the sandbox. The sandbox continues running as a background process. Reconnect later with Sandbox::get().

drain()

async fn drain(&self) -> MicrosandboxResult<()>

Start a graceful drain. Existing commands run to completion, but new exec calls are rejected. The sandbox transitions to Stopped when all in-flight commands finish. Useful for zero-downtime rotation of worker sandboxes.

fs()

fn fs(&self) -> SandboxFs<'_>

Get a filesystem handle for reading and writing files inside the running sandbox. See Filesystem for the full API. Returns

Type	Description
`SandboxFs`	Filesystem handle

kill()

async fn kill(&self) -> MicrosandboxResult<()>

Force-terminate the sandbox immediately with SIGKILL. No graceful shutdown - use when the sandbox is unresponsive.

metrics()

async fn metrics(&self) -> MicrosandboxResult<SandboxMetrics>

Get a point-in-time snapshot of the sandbox’s resource usage: CPU, memory, disk I/O, network I/O, and uptime. Returns

Type	Description
`SandboxMetrics`	Resource metrics

metrics_stream()

fn metrics_stream(&self, interval: Duration) -> impl Stream<Item = MicrosandboxResult<SandboxMetrics>>

Stream resource metrics at a regular interval. Returns an async stream that yields a new snapshot every interval duration. Parameters

Name	Type	Description
interval	`Duration`	Time between metric snapshots

Returns

Type	Description
`impl Stream<Item = Result<SandboxMetrics>>`	Async stream of metrics

name()

fn name(&self) -> &str

Get the sandbox name. Returns

Type	Description
`&str`	Sandbox name

owns_lifecycle()

fn owns_lifecycle(&self) -> bool

Whether this handle owns the sandbox lifecycle. true in attached mode (sandbox stops when your process exits), false in detached mode. Returns

Type	Description
`bool`	`true` if attached

remove_persisted()

async fn remove_persisted(self) -> MicrosandboxResult<()>

Remove the sandbox and all its persisted state from disk.

stop()

async fn stop(&self) -> MicrosandboxResult<()>

Gracefully shut down the sandbox. Sends SIGTERM to all guest processes and waits for the VM to exit.

stop_and_wait()

async fn stop_and_wait(&self) -> MicrosandboxResult<ExitStatus>

Stop the sandbox and wait for the exit status. Returns

Type	Description
`ExitStatus`	Exit code and success flag

wait()

async fn wait(&self) -> MicrosandboxResult<ExitStatus>

Block until the sandbox exits on its own (without triggering a stop). Returns the exit status. Returns

Type	Description
`ExitStatus`	Exit code and success flag

SandboxBuilder

Builder for configuring a sandbox before creation. Obtained via Sandbox::builder(name).

cpus()

fn cpus(self, count: u8) -> Self

Set the number of virtual CPUs. This is a limit, not a reservation. Default: 1. Parameters

Name	Type	Description
count	`u8`	Number of vCPUs

create()

async fn create(self) -> MicrosandboxResult<Sandbox>

Boot the sandbox in attached mode. The sandbox stops when your process exits. Returns

Type	Description
`Sandbox`	Running sandbox

create_detached()

async fn create_detached(self) -> MicrosandboxResult<Sandbox>

Boot the sandbox in detached mode. The sandbox survives after your process exits. Returns

Type	Description
`Sandbox`	Running sandbox

disable_network()

fn disable_network(self) -> Self

Fully disable networking. No network interface is created.

entrypoint()

fn entrypoint(self, cmd: impl IntoIterator<Item = impl Into<String>>) -> Self

Override the OCI image’s entrypoint. Parameters

Name	Type	Description
cmd	`impl IntoIterator<Item = impl Into<String>>`	Entrypoint command and arguments

env()

fn env(self, key: impl Into<String>, value: impl Into<String>) -> Self

Set an environment variable visible to all commands. Can be called multiple times. Per-command env vars (via exec_with) are merged on top. Parameters

Name	Type	Description
key	`impl Into<String>`	Variable name
value	`impl Into<String>`	Variable value

hostname()

fn hostname(self, hostname: impl Into<String>) -> Self

Set the guest hostname. Parameters

Name	Type	Description
hostname	`impl Into<String>`	Hostname

idle_timeout()

fn idle_timeout(self, secs: u64) -> Self

Auto-drain the sandbox after this many seconds of inactivity (no active exec sessions). Enforced on the host side. Parameters

Name	Type	Description
secs	`u64`	Idle timeout in seconds

image()

fn image(self, image: impl IntoImage) -> Self

Set the root filesystem source. Accepts OCI image names, local directory paths, or disk image paths. The format is auto-detected. Parameters

Name	Type	Description
image	`impl IntoImage`	OCI image name, local directory path, or disk image path

image_with()

fn image_with(self, f: impl FnOnce(ImageBuilder) -> ImageBuilder) -> Self

Configure a disk image rootfs with explicit filesystem type. Use when the filesystem type can’t be auto-detected. Parameters

Name	Type	Description
f	`ImageBuilder`	Configure the disk image rootfs.

log_level()

fn log_level(self, level: LogLevel) -> Self

Override the sandbox process’s log verbosity. Parameters

Name	Type	Description
level	`LogLevel`	Log level

max_duration()

fn max_duration(self, secs: u64) -> Self

Set the maximum sandbox lifetime in seconds. When exceeded, the sandbox is drained and stopped. Enforced on the host side - the guest cannot override it. Parameters

Name	Type	Description
secs	`u64`	Maximum lifetime in seconds

memory()

fn memory(self, size: impl Into<Mebibytes>) -> Self

Set the guest memory size. Physical pages are only allocated as the guest touches them, so this is a limit, not an upfront reservation. Default: 512 MiB. Parameters

Name	Type	Description
size	`impl Into<Mebibytes>`	Memory in MiB

network()

fn network(self, f: impl FnOnce(NetworkBuilder) -> NetworkBuilder) -> Self

Configure networking. See Networking for the full builder API. Parameters

Name	Type	Description
f	`NetworkBuilder`	Configure the network.

patch()

fn patch(self, f: impl FnOnce(PatchBuilder) -> PatchBuilder) -> Self

Modify the rootfs before the VM boots. Patches go into the writable layer - the base image is untouched. Parameters

Name	Type	Description
f	`PatchBuilder`	Configure rootfs patches.

port()

fn port(self, host_port: u16, guest_port: u16) -> Self

Publish a TCP port from the sandbox to the host. Parameters

Name	Type	Description
host_port	`u16`	Port on the host
guest_port	`u16`	Port inside the sandbox

port_udp()

fn port_udp(self, host_port: u16, guest_port: u16) -> Self

Publish a UDP port. Parameters

Name	Type	Description
host_port	`u16`	Port on the host
guest_port	`u16`	Port inside the sandbox

pull_policy()

fn pull_policy(self, policy: PullPolicy) -> Self

Control when the OCI image is pulled from the registry. Parameters

Name	Type	Description
policy	`PullPolicy`	Pull behavior

registry_auth()

fn registry_auth(self, auth: RegistryAuth) -> Self

Authenticate to a private container registry. Parameters

Name	Type	Description
auth	`RegistryAuth`	Registry credentials

replace()

fn replace(self) -> Self

If a sandbox with the same name already exists, stop it, remove it, and create a fresh one. Without this, creation fails on name conflict.

script()

fn script(self, name: impl Into<String>, content: impl Into<String>) -> Self

Add a named script at /.msb/scripts/ inside the guest. Scripts are added to PATH and can be called by name via exec() or shell(). Parameters

Name	Type	Description
name	`impl Into<String>`	Script name (becomes the filename)
content	`impl Into<String>`	Script content

secret()

fn secret(self, f: impl FnOnce(SecretBuilder) -> SecretBuilder) -> Self

Add a secret with full configuration. See Secrets for the builder API. Automatically enables TLS interception. Parameters

Name	Type	Description
f	`SecretBuilder`	Configure the secret.

secret_env()

fn secret_env(self, env_var: impl Into<String>, value: impl Into<String>, allowed_host: impl Into<String>) -> Self

Shorthand for adding a header-injected secret. Equivalent to .secret(|s| s.env(env_var).value(value).allow_host(allowed_host)). Parameters

Name	Type	Description
env_var	`impl Into<String>`	Environment variable name
value	`impl Into<String>`	Secret value
allowed_host	`impl Into<String>`	Allowed destination host

shell()

fn shell(self, shell: impl Into<String>) -> Self

Set the shell used by Sandbox::shell(). Default: /bin/sh. Parameters

Name	Type	Description
shell	`impl Into<String>`	Shell path (e.g. `"/bin/bash"`)

user()

fn user(self, user: impl Into<String>) -> Self

Set the default guest user for all commands. Parameters

Name	Type	Description
user	`impl Into<String>`	User name or UID

volume()

fn volume(self, guest_path: impl Into<String>, f: impl FnOnce(MountBuilder) -> MountBuilder) -> Self

Add a volume mount. See Volumes for mount types. Parameters

Name	Type	Description
guest_path	`impl Into<String>`	Mount point inside the sandbox
f	`MountBuilder`	Configure the mount.

workdir()

fn workdir(self, path: impl Into<String>) -> Self

Set the default working directory for all commands. Parameters

Name	Type	Description
path	`impl Into<String>`	Absolute path inside the guest

Types

LogLevel

Sandbox process log verbosity.

Value	Description
`Error`	Errors only
`Warn`	Warnings and errors only
`Info`	Info and higher
`Debug`	Debug and higher
`Trace`	Most verbose - all diagnostic output

PullPolicy

Controls when the SDK fetches an OCI image from the registry.

Value	Description
`Always`	Pull the image every time, even if cached locally
`IfMissing`	Pull only if the image is not already cached. This is the default.
`Never`	Never pull; fail if the image is not cached locally

RegistryAuth

Credentials for authenticating to a private container registry.

Variant	Fields	Description
`Basic`	- `username: String` - `password: String`	Username and password authentication

SandboxConfig

The full configuration of a sandbox. Obtained via config() or built via SandboxBuilder. Contains all settings used to create the sandbox.

Field	Type	Description
cpus	`u8`	Number of virtual CPUs
env	`Vec<(String, String)>`	Environment variables
idle_timeout_secs	`Option<u64>`	Idle timeout
image	`RootfsSource`	Root filesystem source (OCI, bind, or disk image)
max_duration_secs	`Option<u64>`	Maximum lifetime
memory_mib	`u32`	Guest memory in MiB
name	`String`	Sandbox name
patches	`Vec<Patch>`	Rootfs patches
scripts	`Vec<(String, String)>`	Named scripts
shell	`Option<String>`	Shell for `shell()` calls
volumes	`Vec<VolumeMount>`	Volume mounts
workdir	`Option<String>`	Default working directory

SandboxHandle

A lightweight handle to an existing sandbox (running or stopped). Obtained via Sandbox::get() or Sandbox::list(). Provides status, configuration, and lifecycle control without an active connection to the guest agent. You cannot exec or fs on a handle - call .start() or .connect() to upgrade to a full Sandbox.

Property / Method	Type	Description
config()	`Result<SandboxConfig>`	Parsed configuration
config_json()	`&str`	Raw JSON configuration
connect()	`Result<Sandbox>`	Connect to a running sandbox
created_at()	`Option<DateTime<Utc>>`	Creation timestamp
kill()	`Result<()>`	Force terminate
metrics()	`Result<SandboxMetrics>`	Point-in-time resource metrics
name()	`&str`	Sandbox name
remove()	`Result<()>`	Delete sandbox and state
start()	`Result<Sandbox>`	Start in attached mode
start_detached()	`Result<Sandbox>`	Start in detached mode
status()	`SandboxStatus`	Current status
stop()	`Result<()>`	Graceful shutdown
updated_at()	`Option<DateTime<Utc>>`	Last update timestamp

SandboxMetrics

Point-in-time resource usage snapshot.

Field	Type	Description
cpu_percent	`f32`	CPU usage as a percentage
disk_read_bytes	`u64`	Total bytes read from disk since boot
disk_write_bytes	`u64`	Total bytes written to disk since boot
memory_bytes	`u64`	Current memory usage in bytes
memory_limit_bytes	`u64`	Memory limit in bytes
net_rx_bytes	`u64`	Total bytes received over the network since boot
net_tx_bytes	`u64`	Total bytes sent over the network since boot
timestamp	`DateTime<Utc>`	When this measurement was taken
uptime	`Duration`	Time since the sandbox was created

SandboxStatus

Value	Description
`Crashed`	VM exited unexpectedly (kernel panic, OOM, etc.)
`Draining`	Graceful shutdown in progress; existing commands finish, new ones rejected
`Running`	Guest agent is ready; `exec`, `shell`, `fs` work
`Stopped`	VM shut down; configuration persisted; can be restarted

Getting Started

Rust SDK

TypeScript SDK

​Static methods

​Sandbox::builder()

​Sandbox::get()

​Sandbox::list()

​Sandbox::remove()

​Sandbox::start()

​Sandbox::start_detached()

​Instance methods

​config()

​detach()

​drain()

​fs()

​kill()

​metrics()

​metrics_stream()

​name()

​owns_lifecycle()

​remove_persisted()

​stop()

​stop_and_wait()

​wait()

​SandboxBuilder

​cpus()

​create()

​create_detached()

​disable_network()

​entrypoint()

​env()

​hostname()

​idle_timeout()

​image()

​image_with()

​log_level()

​max_duration()

​memory()

​network()

​patch()

​port()

​port_udp()

​pull_policy()

​registry_auth()

​replace()

​script()

​secret()

​secret_env()

​shell()

​user()

​volume()

​workdir()

​Types

​LogLevel

​PullPolicy

​RegistryAuth

​SandboxConfig

​SandboxHandle

​SandboxMetrics

​SandboxStatus

Static methods

Sandbox::builder()

Sandbox::get()

Sandbox::list()

Sandbox::remove()

Sandbox::start()

Sandbox::start_detached()

Instance methods

config()

detach()

drain()

fs()

kill()

metrics()

metrics_stream()

name()

owns_lifecycle()

remove_persisted()

stop()

stop_and_wait()

wait()

SandboxBuilder

cpus()

create()

create_detached()

disable_network()

entrypoint()

env()

hostname()

idle_timeout()

image()

image_with()

log_level()

max_duration()

memory()

network()

patch()

port()

port_udp()

pull_policy()

registry_auth()

replace()

script()

secret()

secret_env()

shell()

user()

volume()

workdir()

Types

LogLevel

PullPolicy

RegistryAuth

SandboxConfig

SandboxHandle

SandboxMetrics

SandboxStatus