Sandbox

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

Returns

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

Returns

Sandbox::list()

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

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

Returns

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

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

Returns

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

Returns

Instance methods

config()

fn config(&self) -> &SandboxConfig

Access the sandbox's full configuration.

Returns

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

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

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

Returns

logs()

fn logs(&self, opts: &LogOptions) -> MicrosandboxResult<Vec<LogEntry>>

Read captured output from the sandbox's exec.log. Backed by an on-disk JSON Lines file the runtime writes via the relay tap. Works on running and stopped sandboxes alike — there is no protocol traffic. The same method is available on SandboxHandle for callers that don't want to start the sandbox first.

The default sources are Stdout, Stderr, and Output (PTY-merged). Pass LogSource::System to also include synthetic lifecycle markers and runtime/kernel diagnostic lines.

use microsandbox::sandbox::{LogOptions, LogSource, Sandbox};

let handle = Sandbox::get("web").await?;

// Default — all user-program output, regardless of pipe/pty mode
let entries = handle.logs(&LogOptions::default())?;

for e in entries {
    let source = match e.source {
        LogSource::Stdout => "OUT",
        LogSource::Stderr => "ERR",
        LogSource::Output => "PTY",
        LogSource::System => "SYS",
    };
    println!(
        "[{}] {} {:?}: {}",
        e.timestamp.to_rfc3339(),
        source,
        e.session_id,
        String::from_utf8_lossy(&e.data).trim_end()
    );
}

// Filtered: last 50 entries from the past hour, including system lines
let recent = handle.logs(&LogOptions {
    tail: Some(50),
    since: Some(chrono::Utc::now() - chrono::Duration::hours(1)),
    sources: vec![
        LogSource::Stdout,
        LogSource::Stderr,
        LogSource::Output,
        LogSource::System,
    ],
    ..Default::default()
})?;

logs() is synchronous because it's a pure file read.

Parameters

Returns

name()

fn name(&self) -> &str

Get the sandbox name.

Returns

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

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

wait()

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

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

Returns

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

create()

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

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

Returns

create_detached()

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

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

Returns

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

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

hostname()

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

Set the guest hostname.

Parameters

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.

init()

fn init(self, cmd: impl Into<PathBuf>) -> Self

Hand off PID 1 inside the guest to cmd after agentd finishes its boot-time setup. The agent forks; the parent execs the init and becomes PID 1, the agent continues as a child process. See Init handoff for image picks, shutdown semantics, and tradeoffs.

cmd is either an absolute path inside the guest rootfs or the literal "auto" (probes /sbin/init, /lib/systemd/systemd, /usr/lib/systemd/systemd). For init binaries that take argv or extra env (rare), use init_with.

Parameters

let sb = Sandbox::builder("worker")
    .image("jrei/systemd-debian:12")
    .init("auto")
    .create()
    .await?;

init_with()

fn init_with(
    self,
    cmd: impl Into<PathBuf>,
    f: impl FnOnce(InitOptionsBuilder) -> InitOptionsBuilder,
) -> Self

Like init, but with a closure-builder for argv and env vars. Mirrors exec_with in shape.

The builder exposes arg, args, env, and envs.

Parameters

let sb = Sandbox::builder("worker")
    .image("jrei/systemd-debian:12")
    .init_with("/lib/systemd/systemd", |i| i
        .args(["--unit=multi-user.target"])
        .env("container", "microsandbox"))
    .create()
    .await?;

Calling init or init_with more than once overwrites — different from env, which appends. The init is one-shot pre-boot.

Parameters

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

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

log_level()

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

Override the sandbox process's log verbosity.

Parameters

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

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

network()

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

Configure networking. See Networking for the full builder API.

Parameters

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

port()

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

Publish a TCP port from the sandbox to the host.

Parameters

port_udp()

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

Publish a UDP port.

Parameters

pull_policy()

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

Control when the OCI image is pulled from the registry.

Parameters

registry_auth()

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

Authenticate to a private container registry.

Parameters

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

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

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

shell()

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

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

Parameters

user()

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

Set the default guest user for all commands.

Parameters

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

workdir()

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

Set the default working directory for all commands.

Parameters

Types

LogEntry

A single captured log entry returned by logs().

LogLevel

Sandbox process log verbosity.

LogOptions

Filters passed to logs(). All fields optional. LogOptions::default() returns everything for the default sources (Stdout + Stderr + Output).

LogSource

Tag indicating where a captured log entry came from.

PullPolicy

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

RegistryAuth

Credentials for authenticating to a private container registry.

• 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.

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.

SandboxMetrics

Point-in-time resource usage snapshot.

SandboxStatus