> ## Documentation Index > Fetch the complete documentation index at: https://microsanbox-staging-toks-cloud-snapshot-contracts.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Sandbox > 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). ## Reuse and restart sandboxes ```rust theme={null} SandboxBuilder::connect_or_create(self) -> MicrosandboxResult SandboxHandle::connect_or_start(&self) -> MicrosandboxResult SandboxHandle::wait_for_status(&self, status: SandboxStatus) -> MicrosandboxResult SandboxHandle::restart(&self) -> MicrosandboxResult SandboxHandle::destroy(&self) -> MicrosandboxResult<()> Sandbox::id(&self) -> SandboxId SandboxHandle::id(&self) -> SandboxId ``` Use `connect_or_create` when a named sandbox might already exist. It connects to a running sandbox, starts a stopped or crashed sandbox, and creates one only when the name is unused. Builder options apply only to a new sandbox. Lifecycle methods on a `Sandbox` or `SandboxHandle` stay attached to its opaque `SandboxId`. If the name is removed and reused, an old receiver returns `MicrosandboxError::SandboxReplaced` instead of acting on the replacement. Custom backends provide the same behavior by implementing the `*_identified` methods on `SandboxBackend`. See [Reuse or create a named sandbox](/sandboxes/lifecycle#reuse-or-create-a-named-sandbox) for examples. ## Sandbox #### Sandbox::builder() ```rust theme={null} fn builder(name: impl Into) -> SandboxBuilder ``` ```rust theme={null} 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\
Sandbox name. Must be unique and no longer than 128 UTF-8 bytes.

Returns

Builder for configuring the sandbox.
#### Sandbox::get() ```rust theme={null} async fn get(name: &str) -> MicrosandboxResult ``` ```rust theme={null} 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

Handle with status and lifecycle control.
#### Sandbox::list() ```rust theme={null} async fn list() -> MicrosandboxResult ``` ```rust theme={null} 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 theme={null} 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 theme={null} 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 theme={null} async fn remove(name: &str) -> MicrosandboxResult<()> ``` ```rust theme={null} Sandbox::remove("api").await?; ``` Delete a stopped sandbox by name. Locally, this removes the same state as [`sb.remove_persisted()`](#sb-remove_persisted); see [Destroy or remove](/sandboxes/lifecycle#destroy-or-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 theme={null} async fn start(name: &str) -> MicrosandboxResult ``` ```rust theme={null} let sb = Sandbox::start("api").await?; ``` Restart a previously stopped sandbox. The VM reboots using the persisted configuration. Local handles enter attached mode and stop the sandbox when the client process exits; cloud handles do not own the service-managed VM.

Parameters

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

Returns

Running sandbox.
#### Sandbox::start\_detached() ```rust theme={null} 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 theme={null} fn config(&self) -> &SandboxConfig ``` ```rust theme={null} println!("{} MiB", sb.config().memory_mib); ``` Access the sandbox's full configuration.

Returns

Sandbox configuration.
#### sb.id() ```rust theme={null} fn id(&self) -> SandboxId ``` Return the opaque stable identity of this persisted sandbox. The ID is backend-qualified, remains unchanged across stop and restart, and changes when the name is removed and recreated. Treat it as an equality and correlation token; do not parse it. #### sb.detach() ```rust theme={null} async fn detach(self) ``` ```rust theme={null} 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()`](#sandbox-get). #### sb.drain() Local-only ```rust theme={null} async fn drain(&self) -> MicrosandboxResult<()> ``` ```rust theme={null} 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 theme={null} 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 theme={null} fn fs(&self) -> SandboxFsOps<'_> ``` ```rust theme={null} 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 theme={null} async fn kill(&self) -> MicrosandboxResult<()> ``` ```rust theme={null} 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 theme={null} 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 theme={null} 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 theme={null} async fn metrics(&self) -> MicrosandboxResult ``` ```rust theme={null} 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 theme={null} fn metrics_stream(&self, interval: Duration) -> impl Stream> ``` ```rust theme={null} 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 theme={null} fn logs(&self, opts: &LogOptions) -> MicrosandboxResult> ``` ```rust theme={null} 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 theme={null} async fn ping(&self) -> MicrosandboxResult ``` ```rust theme={null} 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 theme={null} async fn touch(&self) -> MicrosandboxResult ``` ```rust theme={null} 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 theme={null} fn modify(&self) -> SandboxModificationBuilder ``` ```rust theme={null} 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()`](#modification-dry_run) to preview or [`apply()`](#modification-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`](#modification-max_cpus) / [`max_memory`](#modification-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 theme={null} fn name(&self) -> &str ``` Get the sandbox name.

Returns

\&str
Sandbox name, up to 128 UTF-8 bytes.
#### sb.owns\_lifecycle() ```rust theme={null} fn owns_lifecycle(&self) -> bool ``` Whether this handle owns the sandbox lifecycle. Local attached handles return `true`; local detached handles and all cloud handles return `false`, because the cloud worker owns the sandbox process.

Returns

bool
true for a local attached handle.
#### sb.remove\_persisted() Local-only ```rust theme={null} async fn remove_persisted(&self) -> MicrosandboxResult<()> ``` ```rust theme={null} sb.stop().await?; sb.remove_persisted().await?; ``` Delete this stopped sandbox's persisted state. This receiver-based form is useful when you still hold the `Sandbox` instance; it has exactly the same deletion scope as [`Sandbox::remove(name)`](#sandbox-remove). It does **not** perform additional cleanup. See [Destroy or remove](/sandboxes/lifecycle#destroy-or-remove) for what is deleted and which external resources are preserved. #### sb.request\_stop() ```rust theme={null} 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() Different on cloud ```rust theme={null} async fn stop(&self) -> MicrosandboxResult<()> ``` ```rust theme={null} sb.stop().await?; ``` Gracefully shut down the sandbox and wait until stopped state is observed. Local waits up to ten seconds, then force-kills the sandbox if it is still running. Cloud waits up to six minutes because shutdown may include creating a durable disk checkpoint. If that deadline expires, this returns `MicrosandboxError::SandboxStopTimedOut` without cancelling the accepted server-side stop, which may still complete afterward. #### sb.stop\_with\_timeout() Different on cloud ```rust theme={null} async fn stop_with_timeout(&self, timeout: Duration) -> MicrosandboxResult<()> ``` Gracefully shut down the sandbox with an explicit observation timeout. Local force-kills after the timeout. Cloud returns `MicrosandboxError::SandboxStopTimedOut` instead, while the accepted server-side stop may continue. `Duration::ZERO` requests immediate force termination and is therefore local-only. #### sb.stop\_and\_wait() Local-only ```rust theme={null} async fn stop_and_wait(&self) -> MicrosandboxResult ``` ```rust theme={null} 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() Local-only ```rust theme={null} async fn wait(&self) -> MicrosandboxResult ``` ```rust theme={null} 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 theme={null} 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

Observed terminal sandbox state.
#### sb.wait\_for\_status() ```rust theme={null} async fn wait_for_status(&self, status: SandboxStatus) -> MicrosandboxResult ``` Wait until this exact persisted sandbox reaches `status`. The method intentionally has no built-in timeout; wrap the future with `tokio::time::timeout` or another cancellation primitive when a deadline is required. Returns `SandboxReplaced` rather than following a reused name. #### sb.restart() ```rust theme={null} async fn restart(&self) -> MicrosandboxResult ``` Gracefully stop and start this exact sandbox using the persisted configuration. A stopped, crashed, or newly created sandbox starts directly; a starting sandbox is observed until it settles. Returns an attached local handle or a service-owned cloud handle. #### sb.restart\_with() ```rust theme={null} async fn restart_with(&self, options: RestartOptions) -> MicrosandboxResult ``` Restart with explicit lifecycle controls. `RestartOptions` defaults to graceful shutdown, a ten-second timeout, and attached local start. Set `force` to kill instead of draining, `timeout` to control how long shutdown can take, and `detached` to start a local background sandbox. #### sb.destroy() ```rust theme={null} async fn destroy(&self) -> MicrosandboxResult<()> ``` Gracefully stop and remove this exact sandbox. Unlike [`remove_persisted()`](#sb-remove_persisted), `destroy` accepts a running sandbox, waits for it to shut down, and then deletes its persisted state. #### sb.destroy\_with() ```rust theme={null} async fn destroy_with(&self, options: DestroyOptions) -> MicrosandboxResult<()> ``` Destroy with explicit shutdown controls. `DestroyOptions` defaults to graceful shutdown with a ten-second timeout; set `force` to kill immediately or `timeout` to change how long shutdown can take. Identity checks prevent this receiver from deleting a same-name replacement. ## 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.slug() Cloud-only ```rust theme={null} fn slug(self, slug: impl Into) -> Self ``` Request a globally unique cloud slug. When omitted, microsandbox cloud assigns one; creation fails if the requested slug is already taken.

Parameters

slugimpl Into\
Requested cloud slug.
#### sandbox.build() ```rust theme={null} async fn build(self) -> MicrosandboxResult ``` Materialize the [`SandboxConfig`](#sandboxconfig) without booting the sandbox. Local snapshot references are opened to pin their image and upper-layer source; cloud references remain typed and are resolved by the cloud backend. For booting, use [`create`](#sandbox-create) instead; call [`detached(true)`](#sandbox-detached) first for background mode. `create()` calls `build` internally.

Returns

Validated, ready-to-boot configuration.
#### sandbox.overlay() ```rust theme={null} fn overlay(self, patch: SandboxConfigPatch) -> Self ``` Apply sparse per-sandbox configuration after built-in and global defaults. Builder methods called after `overlay` take precedence over the patch. ```rust theme={null} use microsandbox::{ EnvVar, Sandbox, SandboxConfigPatch, SandboxResourcesPatch, }; let resources = SandboxResourcesPatch::new() .max_memory_mib(1024) .memory_mib(1024) .max_cpus(2) .cpus(2); let patch = SandboxConfigPatch::new() .resources(resources) .env(vec![EnvVar::new("MODE", "production")]); let sandbox = Sandbox::builder("agent") .image("python:3.12") .overlay(patch) .memory(2048) .create() .await?; ``` Environment variables merge by variable name, while labels and scripts merge by map key. Secret entries merge by environment-variable name. Later values win when keys match. Use the generated `replace_*` methods to replace a complete collection; `clear_*` removes the field from the patch so the lower-precedence value remains unchanged. `SandboxConfigPatch` contains typed configuration values only. YAML loading, relative-path resolution, `${ENV}` expansion, registry credentials, and snapshot selection remain separate CLI or builder responsibilities. The generated patch model replaces the handwritten patch hierarchy from microsandbox 0.6.15 and earlier: | Earlier type | Current type | | -------------------------- | ---------------------------- | | `ResourceConfigPatch` | `SandboxResourcesPatch` | | `RuntimeConfigPatch` | `SandboxRuntimeOptionsPatch` | | `NetworkConfigPatch` | `NetworkSpecPatch` | | `NetworkPolicyConfigPatch` | `SandboxPolicyPatch` | | `SecretConfigPatch` | `SecretsConfigPatch` | Filesystem, script, image, and init values now use `SandboxConfigPatch` and its nested patch types directly. `LocalConfig` remains available as a deprecated alias of `GlobalConfig`. #### sandbox.cpus() ```rust theme={null} 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() Local-only ```rust theme={null} 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 theme={null} async fn create(self) -> MicrosandboxResult ``` Boot the sandbox. Local handles use attached mode and stop the sandbox when the client process exits; cloud handles do not own the service-managed VM, so stop or remove cloud sandboxes explicitly.

Returns

Running sandbox.
#### sandbox.connect\_or\_create() ```rust theme={null} async fn connect_or_create(self) -> MicrosandboxResult ``` Reuse or create the sandbox with this name. The method connects when it is running, waits while it is starting, starts it when it is created, stopped, or crashed, and creates it only when the name is unused. Builder configuration applies only to a new sandbox. Concurrent callers reuse the same sandbox. Combining this method with [`replace()`](#sandbox-replace) returns `InvalidConfig`.

Returns

`MicrosandboxResult<`[`Sandbox`](#instance-methods)`>` #### sandbox.detached() ```rust theme={null} fn detached(self, detached: bool) -> Self ``` ```rust theme={null} 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 theme={null} async fn create_detached(self) -> MicrosandboxResult ``` ```rust theme={null} 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)`](#sandbox-detached) with [`create()`](#sandbox-create) for new code so attached and detached creation use the same flow.

Returns

Running sandbox.
#### sandbox.disable\_network() ```rust theme={null} fn disable_network(self) -> Self ``` Fully disable networking. No network interface is created. #### sandbox.entrypoint() ```rust theme={null} 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 theme={null} 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\
Variable name.
valueimpl Into\
Variable value.
#### sandbox.hostname() Local-only ```rust theme={null} fn hostname(self, hostname: impl Into) -> Self ``` Set the guest hostname.

Parameters

hostnameimpl Into\
Hostname.
#### sandbox.idle\_timeout() ```rust theme={null} 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 theme={null} 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 theme={null} let sb = Sandbox::builder("worker") .image("example/worker:latest") .cmd(["worker.py", "--once"]) .create() .await?; ``` #### sandbox.init() ```rust theme={null} fn init(self, cmd: impl Into) -> Self ``` ```rust theme={null} 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`](#sandbox-init_with).

Parameters

cmdimpl Into\
Absolute path inside the guest, or "auto".
#### sandbox.init\_with() ```rust theme={null} fn init_with( self, cmd: impl Into, f: impl FnOnce(InitOptionsBuilder) -> InitOptionsBuilder, ) -> Self ``` ```rust theme={null} 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`](#sandbox-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\
Absolute path to the init binary inside the guest.
fFnOnce(InitOptionsBuilder)
Closure populating argv and env.
#### sandbox.image() Limited on cloud ```rust theme={null} 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() Limited on cloud ```rust theme={null} fn image_with(self, f: impl FnOnce(ImageBuilder) -> ImageBuilder) -> Self ``` ```rust theme={null} use microsandbox::size::SizeExt; let sb = Sandbox::builder("worker") .image_with(|i| i.oci("python:3.12").root_disk(8.gib())) .create() .await?; ``` Configure an explicit rootfs source. Use this for OCI-only settings such as the writable root disk, or for disk images when the filesystem type can't be auto-detected.

Parameters

fFnOnce(ImageBuilder)
Configure the rootfs source.
#### sandbox.log\_level() ```rust theme={null} fn log_level(self, level: LogLevel) -> Self ``` Override the sandbox process's log verbosity.

Parameters

Log level.
#### sandbox.max\_duration() ```rust theme={null} fn max_duration(self, secs: u64) -> Self ``` Set the maximum sandbox lifetime in seconds. When exceeded, the host drains and stops the sandbox. Enforced on the host side; the guest cannot override it.

Parameters

secsu64
Maximum lifetime in seconds.
#### sandbox.memory() ```rust theme={null} 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\
Memory in MiB.
#### sandbox.max\_memory() Local-only ```rust theme={null} 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\
Maximum memory in MiB.
#### sandbox.thp() ```rust theme={null} 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 theme={null} 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.proxy() ```rust theme={null} fn proxy

(self, configure: impl FnOnce(OutboundProxyBuilder) -> P) -> Self where P: OutboundProxyConfig ``` Configure the single proxy used for outbound sandbox connections. See [Proxies](/sdk/rust/proxies) for the protocol builders and examples. #### sandbox.patch() ```rust theme={null} 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 theme={null} 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 theme={null} 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 theme={null} 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 theme={null} 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 theme={null} 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 theme={null} fn registry(self, f: impl FnOnce(RegistryConfigBuilder) -> RegistryConfigBuilder) -> Self ``` ```rust theme={null} 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 theme={null} 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 theme={null} 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\
Script name (becomes the filename).
contentimpl Into\
Script content.
#### sandbox.secret() ```rust theme={null} 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 theme={null} 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\
Environment variable name (non-empty, no = or NUL).
valueimpl Into\
Secret value.
allowed\_hostimpl Into\
Allowed destination host.
#### sandbox.shell() ```rust theme={null} fn shell(self, shell: impl Into) -> Self ``` Set the shell used by [`Sandbox::shell()`](/sdk/rust/execution). Default: `/bin/sh`.

Parameters

shellimpl Into\
Shell path (e.g. "/bin/bash").
#### sandbox.user() ```rust theme={null} fn user(self, user: impl Into) -> Self ``` Set the default guest user for all commands.

Parameters

userimpl Into\
User name or UID.
#### sandbox.volume() ```rust theme={null} 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\
Mount point inside the sandbox.
Configure the mount.
#### sandbox.workdir() ```rust theme={null} fn workdir(self, path: impl Into) -> Self ``` Set the default working directory for all commands.

Parameters

pathimpl Into\
Absolute path inside the guest.
## PatchBuilder Builder for pre-boot root filesystem patches. #### patch.append() ```rust theme={null} 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\
Absolute path inside the guest.
contentimpl Into\
Text to append.
#### patch.copy\_dir() Limited on cloud ```rust theme={null} 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\
Host source directory.
dstimpl Into\
Absolute destination path inside the guest.
replacebool
When true, overwrite an existing path at dst.
#### patch.copy\_file() Limited on cloud ```rust theme={null} 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\
Host source file.
dstimpl Into\
Absolute destination path inside the guest.
modeOption\
File mode, e.g. Some(0o644). None keeps the source mode.
replacebool
When true, overwrite an existing path at dst.
#### patch.file() ```rust theme={null} fn file( self, path: impl Into, content: impl Into>, mode: Option, replace: bool, ) -> Self ``` Write raw bytes at `path`.

Parameters

pathimpl Into\
Absolute path inside the guest.
contentimpl Into\>
Raw byte content.
modeOption\
File mode, e.g. Some(0o644).
replacebool
When true, overwrite an existing path.
#### patch.mkdir() ```rust theme={null} 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\
Absolute path inside the guest.
modeOption\
Directory mode, e.g. Some(0o755).
#### patch.remove() ```rust theme={null} 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\
Absolute path inside the guest.
#### patch.symlink() ```rust theme={null} fn symlink(self, target: impl Into, link: impl Into, replace: bool) -> Self ``` Create a symlink at `link` pointing to `target`.

Parameters

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

Parameters

pathimpl Into\
Absolute path inside the guest.
contentimpl Into\
Text content.
modeOption\
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 theme={null} 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()`](#modification-next_start), are saved and take effect on the next start. With [`restart()`](#modification-restart), `apply()` stops and starts the sandbox 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 theme={null} 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() Local-only ```rust theme={null} 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 theme={null} async fn dry_run(self) -> MicrosandboxResult ``` ```rust theme={null} 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 theme={null} 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\
Variable name.
valueimpl Into\
Variable value.
#### modification.remove\_env() ```rust theme={null} fn remove_env(self, key: impl Into) -> Self ``` Remove an environment variable. Same future-execs-only semantics as [`env()`](#modification-env).

Parameters

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

Parameters

keyimpl Into\
Label key.
valueimpl Into\
Label value.
#### modification.remove\_label() ```rust theme={null} fn remove_label(self, key: impl Into) -> Self ``` Remove a sandbox label.

Parameters

keyimpl Into\
Label key to remove.
#### modification.memory() ```rust theme={null} 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\
Memory in MiB.
#### modification.memory\_mib() ```rust theme={null} fn memory_mib(self, memory_mib: u32) -> Self ``` Set the desired effective guest memory in MiB. Same as [`memory()`](#modification-memory) with an explicit unit.

Parameters

memory\_mibu32
Memory in MiB.
#### modification.max\_memory() Local-only ```rust theme={null} 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\
Maximum memory in MiB.
#### modification.max\_memory\_mib() Local-only ```rust theme={null} fn max_memory_mib(self, max_memory_mib: u32) -> Self ``` Set the desired boot-time maximum hotpluggable memory in MiB. Same as [`max_memory()`](#modification-max_memory) with an explicit unit.

Parameters

max\_memory\_mibu32
Maximum memory in MiB.
#### modification.next\_start() ```rust theme={null} 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 theme={null} fn restart(self) -> Self ``` Plan under restart-backed apply semantics. When the patch contains restart-required changes, [`apply()`](#modification-apply) stops the sandbox, persists the config, and starts it again so the changes become active now. #### modification.secret() ```rust theme={null} fn secret(self, f: impl FnOnce(SecretPatchBuilder) -> SecretPatchBuilder) -> Self ``` ```rust theme={null} 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. 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()`](#modification-remove_secret).

Parameters

fFnOnce(SecretPatchBuilder)
Closure declaring the secret's desired state.
#### modification.remove\_secret() ```rust theme={null} 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\
Secret name (its environment variable name).
#### modification.workdir() ```rust theme={null} 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\
Absolute path inside the guest.
## RegistryConfigBuilder

Used by registry()

Builder passed to [`registry()`](#sandbox-registry) for per-sandbox registry connection settings. #### registry.auth() ```rust theme={null} auth(auth: RegistryAuth) ``` Set explicit credentials for the image registry #### registry.insecure() ```rust theme={null} insecure() ``` Use plain HTTP for the registry #### registry.ca\_certs() ```rust theme={null} ca_certs(pem_data: Vec) ``` Trust additional PEM-encoded CA certificates ## SandboxListBuilder Fluent configuration passed to [`Sandbox::list_with()`](#sandbox-list_with). Keep the labels and limit unchanged when continuing with a cursor. #### list.limit() ```rust theme={null} limit(n) ``` Set a page size from 1 through 100 #### list.cursor() ```rust theme={null} cursor(cursor) ``` Continue after a previous page's `next_cursor` #### list.label() ```rust theme={null} label(key, value) ``` Require one label; repeated calls are AND-matched #### list.labels() ```rust theme={null} 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() Local-only ```rust theme={null} config() ``` Parsed configuration

Returns

`Result<`[`SandboxConfig`](#sandboxconfig)`>` #### h.config\_json() ```rust theme={null} config_json() ``` Raw JSON configuration

Returns

`&str` #### h.connect() ```rust theme={null} 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 theme={null} connect_with_timeout(timeout) ``` Same as `connect()` with an explicit timeout

Returns

`Result<`[`Sandbox`](#instance-methods)`>` #### h.connect\_or\_start() ```rust theme={null} async fn connect_or_start(&self) -> MicrosandboxResult ``` Connect to this exact sandbox when it is running, wait through `Starting`, or start it in attached mode when it is `Created`, `Stopped`, or `Crashed`. `Draining` and `Paused` are rejected. If another caller starts it at the same time, both callers connect to the same sandbox without following a same-name replacement. #### h.connect\_or\_start\_detached() ```rust theme={null} async fn connect_or_start_detached(&self) -> MicrosandboxResult ``` Behaves like [`connect_or_start()`](#h-connect_or_start), but starts a local stopped sandbox in detached/background mode. Connecting to an already-running sandbox never changes its ownership. #### h.created\_at() ```rust theme={null} created_at() ``` Creation timestamp

Returns

`Option>` #### h.kill() Local-only ```rust theme={null} kill() ``` Force terminate and wait until stopped state is observed

Returns

`Result<()>` #### h.kill\_with\_timeout() Local-only ```rust theme={null} kill_with_timeout(timeout) ``` Same as `kill()` with an explicit observation timeout

Returns

`Result<()>` #### h.logs() Local-only ```rust theme={null} logs() ``` Read captured `exec.log` (works without starting)

Returns

`Result>` #### h.metrics() Local-only ```rust theme={null} metrics() ``` Point-in-time resource metrics

Returns

`Result<`[`SandboxMetrics`](#sandboxmetrics)`>` #### h.modify() Local-only ```rust theme={null} 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 theme={null} name() ``` Sandbox name, up to 128 UTF-8 bytes

Returns

`&str` #### h.id() ```rust theme={null} fn id(&self) -> SandboxId ``` Return the stable identity captured by this metadata handle. Receiver lifecycle calls stay bound to this ID and return `SandboxReplaced` if the reusable name now points to another sandbox. #### h.ping() Local-only ```rust theme={null} ping() ``` Check agent reachability without refreshing idle activity

Returns

`Result<`[`SandboxPingResult`](#sandboxpingresult)`>` #### h.remove() ```rust theme={null} remove() ``` Delete sandbox and state

Returns

`Result<()>` #### h.request\_drain() Local-only ```rust theme={null} request_drain() ``` Request graceful drain without waiting

Returns

`Result<()>` #### h.request\_kill() Local-only ```rust theme={null} request_kill() ``` Request force termination without waiting

Returns

`Result<()>` #### h.request\_stop() ```rust theme={null} request_stop() ``` Request graceful shutdown without waiting

Returns

`Result<()>` #### h.start() ```rust theme={null} start() ``` Start the sandbox. The returned local handle is attached; a cloud handle does not own the service-managed VM.

Returns

`Result<`[`Sandbox`](#instance-methods)`>` #### h.start\_detached() ```rust theme={null} start_detached() ``` Start in detached mode

Returns

`Result<`[`Sandbox`](#instance-methods)`>` #### h.wait\_for\_status() ```rust theme={null} async fn wait_for_status(&self, status: SandboxStatus) -> MicrosandboxResult ``` Wait without a built-in timeout until this exact sandbox reaches `status`, returning a refreshed handle. Returns `SandboxReplaced` rather than rebinding to a same-name replacement. #### h.restart() ```rust theme={null} async fn restart(&self) -> MicrosandboxResult ``` Gracefully restart this exact sandbox with default options. #### h.restart\_with() ```rust theme={null} async fn restart_with(&self, options: RestartOptions) -> MicrosandboxResult ``` Restart with explicit force, shutdown timeout, and detached-start controls. See [`sb.restart_with()`](#sb-restart_with) for state behavior and defaults. #### h.destroy() ```rust theme={null} async fn destroy(&self) -> MicrosandboxResult<()> ``` Gracefully stop and remove this exact sandbox. A stale handle cannot destroy a replacement that reused the name. #### h.destroy\_with() ```rust theme={null} async fn destroy_with(&self, options: DestroyOptions) -> MicrosandboxResult<()> ``` Destroy with explicit force and shutdown-timeout controls. See [`sb.destroy_with()`](#sb-destroy_with) for defaults. #### h.status() ```rust theme={null} status() ``` Current status

Returns

[`SandboxStatus`](#sandboxstatus) #### h.stop() Different on cloud ```rust theme={null} stop() ``` Gracefully shut down and wait until stopped. Local waits up to ten seconds, then force-kills. Cloud waits up to six minutes and returns `SandboxStopTimedOut` on expiry without cancelling the accepted server-side stop.

Returns

`Result<()>` #### h.stop\_with\_timeout() Different on cloud ```rust theme={null} stop_with_timeout(timeout) ``` Same as `stop()` with an explicit timeout. Local force-kills on expiry; Cloud returns `SandboxStopTimedOut` while the accepted stop may continue. `Duration::ZERO` requests immediate force termination and is local-only.

Returns

`Result<()>` #### h.touch() Local-only ```rust theme={null} touch() ``` Explicitly refresh the sandbox idle timer

Returns

`Result<`[`SandboxTouchResult`](#sandboxtouchresult)`>` #### h.updated\_at() ```rust theme={null} updated_at() ``` Last update timestamp

Returns

`Option>` #### h.wait\_until\_stopped() ```rust theme={null} 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 theme={null} 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\
Secret name, usually the environment variable name.
#### secret.source() ```rust theme={null} 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 theme={null} 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\
Raw secret value held by the embedding process.
#### secret.placeholder() ```rust theme={null} 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\
Guest-visible placeholder string.
#### secret.allow\_host() ```rust theme={null} 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\
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()`](#sandbox-list) or [`Sandbox::list_with()`](#sandbox-list_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()`](#modification-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 | | ---------- | --------------------------------------------------------------------------------- | | `Created` | Persisted resource exists but has not started | | `Starting` | Runtime is booting and the guest agent is not ready yet | | `Running` | Guest agent is ready; `exec`, `shell`, and `fs` work | | `Draining` | Graceful shutdown in progress; existing commands finish and new ones are rejected | | `Paused` | VM is paused | | `Stopped` | VM shut down; configuration persisted; can be restarted | | `Crashed` | VM exited unexpectedly (kernel panic, OOM, etc.) |