--- title: Sandbox description: Rust SDK - Sandbox API reference --- Create and control a microVM sandbox: boot it from an image, run commands, stream logs and metrics, then shut it down. See [Overview](/sandboxes/overview) for configuration examples and [Lifecycle](/sandboxes/lifecycle) for state management.

Static6

Sandbox::builder()configure a new sandbox Sandbox::get()handle to an existing one Sandbox::list()all sandboxes Sandbox::start()restart a stopped one Sandbox::start_detached()restart detached Sandbox::remove()delete a stopped one

Instance16

sb.exec()run a command sb.shell()interactive shell sb.fs()read / write files sb.logs()captured output sb.metrics()resource snapshot sb.metrics_stream()stream metrics sb.stop()graceful shutdown sb.kill()force terminate sb.drain()graceful drain sb.detach()release, keep running sb.wait()block until it exits sb.stop_and_wait()stop, then await exit sb.config()full configuration sb.name()sandbox name sb.owns_lifecycle()attached vs detached sb.remove_persisted()delete persisted state

Builder · SandboxBuilder32

.image() .memory() .cpus() .port() .volume() .env() .secret() .network() .init() .patch() .create() .build() + 20 more in the Builder section

Types

SandboxConfig SandboxHandle SandboxMetrics SandboxStatus LogEntry LogOptions LogSource LogLevel PullPolicy RegistryAuth ExitStatus PatchBuilder

Typical flow

```rust use microsandbox::Sandbox; let sb = Sandbox::builder("api") // 1. configure .image("python") .memory(1024) .create() // 2. boot the microVM .await?; let out = sb.exec("python", ["-V"]).await?; // 3. run println!("{}", out.stdout()?); sb.stop().await?; // 4. shut down ``` ## Static methods --- #### Sandbox::builder()
static
```rust fn builder(name: impl Into) -> 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. Sandbox names must be non-empty and no longer than 128 UTF-8 bytes. See [`SandboxBuilder`](#sandboxbuilder) for all available options.

Parameters

nameimpl Into<String>
Sandbox name - must be unique and no longer than 128 UTF-8 bytes.

Returns

SandboxBuilder
Builder for configuring the sandbox.
```rust let sb = Sandbox::builder("api") .image("python") .create() .await?; ``` --- #### Sandbox::get()
staticasync
```rust async fn get(name: &str) -> MicrosandboxResult ``` 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&str
Sandbox name, up to 128 UTF-8 bytes.

Returns

SandboxHandle
Handle with status and lifecycle control.
```rust let handle = Sandbox::get("api").await?; println!("{:?}", handle.status()); ``` --- #### Sandbox::list()
staticasync
```rust async fn list() -> MicrosandboxResult> ``` List all sandboxes (running, stopped, and crashed).

Returns

All sandbox handles.
```rust for h in Sandbox::list().await? { println!("{} — {:?}", h.name(), h.status()); } ``` --- #### Sandbox::remove()
staticasync
```rust 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&str
Sandbox name, up to 128 UTF-8 bytes.
```rust Sandbox::remove("api").await?; ``` --- #### Sandbox::start()
staticasync
```rust async fn start(name: &str) -> MicrosandboxResult ``` 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&str
Name of a stopped sandbox, up to 128 UTF-8 bytes.

Returns

Running sandbox.
```rust let sb = Sandbox::start("api").await?; ``` --- #### Sandbox::start_detached()
staticasync
```rust async fn start_detached(name: &str) -> MicrosandboxResult ``` Restart a stopped sandbox in detached mode. The sandbox survives after your process exits.

Parameters

name&str
Name of a stopped sandbox, up to 128 UTF-8 bytes.

Returns

Running sandbox.
--- ## Instance methods --- #### sb.config()
instance
```rust fn config(&self) -> &SandboxConfig ``` Access the sandbox's full configuration.

Returns

Sandbox configuration.
```rust println!("{} MiB", sb.config().memory_mib); ``` --- #### sb.detach()
instanceasync
```rust async fn detach(self) ``` Release the handle without stopping the sandbox. The sandbox continues running as a background process. Reconnect later with [`Sandbox::get()`](#sandboxget). ```rust sb.detach().await; // keeps running in the background ``` --- #### sb.drain()
instanceasync
```rust 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. ```rust sb.drain().await?; ``` --- #### sb.fs()
instance
```rust fn fs(&self) -> SandboxFs<'_> ``` Get a filesystem handle for reading and writing files inside the running sandbox. See [Filesystem](/sdk/rust/filesystem) for API details.

Returns

Filesystem handle.
```rust sb.fs().write("/tmp/hello.txt", "hi").await?; ``` --- #### sb.kill()
instanceasync
```rust async fn kill(&self) -> MicrosandboxResult<()> ``` Force-terminate the sandbox immediately with SIGKILL. No graceful shutdown — use when the sandbox is unresponsive. Pending writes that the workload hasn't `fsync`'d may be lost, same durability semantics as a sudden power loss on a physical machine. Prefer [`stop()`](#sb-stop) for graceful shutdown that gives the workload a chance to flush. ```rust sb.kill().await?; // SIGKILL, no graceful shutdown ``` --- #### sb.metrics()
instanceasync
```rust async fn metrics(&self) -> MicrosandboxResult ``` Get a point-in-time snapshot of the sandbox's resource usage: CPU, memory, disk I/O, network I/O, optional upper disk usage, and uptime.

Returns

Resource metrics.
```rust let m = sb.metrics().await?; println!("cpu {:.1}% · mem {} MiB", m.cpu_percent, m.memory_bytes / 1_048_576); ``` --- #### sb.metrics_stream()
instance
```rust fn metrics_stream(&self, interval: Duration) -> impl Stream> ``` Stream resource metrics at a regular interval. Returns an async stream that yields a new snapshot every `interval` duration.

Parameters

intervalDuration
Time between metric snapshots.

Returns

Async stream yielding a snapshot each interval.
```rust use futures::StreamExt; let mut stream = sb.metrics_stream(Duration::from_secs(1)); while let Some(snapshot) = stream.next().await { println!("{:.1}%", snapshot?.cpu_percent); } ``` --- #### sb.logs()
instance
```rust fn logs(&self, opts: &LogOptions) -> MicrosandboxResult> ``` 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`](#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. `logs()` is **synchronous** because it's a pure file read.

Parameters

Filters: tail, since, until, sources. LogOptions::default() returns everything for the default sources.

Returns

Matching entries in chronological order.
```rust 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() })?; ``` --- #### sb.name()
instance
```rust fn name(&self) -> &str ``` Get the sandbox name.

Returns

&str
Sandbox name, up to 128 UTF-8 bytes.
--- #### sb.owns_lifecycle()
instance
```rust 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

bool
true if attached.
--- #### sb.remove_persisted()
instanceasync
```rust async fn remove_persisted(&self) -> MicrosandboxResult<()> ``` Remove the sandbox and all its persisted state from disk. ```rust sb.remove_persisted().await?; ``` --- #### sb.stop()
instanceasync
```rust async fn stop(&self) -> MicrosandboxResult<()> ``` Gracefully shut down the sandbox. Lets the sandbox finish writing any pending data to disk before it exits, so files written inside the sandbox aren't lost across a later restart. Waits up to ten seconds for a clean exit; if the sandbox is still running after that, it is force-killed. ```rust sb.stop().await?; ``` --- #### sb.stop_and_wait()
instanceasync
```rust async fn stop_and_wait(&self) -> MicrosandboxResult ``` Stop the sandbox and wait for the exit status.

Returns

Exit code and success flag.
```rust let status = sb.stop_and_wait().await?; println!("exited: {}", status.success()); ``` --- #### sb.wait()
instanceasync
```rust async fn wait(&self) -> MicrosandboxResult ``` Block until the sandbox exits on its own (without triggering a stop). Returns the exit status.

Returns

Exit code and success flag.
```rust let status = sb.wait().await?; ``` --- ## SandboxBuilder Builder for configuring a sandbox before creation. Obtained via [`Sandbox::builder(name)`](#sandboxbuilder). Every setter returns `Self`, so calls chain. Examples are shown on the methods where usage is non-obvious; simple setters are demonstrated by the [Typical flow](#typical-flow) above. --- #### .build()
builderasync
```rust async fn build(self) -> MicrosandboxResult ``` Materialize the [`SandboxConfig`](#sandboxconfig) without booting the sandbox. Validates the configuration and, if `from_snapshot` was called, opens the snapshot manifest to pin its image reference and upper-layer source. For booting, use [`create`](#create) or [`create_detached`](#create_detached) instead — they call `build` internally.

Returns

Validated, ready-to-boot configuration.
--- #### .cpus()
builder
```rust fn cpus(self, count: u8) -> Self ``` Set the number of virtual CPUs. This is a limit, not a reservation. Default: `1`.

Parameters

countu8
Number of vCPUs.
--- #### .create()
builderasync
```rust async fn create(self) -> MicrosandboxResult ``` Boot the sandbox in attached mode. The sandbox stops when your process exits.

Returns

Running sandbox.
--- #### .create_detached()
builderasync
```rust async fn create_detached(self) -> MicrosandboxResult ``` Boot the sandbox in detached mode. The sandbox survives after your process exits.

Returns

Running sandbox.
```rust let sb = Sandbox::builder("worker") .image("python") .create_detached() .await?; sb.detach().await; ``` --- #### .disable_network()
builder
```rust fn disable_network(self) -> Self ``` Fully disable networking. No network interface is created. --- #### .entrypoint()
builder
```rust fn entrypoint(self, cmd: impl IntoIterator>) -> Self ``` Override the OCI image's stored ENTRYPOINT. The value is consulted by command-resolution paths that follow OCI semantics — specifically `msb exec` / `msb run` against this sandbox from the terminal. [`Sandbox::exec`](/sdk/rust/execution) and [`Sandbox::shell`](/sdk/rust/execution) do **not** consult it; they pass `cmd` literally to the guest agent. Use this when configuring a sandbox via the SDK for later CLI attachment.

Parameters

cmdimpl IntoIterator
Entrypoint command and arguments.
--- #### .env()
builder
```rust fn env(self, key: impl Into, value: impl Into) -> 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

keyimpl Into<String>
Variable name.
valueimpl Into<String>
Variable value.
--- #### .hostname()
builder
```rust fn hostname(self, hostname: impl Into) -> Self ``` Set the guest hostname.

Parameters

hostnameimpl Into<String>
Hostname.
--- #### .idle_timeout()
builder
```rust 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

secsu64
Idle timeout in seconds.
--- #### .init()
builder
```rust fn init(self, cmd: impl Into) -> 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 [Custom init system](/sandboxes/customize#custom-init-system) for image picks, shutdown semantics, and tradeoffs. `cmd` is either an absolute path inside the guest rootfs or the literal `"auto"`. Auto first honors a known init at the start of the image ENTRYPOINT, such as `/init` in s6-overlay images, then falls back to probing `/sbin/init`, `/lib/systemd/systemd`, and `/usr/lib/systemd/systemd` inside the guest. When attached `msb run` uses an image-declared init entrypoint, the remaining ENTRYPOINT plus CMD or trailing command is passed to that init instead of direct-executed through agentd. For init binaries that take argv or extra env (rare), use [`init_with`](#init_with).

Parameters

cmdimpl Into<PathBuf>
Absolute path inside the guest, or "auto".
```rust let sb = Sandbox::builder("worker") .image("jrei/systemd-debian:12") .init("auto") .create() .await?; ``` --- #### .init_with()
builder
```rust fn init_with( self, cmd: impl Into, f: impl FnOnce(InitOptionsBuilder) -> InitOptionsBuilder, ) -> Self ``` Like [`init`](#init), but with a closure-builder for argv and env vars. Mirrors `exec_with` in shape. The builder exposes `arg`, `args`, `env`, and `envs`. Calling `init` or `init_with` more than once overwrites — different from `env`, which appends. The init is one-shot pre-boot.

Parameters

cmdimpl Into<PathBuf>
Absolute path to the init binary inside the guest.
fFnOnce(InitOptionsBuilder)
Closure populating argv and env.
```rust 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?; ``` --- #### .image()
builder
```rust 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

imageimpl IntoImage
OCI image name, local directory path, or disk image path.
--- #### .image_with()
builder
```rust fn image_with(self, f: impl FnOnce(ImageBuilder) -> ImageBuilder) -> Self ``` Configure an explicit rootfs source. Use this for OCI-only settings such as the writable overlay upper size, or for disk images when the filesystem type can't be auto-detected.

Parameters

fFnOnce(ImageBuilder)
Configure the rootfs source.
```rust use microsandbox::size::SizeExt; let sb = Sandbox::builder("worker") .image_with(|i| i.oci("python:3.12").upper_size(8.gib())) .create() .await?; ``` --- #### .log_level()
builder
```rust fn log_level(self, level: LogLevel) -> Self ``` Override the sandbox process's log verbosity.

Parameters

Log level.
--- #### .max_duration()
builder
```rust 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

secsu64
Maximum lifetime in seconds.
--- #### .memory()
builder
```rust fn memory(self, size: impl Into) -> 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

sizeimpl Into<Mebibytes>
Memory in MiB.
--- #### .network()
builder
```rust fn network(self, f: impl FnOnce(NetworkBuilder) -> NetworkBuilder) -> Self ``` Configure networking. See [Networking](/sdk/rust/networking) for the full builder API.

Parameters

Configure the network.
--- #### .patch()
builder
```rust 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. See [`PatchBuilder`](#patchbuilder) for the operations.

Parameters

Configure rootfs patches.
--- #### .port()
builder
```rust fn port(self, host_port: u16, guest_port: u16) -> Self ``` Publish a TCP port from the sandbox to the host. The default host bind address is `127.0.0.1`.

Parameters

host_portu16
Port on the host.
guest_portu16
Port inside the sandbox.
--- #### .port_bind()
builder
```rust fn port_bind(self, host_bind: IpAddr, host_port: u16, guest_port: u16) -> Self ``` Publish a TCP port on a specific host bind address, such as `0.0.0.0`.

Parameters

host_bindIpAddr
Host bind address.
host_portu16
Port on the host.
guest_portu16
Port inside the sandbox.
--- #### .port_udp()
builder
```rust fn port_udp(self, host_port: u16, guest_port: u16) -> Self ``` Publish a UDP port. The default host bind address is `127.0.0.1`.

Parameters

host_portu16
Port on the host.
guest_portu16
Port inside the sandbox.
--- #### .port_udp_bind()
builder
```rust fn port_udp_bind(self, host_bind: IpAddr, host_port: u16, guest_port: u16) -> Self ``` Publish a UDP port on a specific host bind address.

Parameters

host_bindIpAddr
Host bind address.
host_portu16
Port on the host.
guest_portu16
Port inside the sandbox.
--- #### .pull_policy()
builder
```rust fn pull_policy(self, policy: PullPolicy) -> Self ``` Control when the OCI image is pulled from the registry.

Parameters

Pull behavior.
--- #### .registry_auth()
builder
```rust fn registry_auth(self, auth: RegistryAuth) -> Self ``` Authenticate to a private container registry.

Parameters

Registry credentials.
--- #### .replace()
builder
```rust 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()
builder
```rust fn script(self, name: impl Into, content: impl Into) -> 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

nameimpl Into<String>
Script name (becomes the filename).
contentimpl Into<String>
Script content.
--- #### .secret()
builder
```rust fn secret(self, f: impl FnOnce(SecretBuilder) -> SecretBuilder) -> Self ``` Add a secret with full configuration. See [Secrets](/sdk/rust/secrets) for the builder API. Automatically enables TLS interception.

Parameters

Configure the secret.
--- #### .secret_env()
builder
```rust fn secret_env(self, env_var: impl Into, value: impl Into, allowed_host: impl Into) -> Self ``` Shorthand for adding a header-injected secret. Equivalent to `.secret(|s| s.env(env_var).value(value).allow_host(allowed_host))`.

Parameters

env_varimpl Into<String>
Environment variable name (non-empty, no = or NUL).
valueimpl Into<String>
Secret value.
allowed_hostimpl Into<String>
Allowed destination host.
--- #### .shell()
builder
```rust fn shell(self, shell: impl Into) -> Self ``` Set the shell used by [`Sandbox::shell()`](/sdk/rust/execution). Default: `/bin/sh`.

Parameters

shellimpl Into<String>
Shell path (e.g. "/bin/bash").
--- #### .user()
builder
```rust fn user(self, user: impl Into) -> Self ``` Set the default guest user for all commands.

Parameters

userimpl Into<String>
User name or UID.
--- #### .volume()
builder
```rust fn volume(self, guest_path: impl Into, f: impl FnOnce(MountBuilder) -> MountBuilder) -> Self ``` Add a volume mount. See [Volumes](/sdk/rust/volumes) for mount types.

Parameters

guest_pathimpl Into<String>
Mount point inside the sandbox.
Configure the mount.
--- #### .workdir()
builder
```rust fn workdir(self, path: impl Into) -> Self ``` Set the default working directory for all commands.

Parameters

pathimpl Into<String>
Absolute path inside the guest.
--- ## PatchBuilder Fluent builder for the ordered list of pre-boot rootfs patches. Used in `SandboxBuilder::patch(|p| p...)`. Each method appends one operation; calls are chainable. By default a method that targets a path already present in the image errors at boot; pass `replace = true` on the operation to allow overwriting. `mkdir` and `remove` are idempotent. See [Patches](/sandboxes/customize#patches) for conceptual context. --- #### .append()
builder
```rust fn append(self, path: impl Into, content: impl Into) -> Self ``` Append `content` to an existing file at `path`. If the file lives in a lower image layer, it's copied up first.

Parameters

pathimpl Into<String>
Absolute path inside the guest.
contentimpl Into<String>
Text to append.
--- #### .copy_dir()
builder
```rust fn copy_dir(self, src: impl Into, dst: impl Into, replace: bool) -> Self ``` Recursively copy a host directory at `src` into the guest rootfs at `dst`.

Parameters

srcimpl Into<PathBuf>
Host source directory.
dstimpl Into<String>
Absolute destination path inside the guest.
replacebool
When true, overwrite an existing path at dst.
--- #### .copy_file()
builder
```rust fn copy_file( self, src: impl Into, dst: impl Into, mode: Option, replace: bool, ) -> Self ``` Copy a single host file at `src` into the guest rootfs at `dst`.

Parameters

srcimpl Into<PathBuf>
Host source file.
dstimpl Into<String>
Absolute destination path inside the guest.
modeOption<u32>
File mode, e.g. Some(0o644). None keeps the source mode.
replacebool
When true, overwrite an existing path at dst.
--- #### .file()
builder
```rust fn file( self, path: impl Into, content: impl Into>, mode: Option, replace: bool, ) -> Self ``` Write raw bytes at `path`.

Parameters

pathimpl Into<String>
Absolute path inside the guest.
contentimpl Into<Vec<u8>>
Raw byte content.
modeOption<u32>
File mode, e.g. Some(0o644).
replacebool
When true, overwrite an existing path.
--- #### .mkdir()
builder
```rust fn mkdir(self, path: impl Into, mode: Option) -> Self ``` Create a directory at `path`. Idempotent: a no-op if the directory already exists.

Parameters

pathimpl Into<String>
Absolute path inside the guest.
modeOption<u32>
Directory mode, e.g. Some(0o755).
--- #### .remove()
builder
```rust fn remove(self, path: impl Into) -> Self ``` Delete a file or directory at `path`. Idempotent: a no-op if the path doesn't exist.

Parameters

pathimpl Into<String>
Absolute path inside the guest.
--- #### .symlink()
builder
```rust fn symlink(self, target: impl Into, link: impl Into, replace: bool) -> Self ``` Create a symlink at `link` pointing to `target`.

Parameters

targetimpl Into<String>
What the symlink points to (literal symlink target text).
linkimpl Into<String>
Absolute path of the symlink itself.
replacebool
When true, overwrite an existing path at link.
--- #### .text()
builder
```rust fn text( self, path: impl Into, content: impl Into, mode: Option, replace: bool, ) -> Self ``` Write UTF-8 text content at `path`.

Parameters

pathimpl Into<String>
Absolute path inside the guest.
contentimpl Into<String>
Text content.
modeOption<u32>
File mode, e.g. Some(0o644).
replacebool
When true, overwrite an existing path.
--- ## Types ### LogEntry
struct

Returned by logs()

A single captured log entry returned by [`logs()`](#sb-logs). | Field | Type | Description | |-------|------|-------------| | timestamp | `DateTime` | Wall-clock capture time on the host | | source | [`LogSource`](#logsource) | Where the chunk came from | | session_id | `Option` | Relay-monotonic session id; `None` for `System` entries | | data | `Bytes` | The chunk's bytes (UTF-8 lossy decoded by default; raw bytes if `--raw` mode was used) | ### LogLevel
enum

Used by log_level()

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 | ### LogOptions
struct

Used by logs()

Filters passed to [`logs()`](#sb-logs). All fields optional. `LogOptions::default()` returns everything for the default sources (`Stdout` + `Stderr` + `Output`). | Field | Type | Description | |-------|------|-------------| | tail | `Option` | Show only the last N entries after other filters apply | | since | `Option>` | Inclusive lower bound on entry timestamp | | until | `Option>` | Exclusive upper bound on entry timestamp | | sources | `Vec<`[`LogSource`](#logsource)`>` | Sources to include. Empty = `[Stdout, Stderr, Output]` (the default user-program sources). Add `System` to merge runtime/kernel diagnostics. | ### LogSource
enum

Used by LogEntry.source · LogOptions.sources

Tag indicating where a captured log entry came from. | Value | Description | |-------|-------------| | `Stdout` | Captured from a session's stdout (pipe mode — streams stayed separated) | | `Stderr` | Captured from a session's stderr (pipe mode) | | `Output` | Captured from a session running in pty mode. PTY allocation merges stdout and stderr at the kernel level inside the guest, so they arrive as a single stream — tagged `Output` rather than mislabelled as `Stdout`. | | `System` | Synthetic entry: lifecycle markers in `exec.log` plus runtime/kernel diagnostic lines merged in at read time when `System` is requested. | ### PullPolicy
enum

Used by pull_policy()

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
enum

Used by registry_auth()

Credentials for authenticating to a private container registry. | Variant | Fields | Description | |---------|--------|-------------| | `Basic` | - `username: String`
- `password: String` | Username and password authentication | ### SandboxConfig
struct

Returned by config() · build()

The full configuration of a sandbox. Obtained via [`config()`](#sb-config) or built via [`SandboxBuilder`](#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` | Idle timeout | | image | `RootfsSource` | Root filesystem source (OCI, bind, or disk image) | | max_duration_secs | `Option` | Maximum lifetime | | memory_mib | `u32` | Guest memory in MiB | | name | `String` | Sandbox name, up to 128 UTF-8 bytes | | patches | `Vec` | Rootfs patches | | scripts | `Vec<(String, String)>` | Named scripts | | shell | `Option` | Shell for `shell()` calls | | volumes | `Vec` | Volume mounts | | workdir | `Option` | Default working directory | ### SandboxHandle
struct

Returned by Sandbox::get() · Sandbox::list()

A lightweight handle to an existing sandbox (running or stopped). Obtained via [`Sandbox::get()`](#sandboxget) or [`Sandbox::list()`](#sandboxlist). 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`](#instance-methods). | Property / Method | Type | Description | |-------------------|------|-------------| | config() | `Result<`[`SandboxConfig`](#sandboxconfig)`>` | Parsed configuration | | config_json() | `&str` | Raw JSON configuration | | connect() | `Result<`[`Sandbox`](#instance-methods)`>` | Connect to a running sandbox; returns an error if it doesn't respond within ten seconds | | connect_with_timeout(timeout) | `Result<`[`Sandbox`](#instance-methods)`>` | Same as `connect()` with an explicit timeout | | created_at() | `Option>` | Creation timestamp | | kill() | `Result<()>` | Force terminate immediately. Pending writes may be lost | | logs() | `Result>` | Read captured `exec.log` (works without starting) | | metrics() | `Result<`[`SandboxMetrics`](#sandboxmetrics)`>` | Point-in-time resource metrics | | name() | `&str` | Sandbox name, up to 128 UTF-8 bytes | | remove() | `Result<()>` | Delete sandbox and state | | start() | `Result<`[`Sandbox`](#instance-methods)`>` | Start in attached mode | | start_detached() | `Result<`[`Sandbox`](#instance-methods)`>` | Start in detached mode | | status() | [`SandboxStatus`](#sandboxstatus) | Current status | | stop() | `Result<()>` | Gracefully shut down. Waits up to ten seconds for pending writes to flush, then force-kills | | stop_with_timeout(timeout) | `Result<()>` | Same as `stop()` with an explicit timeout; `Duration::ZERO` force-kills immediately | | updated_at() | `Option>` | Last update timestamp | ### SandboxMetrics
struct

Returned by metrics() · metrics_stream()

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 | | upper_used_bytes | `Option` | Guest-visible OCI upper filesystem used bytes when the protected reporter is available and fresh | | upper_free_bytes | `Option` | Guest-visible OCI upper filesystem free bytes when the protected reporter is available and fresh | | upper_host_allocated_bytes | `Option` | Host-allocated bytes for the writable OCI upper image when available | | timestamp | `DateTime` | When this measurement was taken | | uptime | `Duration` | Time since the sandbox was created | ### SandboxStatus
enum

Used by SandboxHandle.status()

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