Rust SDK Sandbox reference

See Overview for configuration examples and Lifecycle for state management.

Forking

Forking duplicates a running or paused local sandbox without saving a reusable snapshot. It shares memory through copy-on-write, keeps child writes private, and returns the source to its previous state. These methods are available on both Sandbox and SandboxHandle. Each child requires an unused name. See forking for examples, resource bindings, and backend limits.

fork() and fork_many()

let child = source.fork("experiment").fork().await?;
let outcomes = source.fork_many(["alice", "bob"]).fork().await?;

fork(name) returns a ForkBuilder; fork_many(names) returns a ForkManyBuilder. Call .fork().await to start the operation. Both builders accept .record_integrity(), .guest_flush(GuestFlush::Required), and explicit resource bindings. Import GuestFlush from microsandbox::snapshot; Auto is the default, and Skip skips optional guest writeback. The single-child builder also exposes .fork_with_progress() with the local feature.

ForkOutcome

Field	Meaning
`name`	Requested child name as a `String`
`result`	`MicrosandboxResult<Sandbox>` for that child

The outer result of ForkManyBuilder::fork() reports batch validation or capture failure. Match each outcome’s result to handle individual child failures. branch(), branch_many(), the builder .branch() terminal, .branch_with_progress(), and the BranchBuilder, BranchManyBuilder, and BranchOutcome types remain deprecated aliases. Batch results follow input order. Validation or capture failures fail the whole call; an individual startup failure appears in that child’s outcome, and successful siblings remain available. Stop successful children explicitly when finished.

Sandbox

Sandbox::builder()

fn builder(name: impl Into<String>) -> SandboxBuilder

Example

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

async fn get(name: &str) -> MicrosandboxResult<SandboxHandle>

Example

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

async fn list() -> MicrosandboxResult<SandboxPage>

Example

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

async fn list_with(
    configure: impl FnOnce(SandboxListBuilder) -> SandboxListBuilder,
) -> MicrosandboxResult<SandboxPage>

Return a configured page of sandboxes. Limits must be between 1 and 100. Labels are AND-matched before pagination.

Example

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

async fn remove(name: &str) -> MicrosandboxResult<()>

Example

Sandbox::remove("api").await?;

Delete a stopped sandbox by name. Locally, this removes the same state as sb.remove_persisted(); see 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()

async fn start(name: &str) -> MicrosandboxResult<Sandbox>

Example

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

Sandbox

Running sandbox.

Sandbox::start_detached()

async fn start_detached(name: &str) -> MicrosandboxResult<Sandbox>

Restart a stopped sandbox in detached mode. The sandbox survives after your process exits.

Parameters

name&str

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

Returns

Sandbox

Running sandbox.

Instance methods

sb.config()

fn config(&self) -> &SandboxConfig

Example

println!("{} MiB", sb.config().memory_mib);

Access the sandbox’s full configuration.

Returns

&SandboxConfig

Sandbox configuration.

sb.id()

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

async fn detach(self)

Example

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().

sb.drain()

async fn drain(&self) -> MicrosandboxResult<()>

Example

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

async fn request_drain(&self) -> MicrosandboxResult<()>

Request graceful drain and return once the request is sent. Pair with wait_until_stopped() when the caller needs stopped-state observation.

sb.fs()

fn fs(&self) -> SandboxFsOps<'_>

Example

sb.fs().write("/tmp/hello.txt", "hi").await?;

Get a filesystem handle for reading and writing files inside the running sandbox. See Filesystem for API details.

Returns

SandboxFsOps

Filesystem handle.

sb.kill()

async fn kill(&self) -> MicrosandboxResult<()>

Example

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() for graceful shutdown that gives the workload a chance to flush.

sb.kill_with_timeout()

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

async fn request_kill(&self) -> MicrosandboxResult<()>

Request force termination and return once the request is sent, without waiting for stopped-state observation.

sb.metrics()

async fn metrics(&self) -> MicrosandboxResult<SandboxMetrics>

Example

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

SandboxMetrics

Resource metrics.

sb.metrics_stream()

fn metrics_stream(&self, interval: Duration) -> impl Stream<Item = MicrosandboxResult<SandboxMetrics>>

Example

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

impl Stream<SandboxMetrics>

Async stream yielding a snapshot each interval.

sb.logs()

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

Example

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

opts&LogOptions

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

Returns

Vec<LogEntry>

Matching entries in chronological order.

sb.ping()

async fn ping(&self) -> MicrosandboxResult<SandboxPingResult>

Example

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

SandboxPingResult

Sandbox name and ping latency.

sb.touch()

async fn touch(&self) -> MicrosandboxResult<SandboxTouchResult>

Example

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

SandboxTouchResult

Sandbox name and agent activity sequence after the touch.

sb.modify()

fn modify(&self) -> SandboxModificationBuilder

Example

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() to preview or apply() to commit. Both return a 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_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. Changing a secret’s substitution rules, violation action, TLS identity requirement, or placeholder passthrough hosts requires a restart if the sandbox is running. Use .restart() to apply now, or .next_start() to save for the next start. Omitted options keep their current settings. See SandboxModificationBuilder for all setters and msb modify for the CLI.

Returns

SandboxModificationBuilder

Fluent builder; terminate with dry_run() or apply().

sb.name()

fn name(&self) -> &str

Get the sandbox name.

Returns

&str

Sandbox name, up to 128 UTF-8 bytes.

sb.owns_lifecycle()

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

async fn remove_persisted(&self) -> MicrosandboxResult<()>

Example

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). It does not perform additional cleanup. See Destroy or remove for what is deleted and which external resources are preserved.

sb.request_stop()

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() when the caller needs the terminal state.

sb.stop()

async fn stop(&self) -> MicrosandboxResult<()>

Example

sb.stop().await?;

Request graceful shutdown and wait indefinitely for the targeted run to become terminal and release runtime ownership. Success allows immediate removal without racing teardown. Cancelling the wait does not kill the sandbox or undo a delivered request. Paused or unreachable sandboxes return an error; resume explicitly or choose kill() when force termination is intended.

sb.stop_with_timeout()

async fn stop_with_timeout(&self, timeout: Duration) -> MicrosandboxResult<()>

Apply one total budget to graceful dispatch and completion. Expiry returns MicrosandboxError::StopTimeout without killing; Duration::ZERO expires before dispatch. A shutdown request already sent may complete later. Only explicit kill() requests force termination.

sb.stop_and_wait()

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

Example

let status = sb.stop_and_wait().await?;
println!("exited: {}", status.success());

Stop the sandbox and wait for runtime completion. An owned child-process handle supplies its actual exit status. Detached or connected handles retain the existing synthetic success status; use stop() or stop_with_timeout() when you only need completion.

Returns

ExitStatus

Exit code and success flag.

sb.wait()

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

Example

let status = sb.wait().await?;

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

Returns

ExitStatus

Exit code and success flag.

sb.wait_until_stopped()

async fn wait_until_stopped(&self) -> MicrosandboxResult<SandboxStopResult>

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

SandboxStopResult

Observed terminal sandbox state.

sb.wait_for_status()

async fn wait_for_status(&self, status: SandboxStatus) -> MicrosandboxResult<SandboxHandle>

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

async fn restart(&self) -> MicrosandboxResult<Sandbox>

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

async fn restart_with(&self, options: RestartOptions) -> MicrosandboxResult<Sandbox>

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

async fn destroy(&self) -> MicrosandboxResult<()>

Gracefully stop and remove this exact sandbox. Unlike remove_persisted(), destroy accepts a running sandbox, waits for it to shut down, and then deletes its persisted state.

sb.destroy_with()

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.

sb.restore_warnings()

async fn restore_warnings(&self) -> MicrosandboxResult<Vec<ExternalMountWarning>>

Return warnings for unavailable external filesystems and accepted restore mismatches. See External mounts for restore options. Each ExternalMountWarning contains:

Field	Type	Description
`guest_path`	`String`	Guest-visible mount path.
`reason`	`String`	Why the resource could not be reconstructed.
`stale_inodes`	`Vec<u64>`	Permanently invalid captured node IDs; empty when the whole export is unavailable.

SandboxBuilder

Builder for configuring a sandbox before creation. Obtained via Sandbox::builder(name). Every setter returns Self, so calls chain. Examples are shown on the methods where usage is non-obvious.

sandbox.slug()

fn slug(self, slug: impl Into<String>) -> 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<String>

Requested cloud slug.

sandbox.build()

async fn build(self) -> MicrosandboxResult<SandboxConfig>

Materialize the SandboxConfig without pulling an image or booting the sandbox. Validates fresh-boot configuration. Use Sandbox::restore() for snapshots. For booting, use create instead; call detached(true) first for background mode. Local create() keeps patches until image metadata is available. Cloud create() layers settings before sending the request; the cloud worker resolves image metadata.

Returns

SandboxConfig

Validated, ready-to-boot configuration.

sandbox.overlay()

fn overlay(self, patch: SandboxConfigPatch) -> Self

Apply sparse sandbox settings and create-time options after built-in and global defaults. Builder methods called after overlay take precedence over the patch; managed overrides are applied last. The builder uses the active backend’s cached configuration when build() or create() runs. Local creation stacks image defaults, global defaults, CLI/SDK patches, then managed overrides in one resolver before validation. Omitted fields inherit lower layers; explicit nullable clears survive image defaults. Cloud creation also applies user and managed settings, then rejects unsupported options before sending the request. build() returns a concrete SandboxConfig without pulling image metadata. On local creation, workdir: None inherits global defaults, then image defaults if global workdir is omitted. A concrete config cannot distinguish omission from an explicit clear; use direct builder create() to preserve sparse clears through image resolution. Managed overrides apply last in both paths. SandboxConfigPatch patches the SDK configuration. Its spec field is a SandboxSpecPatch for shared settings such as image, resources, and networking. Create-time options, including registry credentials, replacement settings, and the requested slug, live alongside spec.

Example

use microsandbox::{
    EnvVar, Sandbox, SandboxConfigPatch, SandboxResourcesPatch, SandboxSpecPatch,
};

let resources = SandboxResourcesPatch::new()
    .max_memory_mib(1024)
    .memory_mib(1024)
    .max_cpus(2)
    .cpus(2);

let patch = SandboxConfigPatch::new()
    .spec(
        SandboxSpecPatch::new()
            .resources(resources)
            .env(vec![EnvVar::new("MODE", "production")]),
    )
    .replace_existing(true);

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. Patch fields preserve the visibility of their source configuration fields, so ordinary fields and nested patches can be updated directly:

let mut patch = SandboxConfigPatch::new();
patch.spec.resources.cpus = Some(2);
patch.spec.runtime.cmd = Some(vec!["python".into(), "app.py".into()]);
patch.spec.runtime.workdir = Some(None); // Explicitly clear the working directory.
patch.registry_auth = Some(None); // Explicitly clear per-create credentials.

For nullable fields, None omits the update, Some(None) clears the value, and Some(Some(value)) sets it. Mergeable collections keep their merge/replacement state private and expose get_<field>() for borrowing their pending values. Ordinary fields have no generated getters. The collections’ get_<field>_mut() accessors edit pending values without cloning, initializing an absent collection empty in merge mode and preserving any existing replacement mode:

patch.spec.get_env_mut().push(EnvVar::new("REGION", "us-east"));
patch.spec.get_labels_mut().insert("team".into(), "platform".into());

These accessors edit pending values without deduplicating them. Use env_mut(...) to merge entries by name immediately, or replace_env_mut(...) to replace the collection. Fluent setters, replacements, clears, and overlay remain available, along with their _mut variants returning &mut Self. Use fluent setters to construct patches and if let for optional inputs. Once all overlays are composed, into_config() applies the patch to the type’s defaults:

use microsandbox::{SandboxConfigPatch, SandboxResourcesPatch, SandboxSpecPatch};

let cpus = Some(4);
let mut resources = SandboxResourcesPatch::new();
if let Some(cpus) = cpus {
    resources.cpus_mut(cpus);
}
let config = SandboxConfigPatch::new()
    .spec(
        SandboxSpecPatch::new()
            .name("example".into())
            .resources(resources),
    )
    .into_config();

into_config() does not load configuration files, consult a backend, or validate the result. Keep patches for SandboxBuilder::overlay() when creating a sandbox so backend and managed settings can still be layered. Use apply_to(&mut config) when updating an existing value. Both patches contain typed inputs. YAML loading, relative-path resolution, ${ENV} expansion, and snapshot lookup remain CLI or builder responsibilities. Runtime metadata stays internal, and create-time credentials and flags retain their existing serialization exclusions.

Migrating from the earlier patch types

The shared patch previously named SandboxConfigPatch is now SandboxSpecPatch. To use it with the builder, wrap it with SandboxConfigPatch::new().spec(spec_patch). Update direct field access such as patch.resources to patch.spec.resources when using the SDK patch. Existing configuration files and serialized sandbox specifications keep their shape.The generated patch model also 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`

Closure-based patch modifiers have been removed. Update Rust call sites to use direct field access or mutable collection accessors instead.Filesystem, script, image, and init values use SandboxSpecPatch, nested under SandboxConfigPatch.spec in the SDK. LocalConfig remains available as a deprecated alias of GlobalConfig.

sandbox.cpus()

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

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

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

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

Sandbox

Running sandbox.

sandbox.connect_or_create()

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

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() returns InvalidConfig.

Returns

MicrosandboxResult<Sandbox>

sandbox.detached()

fn detached(self, detached: bool) -> Self

Example

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

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

Example

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) with create() for new code so attached and detached creation use the same flow.

Returns

Sandbox

Running sandbox.

sandbox.disable_network()

fn disable_network(self) -> Self

Fully disable networking. No network interface is created.

sandbox.entrypoint()

fn entrypoint(self, cmd: impl IntoIterator<Item = impl Into<String>>) -> Self

Override the image ENTRYPOINT used by default-workload execution. Sandbox::exec_default combines it with the effective CMD. Literal Sandbox::exec, Sandbox::attach, and Sandbox::shell calls ignore it.

Parameters

cmdimpl IntoIterator

Entrypoint command and arguments.

sandbox.env()

fn env(self, key: impl Into<String>, value: impl Into<String>) -> Self

Set an environment variable visible to all commands. Can be called multiple times. Per-command env vars (via exec_with) are merged on top.

Parameters

keyimpl Into<String>

Variable name.

valueimpl Into<String>

Variable value.

sandbox.hostname()

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

Set the guest hostname.

Parameters

hostnameimpl Into<String>

Hostname.

sandbox.idle_timeout()

fn idle_timeout(self, secs: u64) -> Self

Auto-drain the sandbox after this many seconds of inactivity (no active exec sessions). Enforced on the host side.

Parameters

secsu64

Idle timeout in seconds.

sandbox.cmd()

fn cmd(self, cmd: impl IntoIterator<Item = impl Into<String>>) -> 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().

let sb = Sandbox::builder("worker")
    .image("example/worker:latest")
    .cmd(["worker.py", "--once"])
    .create()
    .await?;

sandbox.init()

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

Example

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 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. If none is found, it 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.

Parameters

cmdimpl Into<PathBuf>

Absolute path inside the guest, or “auto”.

sandbox.init_with()

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

Example

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, 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()

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

fn image_with(self, f: impl FnOnce(ImageBuilder) -> ImageBuilder) -> Self

Example

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

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

Override the sandbox process’s log verbosity.

Parameters

levelLogLevel

Log level.

sandbox.max_duration()

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

fn memory(self, size: impl Into<Mebibytes>) -> Self

Set the guest memory size. Physical pages are only allocated as the guest touches them, so this is a limit, not an upfront reservation. Default: 512 MiB.

Parameters

sizeimpl Into<Mebibytes>

Memory in MiB.

sandbox.max_memory()

fn max_memory(self, size: impl Into<Mebibytes>) -> 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()

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.guest_clock()

fn guest_clock(self, policy: GuestClockPolicy) -> Self

Control whether the sandbox clock follows the host. Full snapshots save this setting; restores inherit it unless overridden. Local-only. See guest clock for details.

Parameters

policyGuestClockPolicy

Sync (default) follows host time; Off stops host clock updates after boot.

sandbox.network()

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

Configure networking. See Networking for the full builder API.

Parameters

fNetworkBuilder

Configure the network.

sandbox.proxy()

fn proxy<P>(self, configure: impl FnOnce(OutboundProxyBuilder) -> P) -> Self
where
    P: OutboundProxyConfig

Configure the single proxy used for outbound sandbox connections. See Proxies for the protocol builders and examples.

sandbox.patch()

fn patch(self, f: impl FnOnce(PatchBuilder) -> PatchBuilder) -> Self

Modify the rootfs before the VM boots. Patches go into the writable layer; the base image is untouched. See PatchBuilder for the operations.

Parameters

fFnOnce(PatchBuilder)

Configure rootfs patches.

sandbox.port()

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

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

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

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

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

Control when the OCI image is pulled from the registry.

Parameters

policyPullPolicy

Pull behavior.

sandbox.registry()

fn registry(self, f: impl FnOnce(RegistryConfigBuilder) -> RegistryConfigBuilder) -> Self

Example

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

fRegistryConfigBuilder

Closure that configures registry auth and TLS options.

sandbox.replace()

fn replace(self) -> Self

If a sandbox with the same name already exists, stop it, remove it, and create a fresh one. Without this, creation fails on name conflict.

sandbox.script()

fn script(self, name: impl Into<String>, content: impl Into<String>) -> Self

Add a named script at /.msb/scripts/ inside the guest. Scripts are added to PATH and can be called by name via exec() or shell().

Parameters

nameimpl Into<String>

Script name (becomes the filename).

contentimpl Into<String>

Script content.

sandbox.secret()

fn secret(self, f: impl FnOnce(SecretBuilder) -> SecretBuilder) -> Self

Add a secret with full configuration. See Secrets for the builder API. Automatically enables TLS interception.

Parameters

fSecretBuilder

Configure the secret.

sandbox.secret_env()

fn secret_env(self, env_var: impl Into<String>, value: impl Into<String>, allowed_host: impl Into<String>) -> Self

Shorthand for adding a header-injected secret. Equivalent to .secret(|s| s.env(env_var).value(value).allow(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()

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

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

Parameters

shellimpl Into<String>

Shell path (e.g. “/bin/bash”).

sandbox.user()

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

Set the default guest user for all commands.

Parameters

userimpl Into<String>

User name or UID.

sandbox.volume()

fn volume(self, guest_path: impl Into<String>, f: impl FnOnce(MountBuilder) -> MountBuilder) -> Self

Add a volume mount. See Volumes for mount types.

Parameters

guest_pathimpl Into<String>

Mount point inside the sandbox.

fMountBuilder

Configure the mount.

sandbox.workdir()

fn workdir(self, path: impl Into<String>) -> 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()

fn append(self, path: impl Into<String>, content: impl Into<String>) -> 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()

fn copy_dir(self, src: impl Into<PathBuf>, dst: impl Into<String>, 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()

fn copy_file(
    self,
    src: impl Into<PathBuf>,
    dst: impl Into<String>,
    mode: Option<u32>,
    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()

fn file(
    self,
    path: impl Into<String>,
    content: impl Into<Vec<u8>>,
    mode: Option<u32>,
    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()

fn mkdir(self, path: impl Into<String>, mode: Option<u32>) -> 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()

fn remove(self, path: impl Into<String>) -> 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()

fn symlink(self, target: impl Into<String>, link: impl Into<String>, 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()

fn text(
    self,
    path: impl Into<String>,
    content: impl Into<String>,
    mode: Option<u32>,
    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()

async fn apply(self) -> MicrosandboxResult<SandboxModificationPlan>

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(), are saved and take effect on the next start. With 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.

Returns

SandboxModificationPlan

The applied plan, with applied: true and live resize outcomes in resize_status.

modification.cpus()

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

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

async fn dry_run(self) -> MicrosandboxResult<SandboxModificationPlan>

Example

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

SandboxModificationPlan

The plan, with applied: false.

modification.env()

fn env(self, key: impl Into<String>, value: impl Into<String>) -> 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()

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

Remove an environment variable. Same future-execs-only semantics as env().

Parameters

keyimpl Into<String>

Variable name to remove.

modification.label()

fn label(self, key: impl Into<String>, value: impl Into<String>) -> Self

Set a sandbox label. Can be called multiple times.

Parameters

keyimpl Into<String>

Label key.

valueimpl Into<String>

Label value.

modification.remove_label()

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

Remove a sandbox label.

Parameters

keyimpl Into<String>

Label key to remove.

modification.memory()

fn memory(self, size: impl Into<Mebibytes>) -> 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()

fn memory_mib(self, memory_mib: u32) -> Self

Set the desired effective guest memory in MiB. Same as memory() with an explicit unit.

Parameters

memory_mibu32

Memory in MiB.

modification.max_memory()

fn max_memory(self, size: impl Into<Mebibytes>) -> 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()

fn max_memory_mib(self, max_memory_mib: u32) -> Self

Set the desired boot-time maximum hotpluggable memory in MiB. Same as max_memory() with an explicit unit.

Parameters

max_memory_mibu32

Maximum memory in MiB.

modification.next_start()

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

fn restart(self) -> Self

Plan under restart-backed apply semantics. When the patch contains restart-required changes, apply() stops the sandbox, persists the config, and starts it again so the changes become active now.

modification.secret()

fn secret(self, f: impl FnOnce(SecretPatchBuilder) -> SecretPatchBuilder) -> Self

Example

use microsandbox::sandbox::SecretSource;

let plan = sb.modify()
    .secret(|s| s
        .env("API_KEY")
        .source(SecretSource::Env { var: "API_KEY".into() })
        .allow("api.example.com"))
    .apply()
    .await?;

Declare the desired state of one secret via a SecretPatchBuilder closure. The spec mirrors the create-time SecretBuilder vocabulary. The planner diffs it against the existing config to infer the change. A secret that does not exist yet is added, and material on an existing secret is rotated. Host or placeholder differences update those aspects. Declaring the same secret again replaces the earlier spec; removal is always explicit through remove_secret().

Parameters

fFnOnce(SecretPatchBuilder)

Closure declaring the secret’s desired state.

modification.remove_secret()

fn remove_secret(self, name: impl Into<String>) -> 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()

fn workdir(self, path: impl Into<String>) -> 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() for per-sandbox registry connection settings.

registry.auth()

auth(auth: RegistryAuth)

Set explicit credentials for the image registry

registry.insecure()

insecure()

Use plain HTTP for the registry

registry.ca_certs()

ca_certs(pem_data: Vec<u8>)

Trust additional PEM-encoded CA certificates

SandboxListBuilder

Fluent configuration passed to Sandbox::list_with(). Keep the labels and limit unchanged when continuing with a cursor.

list.limit()

limit(n)

Set a page size from 1 through 100

list.cursor()

cursor(cursor)

Continue after a previous page’s next_cursor

list.label()

label(key, value)

Require one label; repeated calls are AND-matched

list.labels()

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

config()

Parsed configuration

Returns

Result<SandboxConfig>

h.config_json()

config_json()

Raw JSON configuration

Returns

&str

h.connect()

connect()

Connect to a running sandbox; returns an error if it doesn’t respond within ten seconds

Returns

Result<Sandbox>

h.connect_with_timeout()

connect_with_timeout(timeout)

Same as connect() with an explicit timeout

Returns

Result<Sandbox>

h.connect_or_start()

async fn connect_or_start(&self) -> MicrosandboxResult<Sandbox>

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

async fn connect_or_start_detached(&self) -> MicrosandboxResult<Sandbox>

Behaves like 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()

created_at()

Creation timestamp

Returns

Option<DateTime<Utc>>

h.kill()

kill()

Force terminate and wait until stopped state is observed

Returns

Result<()>

h.kill_with_timeout()

kill_with_timeout(timeout)

Same as kill() with an explicit observation timeout

Returns

Result<()>

h.logs()

logs()

Read captured exec.log (works without starting)

Returns

Result<Vec<LogEntry>>

h.metrics()

metrics()

Point-in-time resource metrics

Returns

Result<SandboxMetrics>

h.modify()

modify()

Start planning a configuration change (works without starting; changes on a stopped sandbox persist for the next boot)

Returns

SandboxModificationBuilder

h.name()

name()

Sandbox name, up to 128 UTF-8 bytes

Returns

&str

h.id()

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

ping()

Check agent reachability without refreshing idle activity

Returns

Result<SandboxPingResult>

h.remove()

remove()

Delete sandbox and state

Returns

Result<()>

h.request_drain()

request_drain()

Request graceful drain without waiting

Returns

Result<()>

h.request_kill()

request_kill()

Request force termination without waiting

Returns

Result<()>

h.request_stop()

request_stop()

Request graceful shutdown without waiting

Returns

Result<()>

h.start()

start()

Start the sandbox. The returned local handle is attached; a cloud handle does not own the service-managed VM.

Returns

Result<Sandbox>

h.start_detached()

start_detached()

Start in detached mode

Returns

Result<Sandbox>

h.wait_for_status()

async fn wait_for_status(&self, status: SandboxStatus) -> MicrosandboxResult<SandboxHandle>

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

async fn restart(&self) -> MicrosandboxResult<Sandbox>

Gracefully restart this exact sandbox with default options.

h.restart_with()

async fn restart_with(&self, options: RestartOptions) -> MicrosandboxResult<Sandbox>

Restart with explicit force, shutdown timeout, and detached-start controls. See sb.restart_with() for state behavior and defaults.

h.destroy()

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

async fn destroy_with(&self, options: DestroyOptions) -> MicrosandboxResult<()>

Destroy with explicit force and shutdown-timeout controls. See sb.destroy_with() for defaults.

h.status()

status()

Current status

Returns

SandboxStatus

h.stop()

stop()

Wait indefinitely for graceful completion and release of the same runtime’s ownership. No implicit kill; cancellation stops only the wait.

Returns

Result<()>

h.stop_with_timeout()

stop_with_timeout(timeout)

Same completion contract as stop() under one total budget. Expiry returns MicrosandboxError::StopTimeout without killing; Duration::ZERO expires before dispatch.

Returns

Result<()>

h.touch()

touch()

Explicitly refresh the sandbox idle timer

Returns

Result<SandboxTouchResult>

h.updated_at()

updated_at()

Last update timestamp

Returns

Option<DateTime<Utc>>

h.wait_until_stopped()

wait_until_stopped()

Block until terminal state is observed

Returns

Result<SandboxStopResult>

SecretPatchBuilder

Used by secret()

Builder for one declarative secret change.

secret.env()

fn env(self, name: impl Into<String>) -> 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()

fn source(self, source: SecretSource) -> Self

Provide the secret material as a host-side 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

sourceSecretSource

Host-side reference for the secret material.

secret.value()

fn value(self, value: impl Into<String>) -> 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()

fn placeholder(self, placeholder: impl Into<String>) -> 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()

fn allow(self, host: impl Into<String>) -> 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 *.

secret.substitution()

fn substitution(self, value: SecretSubstitution) -> Self

Replace the enabled request locations for this secret. Omit this method to leave existing settings unchanged. At least one location must remain enabled. See SecretSubstitution for defaults and protocol limits.

secret.allow_placeholder_for()

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

Add a destination allowed to receive the unchanged placeholder where substitution does not apply. allow_passthrough_for() remains a deprecated alias. This does not grant access to the real secret.

secret.violation_action()

fn violation_action(self, value: SecretViolationAction) -> Self

Set the per-secret blocking action. See SecretViolationAction.

secret.require_tls_identity()

fn require_tls_identity(self, value: bool) -> Self

Set whether substitution requires a verified TLS identity. Omit this method to retain the existing setting.

Types

LogEntry

Returned by logs()

A single captured log entry returned by logs().

Field	Type	Description
timestamp	`DateTime<Utc>`	Wall-clock capture time on the host
source	`LogSource`	Where the chunk came from
session_id	`Option<u64>`	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(). All fields optional. LogOptions::default() returns everything for the default sources (Stdout + Stderr + Output).

Field	Type	Description
tail	`Option<usize>`	Show only the last N entries after other filters apply
since	`Option<DateTime<Utc>>`	Inclusive lower bound on entry timestamp
until	`Option<DateTime<Utc>>`	Exclusive upper bound on entry timestamp
sources	`Vec<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() or built via SandboxBuilder. Contains all settings used to create the sandbox.

Field	Type	Description
cpus	`u8`	Number of virtual CPUs
env	`Vec<(String, String)>`	Environment variables
idle_timeout_secs	`Option<u64>`	Idle timeout
image	`RootfsSource`	Root filesystem source (OCI, bind, or disk image)
max_duration_secs	`Option<u64>`	Maximum lifetime
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<Patch>`	Rootfs patches
scripts	`Vec<(String, String)>`	Named scripts
shell	`Option<String>`	Shell for `shell()` calls
volumes	`Vec<VolumeMount>`	Volume mounts
workdir	`Option<String>`	Default working directory

SandboxPage

One stable, newest-first page returned by Sandbox::list() or Sandbox::list_with().

Field	Type	Description
`sandboxes`	`Vec<SandboxHandle>`	Handles in this page
`next_cursor`	`Option<String>`	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>`	Planned changes, one entry per field or secret
conflicts	`Vec<ModificationConflict>`	Conflicts (`field` + `message`) that must be resolved before the patch can apply
warnings	`Vec<ModificationWarning>`	Non-fatal warnings (`field` + `message`) about the patch or current runtime capabilities, e.g. the future-execs-only env caveat
resize_status	`Vec<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`	Ordinary config change
`Secret`	`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<String>`	Previous safe visible state
after	`Option<String>`	New safe visible state
disposition	`ModificationDisposition`	When or whether the change can take effect
reason	`Option<String>`	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<String>`	Previous guest-visible reference or placeholder
after_ref	`Option<String>`	New guest-visible reference or placeholder
disposition	`ModificationDisposition`	When or whether the change can take effect
allow_hosts	`Vec<String>`	Allowed hosts after the requested change
reason	`Option<String>`	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()` 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().

Field	Type	Description
name	`String`	Sandbox name
status	`SandboxStatus`	Terminal status that was observed
exit_code	`Option<i32>`	Process exit code when available from an owned child process
signal	`Option<i32>`	Terminating signal when available from an owned child process
observed_at	`DateTime<Utc>`	When the terminal state was observed
source	`Option<String>`	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<u64>`	Guest-visible OCI upper filesystem used bytes when the protected reporter is available and fresh
upper_free_bytes	`Option<u64>`	Guest-visible OCI upper filesystem free bytes when the protected reporter is available and fresh
upper_host_allocated_bytes	`Option<u64>`	Host-allocated bytes for the writable OCI upper image when available
timestamp	`DateTime<Utc>`	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.)

⌘I

​Forking

​fork() and fork_many()

​ForkOutcome

​Sandbox

​Sandbox::builder()

​Sandbox::get()

​Sandbox::list()

​Sandbox::list_with()

​Sandbox::remove()

​Sandbox::start()

​Sandbox::start_detached()

​sb.config()

​sb.id()

​sb.detach()

​sb.drain()

​sb.request_drain()

​sb.fs()

​sb.kill()

​sb.kill_with_timeout()

​sb.request_kill()

​sb.metrics()

​sb.metrics_stream()

​sb.logs()

​sb.ping()

​sb.touch()

​sb.modify()

​sb.name()

​sb.owns_lifecycle()

​sb.remove_persisted()

​sb.request_stop()

​sb.stop()

​sb.stop_with_timeout()

​sb.stop_and_wait()

​sb.wait()

​sb.wait_until_stopped()

​sb.wait_for_status()

​sb.restart()

​sb.restart_with()

​sb.destroy()

​sb.destroy_with()

​sb.restore_warnings()

​SandboxBuilder

​sandbox.slug()

​sandbox.build()

​sandbox.overlay()

​sandbox.cpus()

​sandbox.max_cpus()

​sandbox.create()

​sandbox.connect_or_create()

​sandbox.detached()

​sandbox.create_detached()

​sandbox.disable_network()

​sandbox.entrypoint()

​sandbox.env()

​sandbox.hostname()

​sandbox.idle_timeout()

​sandbox.cmd()

​sandbox.init()

​sandbox.init_with()

​sandbox.image()

​sandbox.image_with()

​sandbox.log_level()

​sandbox.max_duration()

​sandbox.memory()

​sandbox.max_memory()

​sandbox.thp()

​sandbox.guest_clock()

​sandbox.network()

​sandbox.proxy()

​sandbox.patch()

​sandbox.port()

​sandbox.port_bind()

​sandbox.port_udp()

​sandbox.port_udp_bind()

​sandbox.pull_policy()

​sandbox.registry()

​sandbox.replace()

​sandbox.script()

​sandbox.secret()

​sandbox.secret_env()

Forking

fork() and fork_many()

ForkOutcome

Sandbox

Sandbox::builder()

Sandbox::get()

Sandbox::list()

Sandbox::list_with()

Sandbox::remove()

Sandbox::start()

Sandbox::start_detached()

sb.config()

sb.id()

sb.detach()

sb.drain()

sb.request_drain()

sb.fs()

sb.kill()

sb.kill_with_timeout()

sb.request_kill()

sb.metrics()

sb.metrics_stream()

sb.logs()

sb.ping()

sb.touch()

sb.modify()

sb.name()

sb.owns_lifecycle()

sb.remove_persisted()

sb.request_stop()

sb.stop()

sb.stop_with_timeout()

sb.stop_and_wait()

sb.wait()

sb.wait_until_stopped()

sb.wait_for_status()

sb.restart()

sb.restart_with()

sb.destroy()

sb.destroy_with()

sb.restore_warnings()

SandboxBuilder

sandbox.slug()

sandbox.build()

sandbox.overlay()

sandbox.cpus()

sandbox.max_cpus()

sandbox.create()

sandbox.connect_or_create()

sandbox.detached()

sandbox.create_detached()

sandbox.disable_network()

sandbox.entrypoint()

sandbox.env()

sandbox.hostname()

sandbox.idle_timeout()

sandbox.cmd()

sandbox.init()

sandbox.init_with()

sandbox.image()

sandbox.image_with()

sandbox.log_level()

sandbox.max_duration()

sandbox.memory()

sandbox.max_memory()

sandbox.thp()

sandbox.guest_clock()

sandbox.network()

sandbox.proxy()

sandbox.patch()

sandbox.port()

sandbox.port_bind()

sandbox.port_udp()

sandbox.port_udp_bind()

sandbox.pull_policy()

sandbox.registry()

sandbox.replace()

sandbox.script()

sandbox.secret()

sandbox.secret_env()