--- 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. For local runtime installation and verification, see [Runtime setup](/sdk/setup#install-and-verify). ## Sandbox #### Sandbox::builder() ```rust fn builder(name: impl Into) -> SandboxBuilder ``` ```rust let sb = Sandbox::builder("api") .image("python") .create() .await?; ``` 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.
#### Sandbox::get() ```rust async fn get(name: &str) -> MicrosandboxResult ``` ```rust let handle = Sandbox::get("api").await?; println!("{:?}", handle.status()); ``` 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.
#### Sandbox::list() ```rust async fn list() -> MicrosandboxResult ``` ```rust let page = Sandbox::list().await?; for h in page.sandboxes { println!("{} - {:?}", h.name(), h.status()); } ``` Return the first page of sandboxes (running, stopped, and crashed), ordered newest first. The default page size is 20.

Returns

SandboxPage
Handles in this page and an optional cursor for the next page.
#### Sandbox::list_with() ```rust async fn list_with( configure: impl FnOnce(SandboxListBuilder) -> SandboxListBuilder, ) -> MicrosandboxResult ``` Return a configured page of sandboxes. Limits must be between 1 and 100. Labels are AND-matched before pagination. ```rust let page = Sandbox::list_with(|list| { list.limit(50).label("role", "worker") }).await?; if let Some(cursor) = page.next_cursor { let next_page = Sandbox::list_with(|list| { list.limit(50).cursor(cursor).label("role", "worker") }).await?; } ``` #### Sandbox::remove() ```rust async fn remove(name: &str) -> MicrosandboxResult<()> ``` ```rust Sandbox::remove("api").await?; ``` Delete a stopped sandbox by name. Locally, this removes the same state as [`sb.remove_persisted()`](#remove-persisted); see [Remove](/sandboxes/lifecycle#remove) for the exact deletion scope. Unlike `remove_persisted()`, this associated function routes through the default backend and also supports cloud sandboxes. Fails if the sandbox is still running—stop it first.

Parameters

name&str
Sandbox name, up to 128 UTF-8 bytes.
#### Sandbox::start() ```rust async fn start(name: &str) -> MicrosandboxResult ``` ```rust let sb = Sandbox::start("api").await?; ``` 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.
#### Sandbox::start_detached() ```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() ```rust fn config(&self) -> &SandboxConfig ``` ```rust println!("{} MiB", sb.config().memory_mib); ``` Access the sandbox's full configuration.

Returns

Sandbox configuration.
#### sb.detach() ```rust async fn detach(self) ``` ```rust sb.detach().await; // keeps running in the background ``` Release the handle without stopping the sandbox. The sandbox continues running as a background process. Reconnect later with [`Sandbox::get()`](#sandboxget). #### sb.drain() Local-only ```rust async fn drain(&self) -> MicrosandboxResult<()> ``` ```rust sb.drain().await?; ``` 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. #### sb.request_drain() Local-only ```rust async fn request_drain(&self) -> MicrosandboxResult<()> ``` Request graceful drain and return once the request is sent. Pair with [`wait_until_stopped()`](#sb-wait_until_stopped) when the caller needs stopped-state observation. #### sb.fs() ```rust fn fs(&self) -> SandboxFsOps<'_> ``` ```rust sb.fs().write("/tmp/hello.txt", "hi").await?; ``` Get a filesystem handle for reading and writing files inside the running sandbox. See [Filesystem](/sdk/rust/filesystem) for API details.

Returns

Filesystem handle.
#### sb.kill() Local-only ```rust async fn kill(&self) -> MicrosandboxResult<()> ``` ```rust sb.kill().await?; // SIGKILL, no graceful shutdown ``` Force-terminate the sandbox immediately with SIGKILL. No graceful shutdown - use when the sandbox is unresponsive. Waits up to five seconds for stopped-state observation after the kill request. 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. #### sb.kill_with_timeout() Local-only ```rust async fn kill_with_timeout(&self, timeout: Duration) -> MicrosandboxResult<()> ``` Force-terminate the sandbox and wait up to `timeout` for stopped-state observation. #### sb.request_kill() Local-only ```rust async fn request_kill(&self) -> MicrosandboxResult<()> ``` Request force termination and return once the request is sent, without waiting for stopped-state observation. #### sb.metrics() Local-only ```rust async fn metrics(&self) -> MicrosandboxResult ``` ```rust let m = sb.metrics().await?; println!("cpu {:.1}% · mem {} MiB", m.cpu_percent, m.memory_bytes / 1_048_576); ``` 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.
#### sb.metrics_stream() Local-only ```rust fn metrics_stream(&self, interval: Duration) -> impl Stream> ``` ```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); } ``` 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.
#### sb.logs() Local-only ```rust fn logs(&self, opts: &LogOptions) -> MicrosandboxResult> ``` ```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() })?; ``` 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.
#### sb.ping() Local-only ```rust async fn ping(&self) -> MicrosandboxResult ``` ```rust let result = sb.ping().await?; println!("{} reachable in {:?}", result.name, result.latency); ``` Check whether the running sandbox's guest agent is reachable. This sends `core.ping`, returns the SDK-measured round-trip latency, and does not refresh the sandbox idle timer.

Returns

Sandbox name and ping latency.
#### sb.touch() Local-only ```rust async fn touch(&self) -> MicrosandboxResult ``` ```rust let result = sb.touch().await?; println!("{} activity seq {}", result.name, result.activity_seq); ``` Explicitly refresh the running sandbox's idle timer. This sends `core.touch`; use it when keeping an idle sandbox alive is intentional.

Returns

Sandbox name and agent activity sequence after the touch.
#### sb.modify() Local-only ```rust fn modify(&self) -> SandboxModificationBuilder ``` ```rust let plan = sb.modify() .cpus(4) // live when 4 <= max_cpus .memory(4096) // live when 4096 MiB <= max_memory .env("MODE", "prod") // future execs only; the plan warns about this .apply() .await?; for r in &plan.resize_status { println!("{:?}: requested {} · actual {} · {:?}", r.resource, r.requested, r.actual, r.state); } ``` Plan or apply a configuration change. Set what to change (CPUs, memory, env vars, labels, workdir, secrets), then call [`dry_run()`](#dry_run) to preview or [`apply()`](#apply) to commit; both return a [`SandboxModificationPlan`](#sandboxmodificationplan) labeling each change `live`, `next start`, `requires restart`, or `unsupported`. Apply is all-or-nothing. CPU and memory resize live within the [`max_cpus`](#max_cpus) / [`max_memory`](#max_memory) ceilings; raising a ceiling requires a restart. Env and workdir changes affect future execs only. On a stopped sandbox, changes are saved for the next boot. See [`SandboxModificationBuilder`](#sandboxmodificationbuilder) for all setters and [`msb modify`](/cli/sandbox-commands#msb-modify) for the CLI.

Returns

Fluent builder; terminate with dry_run() or apply().
#### sb.name() ```rust fn name(&self) -> &str ``` Get the sandbox name.

Returns

&str
Sandbox name, up to 128 UTF-8 bytes.
#### sb.owns_lifecycle() On cloud ```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() ```rust async fn remove_persisted(&self) -> MicrosandboxResult<()> ``` ```rust sb.stop().await?; sb.remove_persisted().await?; ``` Delete this stopped sandbox's local persisted state. This is the receiver-based form to use when you still hold the `Sandbox` instance; it is local-only and has exactly the same local deletion scope as [`Sandbox::remove(name)`](#remove). It does **not** perform additional cleanup. See [Remove](/sandboxes/lifecycle#remove) for what is deleted and which external resources are preserved. #### sb.request_stop() ```rust async fn request_stop(&self) -> MicrosandboxResult<()> ``` Request graceful shutdown and return once the request is sent, without waiting for stopped-state observation. Pair with [`wait_until_stopped()`](#sb-wait_until_stopped) when the caller needs the terminal state. #### sb.stop() ```rust async fn stop(&self) -> MicrosandboxResult<()> ``` ```rust sb.stop().await?; ``` 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. #### sb.stop_with_timeout() ```rust async fn stop_with_timeout(&self, timeout: Duration) -> MicrosandboxResult<()> ``` Gracefully shut down the sandbox with an explicit timeout before escalation. `Duration::ZERO` skips graceful shutdown and force-kills immediately. #### sb.stop_and_wait() ```rust async fn stop_and_wait(&self) -> MicrosandboxResult ``` ```rust let status = sb.stop_and_wait().await?; println!("exited: {}", status.success()); ``` Stop the sandbox and wait for the exit status. This is a local-backend compatibility helper; prefer [`stop()`](#sb-stop) or [`stop_with_timeout()`](#sb-stop_with_timeout) when the caller only needs stopped-state observation.

Returns

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

Returns

Exit code and success flag.
#### sb.wait_until_stopped() ```rust async fn wait_until_stopped(&self) -> MicrosandboxResult ``` Block until the sandbox is observed in a terminal non-running state. Owned local sandboxes can include process exit details; detached, name-addressed, and cloud-backed sandboxes report the observed backend state. **Returns** | Type | Description | |------|-------------| | [`SandboxStopResult`](#sandboxstopresult) | Observed terminal sandbox state | ## 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. #### sandbox.build() ```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) instead; call [`detached(true)`](#detached) first for background mode. `create()` calls `build` internally.

Returns

Validated, ready-to-boot configuration.
#### sandbox.cpus() ```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.
#### sandbox.max_cpus() On cloud ```rust fn max_cpus(self, count: u8) -> Self ``` Set the boot-time maximum possible virtual CPU capacity. This reserves the envelope a sandbox can use after restart-backed changes and future live CPU activation; it does not increase the effective vCPU count by itself.

Parameters

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

Returns

Running sandbox.
#### sandbox.detached() ```rust fn detached(self, detached: bool) -> Self ``` ```rust let sb = Sandbox::builder("worker") .image("python") .detached(true) .create() .await?; sb.detach().await; ``` Choose whether the sandbox is created in detached/background mode. Detached sandboxes survive the creating process. Defaults to `false`.

Parameters

detachedbool
When true, create the sandbox in detached mode.
#### sandbox.create_detached() ```rust async fn create_detached(self) -> MicrosandboxResult ``` ```rust let sb = Sandbox::builder("worker") .image("python") .create_detached() .await?; sb.detach().await; ``` Boot the sandbox in detached mode. This is a compatibility helper for `.detached(true).create()`. Prefer [`detached(true)`](#detached) with [`create()`](#create) for new code so attached and detached creation use the same flow.

Returns

Running sandbox.
#### sandbox.disable_network() ```rust fn disable_network(self) -> Self ``` Fully disable networking. No network interface is created. #### sandbox.entrypoint() ```rust fn entrypoint(self, cmd: impl IntoIterator>) -> Self ``` Override the image ENTRYPOINT used by default-workload execution. [`Sandbox::exec_default`](/sdk/rust/execution) combines it with the effective CMD. Literal [`Sandbox::exec`](/sdk/rust/execution), [`Sandbox::attach`](/sdk/rust/execution), and [`Sandbox::shell`](/sdk/rust/execution) calls ignore it.

Parameters

cmdimpl IntoIterator
Entrypoint command and arguments.
#### sandbox.env() ```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.
#### sandbox.hostname() On cloud ```rust fn hostname(self, hostname: impl Into) -> Self ``` Set the guest hostname.

Parameters

hostnameimpl Into<String>
Hostname.
#### sandbox.idle_timeout() ```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.
#### sandbox.cmd() ```rust fn cmd(self, cmd: impl IntoIterator>) -> Self ``` Override the image CMD used by default-workload execution. An empty array explicitly clears the image CMD. This describes durable configuration and does not execute anything during `create()`. ```rust let sb = Sandbox::builder("worker") .image("example/worker:latest") .cmd(["worker.py", "--once"]) .create() .await?; ``` #### sandbox.init() ```rust fn init(self, cmd: impl Into) -> Self ``` ```rust let sb = Sandbox::builder("worker") .image("jrei/systemd-debian:12") .init("auto") .create() .await?; ``` 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/bootstrap#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".
#### sandbox.init_with() ```rust fn init_with( self, cmd: impl Into, f: impl FnOnce(InitOptionsBuilder) -> InitOptionsBuilder, ) -> Self ``` ```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?; ``` 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, unlike `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.
#### sandbox.image() On cloud ```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.
#### sandbox.image_with() On cloud ```rust fn image_with(self, f: impl FnOnce(ImageBuilder) -> ImageBuilder) -> Self ``` ```rust use microsandbox::size::SizeExt; let sb = Sandbox::builder("worker") .image_with(|i| i.oci("python:3.12").upper_size(8.gib())) .create() .await?; ``` 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.
#### sandbox.log_level() ```rust fn log_level(self, level: LogLevel) -> Self ``` Override the sandbox process's log verbosity.

Parameters

Log level.
#### sandbox.max_duration() ```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.
#### sandbox.memory() ```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.
#### sandbox.max_memory() On cloud ```rust fn max_memory(self, size: impl Into) -> Self ``` Set the boot-time maximum hotpluggable guest memory. This reserves the envelope a sandbox can use after restart-backed changes and future live memory activation; it does not increase the effective memory by itself.

Parameters

sizeimpl Into<Mebibytes>
Maximum memory in MiB.
#### sandbox.thp() ```rust fn thp(self, policy: TransparentHugePagePolicy) -> Self ``` Select the guest transparent huge-page policy applied through the kernel command line at boot. Default: `TransparentHugePagePolicy::Madvise`.

Parameters

policyTransparentHugePagePolicy
Always, Madvise, or Never.
#### sandbox.network() ```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.
#### sandbox.patch() ```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.
#### sandbox.port() Local-only ```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.
#### sandbox.port_bind() Local-only ```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.
#### sandbox.port_udp() Local-only ```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.
#### sandbox.port_udp_bind() Local-only ```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.
#### sandbox.pull_policy() ```rust fn pull_policy(self, policy: PullPolicy) -> Self ``` Control when the OCI image is pulled from the registry.

Parameters

Pull behavior.
#### sandbox.registry() Limited on cloud ```rust fn registry(self, f: impl FnOnce(RegistryConfigBuilder) -> RegistryConfigBuilder) -> Self ``` ```rust use microsandbox::{RegistryAuth, Sandbox}; let sb = Sandbox::builder("worker") .image("registry.example.com/team/app:latest") .registry(|r| r.auth(RegistryAuth::Basic { username: "user".into(), password: "token".into(), })) .create() .await?; ``` Configure registry connection settings for the sandbox image pull, including explicit auth, insecure HTTP, and custom CA certificates.

Parameters

Closure that configures registry auth and TLS options.
#### sandbox.replace() Local-only ```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. #### sandbox.script() ```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.
#### sandbox.secret() ```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.
#### sandbox.secret_env() ```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))`. **Plaintext at rest.** The value is persisted verbatim in the durable sandbox config until a later `modify` rotate migrates the entry to a source reference. Prefer `.secret(|s| s.source(..))` when the value can be referenced; use this path when you hold only a value. A future host-side secret store will switch this method to import-then-reference with no signature change.

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.
#### sandbox.shell() ```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").
#### sandbox.user() ```rust fn user(self, user: impl Into) -> Self ``` Set the default guest user for all commands.

Parameters

userimpl Into<String>
User name or UID.
#### sandbox.volume() ```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.
#### sandbox.workdir() ```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 Builder for pre-boot root filesystem patches. #### patch.append() ```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.
#### patch.copy_dir() On cloud ```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.
#### patch.copy_file() On cloud ```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.
#### patch.file() ```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.
#### patch.mkdir() On cloud ```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).
#### patch.remove() ```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.
#### patch.symlink() ```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.
#### patch.text() ```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.
## SandboxModificationBuilder Builder for planning or applying sandbox configuration changes. #### modification.apply() ```rust async fn apply(self) -> MicrosandboxResult ``` Apply the changes. Live changes are made to the running sandbox first, and the new config is saved only after they succeed, so a failed apply leaves the old config in place. Changes for a stopped sandbox, or requested with [`next_start()`](#next_start), are saved and take effect on the next start. With [`restart()`](#restart), the sandbox is stopped and started so that restart-required changes take effect. A live CPU or memory resize can take a moment to settle. The returned plan's `resize_status` reports progress per resource; see [`ResourceResizeStatus`](#resourceresizestatus).

Returns

The applied plan, with applied: true and live resize outcomes in resize_status.
#### modification.cpus() ```rust fn cpus(self, cpus: u8) -> Self ``` Set the desired effective vCPU count. Applies live to a running sandbox when the target fits inside the booted `max_cpus`; otherwise it requires a restart.

Parameters

cpusu8
Number of vCPUs.
#### modification.max_cpus() On cloud ```rust fn max_cpus(self, max_cpus: u8) -> Self ``` Set the desired boot-time maximum possible vCPU count. Capacity is fixed at boot, so this is always restart-backed on a running sandbox.

Parameters

max_cpusu8
Maximum possible vCPUs.
#### modification.dry_run() ```rust async fn dry_run(self) -> MicrosandboxResult ``` ```rust let plan = sb.modify().cpus(8).dry_run().await?; for change in &plan.changes { if let PlannedChange::Config(c) = change { println!("{}: {:?} -> {:?} ({:?})", c.field, c.before, c.after, c.disposition); } } ``` Compute the modification plan without applying anything. Use it to preview how each change classifies and whether conflicts block the patch.

Returns

The plan, with applied: false.
#### modification.env() ```rust fn env(self, key: impl Into, value: impl Into) -> Self ``` Set an environment variable for future execs. Can be called multiple times. On a running sandbox this applies to future execs only; running processes keep their current environment.

Parameters

keyimpl Into<String>
Variable name.
valueimpl Into<String>
Variable value.
#### modification.remove_env() ```rust fn remove_env(self, key: impl Into) -> Self ``` Remove an environment variable. Same future-execs-only semantics as [`env()`](#env-2).

Parameters

keyimpl Into<String>
Variable name to remove.
#### modification.label() ```rust fn label(self, key: impl Into, value: impl Into) -> Self ``` Set a sandbox label. Can be called multiple times.

Parameters

keyimpl Into<String>
Label key.
valueimpl Into<String>
Label value.
#### modification.remove_label() ```rust fn remove_label(self, key: impl Into) -> Self ``` Remove a sandbox label.

Parameters

keyimpl Into<String>
Label key to remove.
#### modification.memory() ```rust fn memory(self, size: impl Into) -> Self ``` Set the desired effective guest memory. Applies live to a running sandbox when the target fits inside the booted `max_memory`; otherwise it requires a restart.

Parameters

sizeimpl Into<Mebibytes>
Memory in MiB.
#### modification.memory_mib() ```rust fn memory_mib(self, memory_mib: u32) -> Self ``` Set the desired effective guest memory in MiB. Same as [`memory()`](#memory-2) with an explicit unit.

Parameters

memory_mibu32
Memory in MiB.
#### modification.max_memory() On cloud ```rust fn max_memory(self, size: impl Into) -> Self ``` Set the desired boot-time maximum hotpluggable memory. Capacity is fixed at boot, so this is always restart-backed on a running sandbox.

Parameters

sizeimpl Into<Mebibytes>
Maximum memory in MiB.
#### modification.max_memory_mib() On cloud ```rust fn max_memory_mib(self, max_memory_mib: u32) -> Self ``` Set the desired boot-time maximum hotpluggable memory in MiB. Same as [`max_memory()`](#max_memory-2) with an explicit unit.

Parameters

max_memory_mibu32
Maximum memory in MiB.
#### modification.next_start() ```rust fn next_start(self) -> Self ``` Persist the requested changes for the next start, leaving any running VM unchanged. Every change classifies as `next start`. #### modification.restart() ```rust fn restart(self) -> Self ``` Plan under restart-backed apply semantics. When the patch contains restart-required changes, [`apply()`](#apply) stops the sandbox, persists the config, and starts it again so the changes become active now. #### modification.secret() ```rust fn secret(self, f: impl FnOnce(SecretPatchBuilder) -> SecretPatchBuilder) -> Self ``` ```rust use microsandbox::sandbox::SecretSource; let plan = sb.modify() .secret(|s| s .env("API_KEY") .source(SecretSource::Env { var: "API_KEY".into() }) .allow_host("api.example.com")) .apply() .await?; ``` Declare the desired state of one secret via a [`SecretPatchBuilder`](#secretpatchbuilder) closure. The spec mirrors the create-time [`SecretBuilder`](/sdk/rust/secrets#secretbuilder) vocabulary, and the planner diffs it against the existing config to infer the change: a secret that does not exist yet is `added`, material on an existing secret `rotated`, and host or placeholder differences update those aspects. Declaring the same secret again replaces the earlier spec; removal is always explicit through [`remove_secret()`](#remove_secret).

Parameters

fFnOnce(SecretPatchBuilder)
Closure declaring the secret's desired state.
#### modification.remove_secret() ```rust fn remove_secret(self, name: impl Into) -> Self ``` Remove a secret. Removal is always explicit; omitting a secret from the patch never removes it.

Parameters

nameimpl Into<String>
Secret name (its environment variable name).
#### modification.workdir() ```rust fn workdir(self, path: impl Into) -> Self ``` Set the working directory for future execs. On a running sandbox this applies to future execs only.

Parameters

pathimpl Into<String>
Absolute path inside the guest.
## RegistryConfigBuilder

Used by registry()

Builder passed to [`registry()`](#registry) for per-sandbox registry connection settings. #### registry.auth() ```rust auth(auth: RegistryAuth) ``` Set explicit credentials for the image registry #### registry.insecure() ```rust insecure() ``` Use plain HTTP for the registry #### registry.ca_certs() ```rust ca_certs(pem_data: Vec) ``` Trust additional PEM-encoded CA certificates ## SandboxListBuilder Fluent configuration passed to [`Sandbox::list_with()`](#sandboxlist_with). Keep the labels and limit unchanged when continuing with a cursor. #### list.limit() ```rust limit(n) ``` Set a page size from 1 through 100 #### list.cursor() ```rust cursor(cursor) ``` Continue after a previous page's `next_cursor` #### list.label() ```rust label(key, value) ``` Require one label; repeated calls are AND-matched #### list.labels() ```rust labels(iterable) ``` Add several AND-matched labels ## SandboxHandle

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

A sandbox metadata and lifecycle handle that does not require an active guest-agent connection. #### h.config() ```rust config() ``` Parsed configuration

Returns

`Result<`[`SandboxConfig`](#sandboxconfig)`>` #### h.config_json() ```rust config_json() ``` Raw JSON configuration

Returns

`&str` #### h.connect() ```rust connect() ``` Connect to a running sandbox; returns an error if it doesn't respond within ten seconds

Returns

`Result<`[`Sandbox`](#instance-methods)`>` #### h.connect_with_timeout() ```rust connect_with_timeout(timeout) ``` Same as `connect()` with an explicit timeout

Returns

`Result<`[`Sandbox`](#instance-methods)`>` #### h.created_at() ```rust created_at() ``` Creation timestamp

Returns

`Option>` #### h.kill() ```rust kill() ``` Force terminate and wait until stopped state is observed

Returns

`Result<()>` #### h.kill_with_timeout() ```rust kill_with_timeout(timeout) ``` Same as `kill()` with an explicit observation timeout

Returns

`Result<()>` #### h.logs() ```rust logs() ``` Read captured `exec.log` (works without starting)

Returns

`Result>` #### h.metrics() ```rust metrics() ``` Point-in-time resource metrics

Returns

`Result<`[`SandboxMetrics`](#sandboxmetrics)`>` #### h.modify() ```rust modify() ``` Start planning a configuration change (works without starting; changes on a stopped sandbox persist for the next boot)

Returns

[`SandboxModificationBuilder`](#sandboxmodificationbuilder) #### h.name() ```rust name() ``` Sandbox name, up to 128 UTF-8 bytes

Returns

`&str` #### h.ping() ```rust ping() ``` Check agent reachability without refreshing idle activity

Returns

`Result<`[`SandboxPingResult`](#sandboxpingresult)`>` #### h.remove() ```rust remove() ``` Delete sandbox and state

Returns

`Result<()>` #### h.request_drain() ```rust request_drain() ``` Request graceful drain without waiting

Returns

`Result<()>` #### h.request_kill() ```rust request_kill() ``` Request force termination without waiting

Returns

`Result<()>` #### h.request_stop() ```rust request_stop() ``` Request graceful shutdown without waiting

Returns

`Result<()>` #### h.start() ```rust start() ``` Start in attached mode

Returns

`Result<`[`Sandbox`](#instance-methods)`>` #### h.start_detached() ```rust start_detached() ``` Start in detached mode

Returns

`Result<`[`Sandbox`](#instance-methods)`>` #### h.status() ```rust status() ``` Current status

Returns

[`SandboxStatus`](#sandboxstatus) #### h.stop() ```rust stop() ``` Gracefully shut down. Waits up to ten seconds for pending writes to flush, then force-kills

Returns

`Result<()>` #### h.stop_with_timeout() ```rust stop_with_timeout(timeout) ``` Same as `stop()` with an explicit timeout; `Duration::ZERO` force-kills immediately

Returns

`Result<()>` #### h.touch() ```rust touch() ``` Explicitly refresh the sandbox idle timer

Returns

`Result<`[`SandboxTouchResult`](#sandboxtouchresult)`>` #### h.updated_at() ```rust updated_at() ``` Last update timestamp

Returns

`Option>` #### h.wait_until_stopped() ```rust wait_until_stopped() ``` Block until terminal state is observed

Returns

`Result<`[`SandboxStopResult`](#sandboxstopresult)`>` ## SecretPatchBuilder

Used by secret()

Builder for one declarative secret change. #### secret.env() ```rust fn env(self, name: impl Into) -> Self ``` Name the secret. This is the environment variable that exposes the placeholder inside the guest. **Required.**

Parameters

nameimpl Into<String>
Secret name, usually the environment variable name.
#### secret.source() ```rust fn source(self, source: SecretSource) -> Self ``` Provide the secret material as a host-side [`SecretSource`](#secretsource) reference. The durable config records only the reference, and the value is resolved host-side when the change applies. Mutually exclusive with `value(...)`.

Parameters

Host-side reference for the secret material.
#### secret.value() ```rust fn value(self, value: impl Into) -> Self ``` Provide the secret material as a raw value, for embedders that hold only a value. The value is zeroized on drop, redacted from `Debug`, and never enters the plan. Applying a value persists it into the durable config until a later source-based rotate migrates it to a reference, the same at-rest property as `secret_env()`. Mutually exclusive with `source(...)`.

Parameters

valueimpl Into<String>
Raw secret value held by the embedding process.
#### secret.placeholder() ```rust fn placeholder(self, placeholder: impl Into) -> Self ``` Set the guest-visible placeholder. Placeholder changes cannot reach already-running processes, so they classify as `requires restart` on a running sandbox.

Parameters

placeholderimpl Into<String>
Guest-visible placeholder string.
#### secret.allow_host() ```rust fn allow_host(self, host: impl Into) -> Self ``` Add an allowed host pattern, such as `api.example.com`, `*.example.org`, or `*`. A non-empty list replaces the secret's current allow-list; an empty list leaves it unchanged. A new secret needs at least one.

Parameters

hostimpl Into<String>
Allowed exact host, wildcard host pattern, or *.
## Types ### LogEntry

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

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

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

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 mislabeled as `Stdout`. | | `System` | Synthetic entry: lifecycle markers in `exec.log` plus runtime/kernel diagnostic lines merged in at read time when `System` is requested. | ### SandboxPingResult

Returned by ping() · SandboxHandle.ping()

Result of a successful agent reachability check. | Field | Type | Description | |-------|------|-------------| | name | `String` | Sandbox name that was pinged | | latency | `Duration` | SDK-measured round-trip latency | ### SandboxTouchResult

Returned by touch() · SandboxHandle.touch()

Result of an explicit idle-timer refresh. | Field | Type | Description | |-------|------|-------------| | name | `String` | Sandbox name that was touched | | activity_seq | `u64` | Agent activity sequence after the touch was recorded | ### PullPolicy

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

Used by registry()

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

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 | | max_cpus | `u8` | Boot-time maximum possible virtual CPUs | | max_memory_mib | `u32` | Boot-time maximum hotpluggable memory in MiB | | 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 | ### SandboxPage One stable, newest-first page returned by [`Sandbox::list()`](#sandboxlist) or [`Sandbox::list_with()`](#sandboxlist_with). | Field | Type | Description | |-------|------|-------------| | `sandboxes` | `Vec` | Handles in this page | | `next_cursor` | `Option` | Opaque continuation cursor, or `None` on the final page | ### SandboxModificationPlan

Returned by dry_run() · apply()

Dry-run or apply plan for a sandbox modification. Values never appear in a plan: secret entries carry only guest-visible references. | Field | Type | Description | |-------|------|-------------| | sandbox | `String` | Sandbox being modified | | status | `String` | Sandbox status used for classification (`"running"`, `"stopped"`, ...) | | applied | `bool` | Whether the changes were applied; `false` for dry runs | | policy | `ModificationPolicy` | Policy used to produce the plan: `NoRestart` (default), `NextStart`, or `Restart` | | changes | `Vec<`[`PlannedChange`](#plannedchange)`>` | Planned changes, one entry per field or secret | | conflicts | `Vec` | Conflicts (`field` + `message`) that must be resolved before the patch can apply | | warnings | `Vec` | Non-fatal warnings (`field` + `message`) about the patch or current runtime capabilities, e.g. the future-execs-only env caveat | | resize_status | `Vec<`[`ResourceResizeStatus`](#resourceresizestatus)`>` | Live resource resize outcomes, populated by `apply()` when a live change ran | ### SecretSource

Used by SecretPatchBuilder.source()

Host-side source for secret material. The source is resolved when the modification applies, and plans only show guest-visible references. Import path: `microsandbox::sandbox::SecretSource`. | Variant | Field | Description | |---------|-------|-------------| | `Env` | `var: String` | Read the value from a host environment variable at apply time | | `Store` | `reference: String` | Reserved for a host-side secret store reference; current modifiers report it as unsupported | ### PlannedChange

Used by SandboxModificationPlan.changes

One planned modification entry. This enum has a `Config` variant for ordinary configuration fields and a `Secret` variant for secret changes. | Variant | Type | Description | |---------|------|-------------| | `Config` | [`ConfigPlannedChange`](#configplannedchange) | Ordinary config change | | `Secret` | [`SecretPlannedChange`](#secretplannedchange) | Secret change. Values are omitted by construction; references are guest-visible only | ### ConfigPlannedChange

Variant of PlannedChange::Config

Ordinary configuration change in a modification plan. | Field | Type | Description | |-------|------|-------------| | field | `String` | Config field being changed | | change | `ChangeKind` | `Added`, `Updated`, or `Removed` | | before | `Option` | Previous safe visible state | | after | `Option` | New safe visible state | | disposition | [`ModificationDisposition`](#modificationdisposition) | When or whether the change can take effect | | reason | `Option` | Human-readable reason for the classification, when useful | ### SecretPlannedChange

Variant of PlannedChange::Secret

Secret change in a modification plan. Values are omitted by construction; `before_ref` and `after_ref` are guest-visible references. | Field | Type | Description | |-------|------|-------------| | field | `String` | Always `"secret"` | | name | `String` | Stable secret identity, usually the environment variable name | | change | `SecretChangeKind` | `Added`, `Rotated`, `Removed`, `Renamed`, `HostsUpdated`, or `PlaceholderUpdated` | | before_ref | `Option` | Previous guest-visible reference or placeholder | | after_ref | `Option` | New guest-visible reference or placeholder | | disposition | [`ModificationDisposition`](#modificationdisposition) | When or whether the change can take effect | | allow_hosts | `Vec` | Allowed hosts after the requested change | | reason | `Option` | Human-readable reason for the classification, when useful | ### ModificationDisposition

Used by ConfigPlannedChange.disposition · SecretPlannedChange.disposition

When or whether a planned change can take effect. Serializes as the quoted strings below. | Value | Description | |-------|-------------| | `Live` (`"live"`) | Applies to the running VM now | | `NextStart` (`"next start"`) | Persists to the desired config and applies the next time the sandbox starts | | `RequiresRestart` (`"requires restart"`) | Needs a restart before it can take effect; `apply()` refuses it unless the [`restart()`](#restart) policy is selected | | `Unsupported` (`"unsupported"`) | Cannot be changed by `modify` | ### ResourceResizeStatus

Used by SandboxModificationPlan.resize_status

Runtime convergence status for a live resource resize. Enforcement applies immediately; the guest converges asynchronously (onlining CPUs, plugging memory blocks). | Field | Type | Description | |-------|------|-------------| | resource | `ResourceKind` | `Cpus` or `Memory` | | requested | `String` | Requested value | | actual | `String` | Actual value observed in the guest/runtime | | enforced | `String` | Host/VMM-enforced value | | state | `ResourceConvergenceState` | Convergence state, see below | | State | Description | |-------|-------------| | `Accepted` | The runtime accepted the request | | `Converging` | The guest and VMM are still converging on the requested state | | `Applied` | Desired, actual, and enforced state match | | `GuestRefused` | The guest would not cooperate; the host enforces the new limit anyway | | `Failed` | The resize failed | ### SandboxStopResult Observed terminal sandbox state returned by [`wait_until_stopped()`](#sb-wait_until_stopped). | Field | Type | Description | |-------|------|-------------| | name | `String` | Sandbox name | | status | [`SandboxStatus`](#sandboxstatus) | Terminal status that was observed | | exit_code | `Option` | Process exit code when available from an owned child process | | signal | `Option` | Terminating signal when available from an owned child process | | observed_at | `DateTime` | When the terminal state was observed | | source | `Option` | Description of the observation source | ### SandboxMetrics

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

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 |