Sandbox

Rust SDK - Sandbox API reference

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