--- title: Sandbox description: Go 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. ## Functions #### m.CreateSandbox() ```go func CreateSandbox(ctx context.Context, name string, opts ...SandboxOption) (*Sandbox, error) ``` ```go sb, err := m.CreateSandbox(ctx, "api", m.WithImage("python:3.12"), m.WithMemory(512), m.WithCPUs(2), m.WithEnv(map[string]string{"PYTHONDONTWRITEBYTECODE": "1"}), ) if err != nil { return err } defer func() { _ = sb.Stop(context.Background()) _ = sb.Close() }() ``` Create and boot a new sandbox. Pulls the image if needed, boots the VM, starts the guest agent, and waits until it is ready to accept commands. Sandbox names must be non-empty and no longer than 128 UTF-8 bytes. The returned [`*Sandbox`](#methods) owns the VM process. Call `Close` (or `Stop` + `Close`) when done. See [Options](#options) for all configuration knobs.

Parameters

ctxcontext.Context

Cancels the boot operation only. Cancelling after this function returns has no effect on the running sandbox.

namestring

Sandbox name, up to 128 UTF-8 bytes.

opts...SandboxOption

Functional options applied in order.

Returns

*Sandbox

Running sandbox. Safe for concurrent use from multiple goroutines.

error

Typed *Error, see Error Handling.

#### m.GetSandbox() ```go func GetSandbox(ctx context.Context, name string) (*SandboxHandle, error) ``` ```go h, err := m.GetSandbox(ctx, "api") if err != nil { return err } fmt.Println(h.Status()) ``` Look up a sandbox by name and return a metadata handle without connecting to it. Returns an error with `Kind == ErrSandboxNotFound` if no such sandbox exists. The returned [`*SandboxHandle`](#sandboxhandle) exposes `Connect`, `Start`, `Stop`, `Kill`, `Remove`, `Ping`, `Touch`, `Metrics`, `Logs`, and snapshot methods.

Parameters

namestring

Sandbox name, up to 128 UTF-8 bytes.

Returns

*SandboxHandle

Metadata handle with status and lifecycle control.

#### m.ListSandboxes() ```go func ListSandboxes(ctx context.Context) (*SandboxPage, error) ``` ```go page, err := m.ListSandboxes(ctx) if err != nil { return err } for _, h := range page.Sandboxes { fmt.Printf("%s - %s\n", h.Name(), h.Status()) } ``` Return the first page of known sandboxes (running, stopped, draining, crashed), ordered newest first. The default page size is 20.

Returns

*SandboxPage

Handles in this page and an optional cursor for the next page.

#### m.ListSandboxesWith() ```go func ListSandboxesWith(ctx context.Context, options ...SandboxListOption) (*SandboxPage, error) ``` ```go page, err := m.ListSandboxesWith( ctx, m.WithListLimit(50), m.WithListLabels(map[string]string{"user.id": "alice"}), ) if err != nil { return err } if page.NextCursor != nil { nextPage, err := m.ListSandboxesWith( ctx, m.WithListLimit(50), m.WithListCursor(*page.NextCursor), m.WithListLabels(map[string]string{"user.id": "alice"}), ) } ``` Return a configured page of sandbox metadata. Label selectors are applied before pagination and AND-matched.

Parameters

options...SandboxListOption

WithListLimit, WithListCursor, and/or WithListLabels options.

Returns

*SandboxPage

Matching handles and an optional cursor for the next page.

#### m.StartSandbox() ```go func StartSandbox(ctx context.Context, name string) (*Sandbox, error) ``` ```go sb, err := m.StartSandbox(ctx, "api") ``` Restart a previously stopped sandbox. The VM reboots using the persisted configuration and returns a live [`*Sandbox`](#methods).

Parameters

namestring

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

Returns

*Sandbox

Running sandbox.

#### m.StartSandboxDetached() ```go func StartSandboxDetached(ctx context.Context, name string) (*Sandbox, error) ``` Boot a stopped sandbox in detached mode. The VM keeps running after the returned handle is released.

Parameters

namestring

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

Returns

*Sandbox

Running sandbox in detached mode.

#### m.RemoveSandbox() ```go func RemoveSandbox(ctx context.Context, name string) error ``` ```go err := m.RemoveSandbox(ctx, "api") ``` Delete a stopped sandbox by name. See [Remove](/sandboxes/lifecycle#remove) for the exact local deletion scope and the external resources that are preserved. Fails if the sandbox is still running; stop it first.

Parameters

namestring

Sandbox name, up to 128 UTF-8 bytes.

#### m.AllSandboxMetrics() Local-only ```go func AllSandboxMetrics(ctx context.Context) (map[string]*Metrics, error) ``` ```go all, err := m.AllSandboxMetrics(ctx) for name, metrics := range all { fmt.Printf("%s: %.1f%% CPU\n", name, metrics.CPUPercent) } ``` Return a point-in-time [`Metrics`](#metrics) snapshot for every running sandbox, keyed by sandbox name. Only running and draining sandboxes appear.

Returns

map[string]*Metrics

Per-sandbox metrics keyed by name.

Runtime installation and verification helpers are documented under [Runtime setup](/sdk/setup#install-and-verify). The Go-only version helpers are under [Inspect Go versions](/sdk/setup#inspect-go-versions). ## Sandbox A live sandbox connection that is safe for concurrent use. #### sb.Name() ```go func (s *Sandbox) Name() string ``` Return the sandbox name.

Returns

string

Sandbox name, up to 128 UTF-8 bytes.

#### sb.FS() ```go func (s *Sandbox) FS() *SandboxFSOps ``` ```go err := sb.FS().Write(ctx, "/tmp/hello.txt", []byte("hi")) ``` Return a filesystem accessor for reading and writing files inside the running sandbox. See [Filesystem](/sdk/go/filesystem) for the API.

Returns

*SandboxFSOps

Filesystem accessor.

#### sb.SSH() ```go func (s *Sandbox) SSH() *SandboxSSHOps ``` ```go client, err := sb.SSH().OpenClient(ctx) ``` Return an SSH accessor for opening a native in-process SSH client or preparing a reusable SSH server endpoint against the running sandbox. See [SSH](/sdk/go/ssh) for the API.

Returns

*SandboxSSHOps

SSH accessor.

#### sb.Logs() Local-only ```go func (s *Sandbox) Logs(ctx context.Context, opts LogOptions) ([]LogEntry, error) ``` ```go entries, err := sb.Logs(ctx, m.LogOptions{ Sources: []m.LogSource{m.LogSourceStdout, m.LogSourceStderr}, }) for _, e := range entries { fmt.Printf("[%s] %s", e.Source, e.Text()) } ``` Read persisted output from the sandbox's `exec.log`. Backed by an on-disk file, so it works for running and stopped sandboxes alike without guest-agent protocol traffic. The default sources are stdout and stderr; add `LogSourceOutput` for PTY-merged output or `LogSourceSystem` for runtime and kernel diagnostics. The same method exists on [`SandboxHandle`](#sandboxhandle) for callers that don't want to start the sandbox first.

Parameters

optsLogOptions

Filters: Tail, Since, Until, Sources. The zero value returns everything for the default stdout and stderr sources.

Returns

[]LogEntry

Matching entries in chronological order.

#### sb.LogStream() Limited on cloud ```go func (s *Sandbox) LogStream(ctx context.Context, opts LogStreamOptions) (*LogStreamHandle, error) ``` ```go stream, err := sb.LogStream(ctx, m.LogStreamOptions{Follow: true}) if err != nil { return err } defer stream.Close() for { entry, err := stream.Recv(ctx) if err != nil || entry == nil { break } fmt.Print(entry.Text()) } ``` Start a streaming log subscription against a live sandbox. Pass `LogStreamOptions{Follow: true}` to keep the stream open past current EOF and pick up new entries as they are written. Close the returned [`*LogStreamHandle`](#logstreamhandle) when done. Also available on [`SandboxHandle`](#sandboxhandle).

Parameters

optsLogStreamOptions

Sources, follow mode, and a Since or FromCursor start point.

Returns

*LogStreamHandle

Live subscription; call Recv in a loop.

#### sb.Ping() Local-only ```go func (s *Sandbox) Ping(ctx context.Context) (*SandboxPingResult, error) ``` ```go health, err := sb.Ping(ctx) if err != nil { return err } fmt.Printf("%s: %s\n", health.Name, health.Latency) ``` Check that the running sandbox's guest agent is reachable without refreshing idle activity. This sends `core.ping` and waits for `core.pong`; it does not start stopped sandboxes and returns an error if the sandbox is not running or `agentd` cannot respond. After upgrading from a runtime that predates protocol generation 6, restart already-running sandboxes so the guest agent understands the message.

Returns

*SandboxPingResult

Sandbox name and agent round-trip latency.

#### sb.Touch() Local-only ```go func (s *Sandbox) Touch(ctx context.Context) (*SandboxTouchResult, error) ``` ```go keepalive, err := sb.Touch(ctx) if err != nil { return err } fmt.Printf("%s: %d\n", keepalive.Name, keepalive.ActivitySeq) ``` Explicitly refresh the running sandbox's idle activity. This sends `core.touch`, receives `core.touched`, and advances the guest activity sequence used by the runtime idle-timeout monitor. It does not start stopped sandboxes and it does not bypass `MaxDuration`.

Returns

*SandboxTouchResult

Sandbox name and updated activity sequence.

#### sb.Modify() Local-only ```go func (s *Sandbox) Modify(ctx context.Context, opts ModifyOptions) (*SandboxModificationPlan, error) ``` ```go // Live resize: applies to the running VM when within the booted capacity plan, err := sb.Modify(ctx, m.ModifyOptions{CPUs: 4, MemoryMiB: 4096}) if err != nil { return err } for _, r := range plan.ResizeStatus { fmt.Printf("%s: %s -> %s (%s)\n", r.Resource, r.Requested, r.Actual, r.State) } // Preview a change without applying it preview, err := sb.Modify(ctx, m.ModifyOptions{MaxMemoryMiB: 16384, DryRun: true}) if err != nil { return err } for _, c := range preview.Changes { fmt.Printf("%s: %s\n", c.Field, c.Disposition) } // Make an env change active now by restarting _, err = sb.Modify(ctx, m.ModifyOptions{ Env: map[string]string{"MODE": "prod"}, Policy: m.ModificationPolicyRestart, }) // Grow the managed OCI root disk offline and restart _, err = sb.Modify(ctx, m.ModifyOptions{ RootDiskSizeMiB: 8192, Policy: m.ModificationPolicyRestart, }) // Add or rotate a host-environment secret; restart if it is newly added _, err = sb.Modify(ctx, m.ModifyOptions{ Secrets: map[string]m.SecretModifySpec{ "API_KEY": { Env: "API_KEY", AllowedHosts: []string{"api.example.com"}, }, }, Policy: m.ModificationPolicyRestart, }) // Remove an existing secret _, err = sb.Modify(ctx, m.ModifyOptions{ SecretsRemove: []string{"OLD_API_KEY"}, }) ``` Plan or apply a configuration change. The returned plan labels each change `"live"`, `"next start"`, `"requires restart"`, or `"unsupported"`, and apply is all-or-nothing. `CPUs` and `MemoryMiB` resize live within the [`WithMaxCPUs`](#withmaxcpus) / [`WithMaxMemory`](#withmaxmemory) ceilings; raising a ceiling requires a restart. `RootDiskSizeMiB` changes are offline: managed and flat OCI root disks grow only, tmpfs root disks can change in either direction on the next boot, and user-supplied disk images are rejected. Env and workdir changes affect future execs only. On a stopped sandbox, changes are saved for the next boot. Secret specs are keyed by stable secret name. Each `SecretModifySpec` selects at most one source—`Env`, `Value`, or `Store`—and may also set `Placeholder` and `AllowedHosts`; omitting a source updates only the other supplied fields. Plans expose only safe references and metadata; raw secret values never appear in a plan. Removal is explicit through `SecretsRemove`. A live CPU or memory resize can take a moment to settle. The new limits are enforced immediately, and the returned plan's `ResizeStatus` reports when the sandbox has finished adjusting. See [`SandboxModificationPlan`](#sandboxmodificationplan).

Parameters

optsModifyOptions

Requested changes plus Policy and DryRun. Zero-valued fields are left unchanged.

Returns

*SandboxModificationPlan

The modification plan, applied unless DryRun is set.

#### sb.Metrics() Local-only ```go func (s *Sandbox) Metrics(ctx context.Context) (*Metrics, error) ``` ```go metrics, err := sb.Metrics(ctx) fmt.Printf("cpu %.1f%% · mem %d MiB\n", metrics.CPUPercent, metrics.MemoryBytes/(1<<20)) ``` 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

*Metrics

Resource snapshot.

#### sb.MetricsStream() Local-only ```go func (s *Sandbox) MetricsStream(ctx context.Context, interval time.Duration) (*MetricsStreamHandle, error) ``` ```go stream, err := sb.MetricsStream(ctx, 500*time.Millisecond) if err != nil { return err } defer stream.Close() for { metrics, err := stream.Recv(ctx) if err != nil || metrics == nil { break } fmt.Printf("CPU: %.1f%%\n", metrics.CPUPercent) } ``` Start a streaming metrics subscription that delivers a [`Metrics`](#metrics) snapshot every `interval`. Sub-millisecond precision is rounded up; a zero or negative value uses the runtime minimum (~1 ms). Close the returned [`*MetricsStreamHandle`](#metricsstreamhandle) when done.

Parameters

intervaltime.Duration

Time between snapshots.

Returns

*MetricsStreamHandle

Live subscription; call Recv in a loop.

#### sb.Attach() ```go func (s *Sandbox) Attach(ctx context.Context, cmd string, args ...string) (int, error) ``` Bridge the caller's terminal to a process inside the sandbox for a fully interactive PTY session. Blocks until the process exits and returns its exit code. The caller's terminal must be a real TTY, so this is primarily useful for CLI tools, not library code.

Parameters

cmdstring

Command to run.

args...string

Command arguments.

Returns

int

Exit code of the process.

#### sb.AttachWith() ```go func (s *Sandbox) AttachWith(ctx context.Context, cmd string, args []string, opts ...AttachOption) (int, error) ``` ```go exitCode, err := sb.AttachWith(ctx, "bash", []string{"-l"}, m.WithAttachUser("dev"), m.WithAttachCwd("/app"), m.WithAttachEnv(map[string]string{"DEBUG": "1"}), m.WithAttachDetachKeys("ctrl-q"), ) ``` Same as [`Attach`](#sb-attach), but takes [`AttachOption`](#attachoption) values so the session can run as a different guest user, in a different working directory, with extra environment variables, or with custom detach keys.

Parameters

cmdstring

Command to run.

args[]string

Command arguments; may be nil.

opts...AttachOption

Attach options.

Returns

int

Exit code of the process.

#### sb.AttachShell() ```go func (s *Sandbox) AttachShell(ctx context.Context) (int, error) ``` Attach to the sandbox's default shell (configured via [`WithShell`](#withshell), defaults to `/bin/sh`). Blocks until the shell exits and returns its exit code.

Returns

int

Exit code of the shell.

#### sb.Stop() ```go func (s *Sandbox) Stop(ctx context.Context, opts ...StopOption) error ``` ```go err := sb.Stop(ctx, m.WithStopTimeout(30*time.Second)) ``` Gracefully shut down the sandbox and wait until stopped state is observed. Lets the workload finish writing any pending data to disk before it exits. Defaults to a ten-second graceful window before force-kill; pass [`WithStopTimeout`](#withstoptimeout) to change it.

Parameters

opts...StopOption

Graceful shutdown window, e.g. WithStopTimeout(30 * time.Second).

#### sb.RequestStop() ```go func (s *Sandbox) RequestStop(ctx context.Context) error ``` Request graceful shutdown and return once the request is sent, without waiting for the sandbox to reach stopped state. Pair with [`WaitUntilStopped`](#sb-waituntilstopped) to await termination. #### sb.Kill() Local-only ```go func (s *Sandbox) Kill(ctx context.Context, opts ...KillOption) error ``` ```go err := sb.Kill(ctx) ``` Force-terminate the sandbox with SIGKILL and wait until stopped state is observed. No graceful shutdown, so pending writes the workload hasn't `fsync`'d may be lost. Prefer [`Stop`](#sb-stop) for graceful shutdown. Defaults to a five-second observation window; pass [`WithKillTimeout`](#withkilltimeout) to change it.

Parameters

opts...KillOption

Stopped-state observation window.

#### sb.RequestKill() Local-only ```go func (s *Sandbox) RequestKill(ctx context.Context) error ``` Request force termination and return once the request is sent, without waiting for the sandbox to reach stopped state. #### sb.RequestDrain() Local-only ```go func (s *Sandbox) RequestDrain(ctx context.Context) error ``` Request a graceful drain and return once the request is sent. Existing commands run to completion while 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.WaitUntilStopped() ```go func (s *Sandbox) WaitUntilStopped(ctx context.Context) (*SandboxStopResult, error) ``` ```go result, err := sb.WaitUntilStopped(ctx) fmt.Printf("ended as %s\n", result.Status) ``` Block until the sandbox is observed in a terminal state, then return how it ended.

Returns

*SandboxStopResult

Terminal status, exit code, and signal.

#### sb.Detach() ```go func (s *Sandbox) Detach(ctx context.Context) error ``` ```go err := sb.Detach(ctx) // keeps running in the background ``` Release the Rust-side handle **without** stopping the VM. Use on sandboxes created with [`WithDetached`](#withdetached) once the caller is done with the handle but the sandbox should keep running in the background. After `Detach`, the handle is invalid; a subsequent `Close` returns an error with `Kind == ErrInvalidHandle`. Reconnect later with [`GetSandbox`](#m-getsandbox). #### sb.Close() Limited on cloud ```go func (s *Sandbox) Close() error ``` ```go defer sb.Close() ``` Release the Rust-side handle. Safe to call multiple times; the second call returns an error with `Kind == ErrInvalidHandle`. For a sandbox created with [`WithDetached`](#withdetached), `Close` stops the VM. Use [`Detach`](#sb-detach) instead to leave it running. #### sb.OwnsLifecycle() On cloud ```go func (s *Sandbox) OwnsLifecycle() (bool, error) ``` Report whether this handle owns the VM process. When `true`, closing or stopping the handle terminates the sandbox (attached mode); `false` means it is detached. The error return covers stale handles and FFI failures; use [`OwnsLifecycleOrFalse`](#sb-ownslifecycleorfalse) when you don't care.

Returns

bool

true if attached.

#### sb.OwnsLifecycleOrFalse() On cloud ```go func (s *Sandbox) OwnsLifecycleOrFalse() bool ``` Convenience wrapper around [`OwnsLifecycle`](#sb-ownslifecycle) that swallows the error and returns `false` on any failure. Suitable for log lines and best-effort branching.

Returns

bool

true if attached, false on detach or error.

## Options Functional options for creating and listing sandboxes. Map and slice options merge across repeated calls; single-value setters like [`WithImage`](#withimage) replace. #### WithListLimit() ```go func WithListLimit(limit uint32) SandboxListOption ``` Set the maximum number of sandboxes returned in a page. The limit must be between 1 and 100.

Parameters

limituint32

Maximum number of sandboxes in the page.

#### WithListCursor() ```go func WithListCursor(cursor string) SandboxListOption ``` Continue listing after a previous page's `NextCursor`. Keep the same label filters when requesting the next page.

Parameters

cursorstring

Opaque cursor returned by the previous page.

#### WithListLabels() ```go func WithListLabels(labels map[string]string) SandboxListOption ``` Require every supplied label. Repeated selectors are AND-matched.

Parameters

labelsmap[string]string

Label key-value pairs that every result must match.

#### WithImage() On cloud ```go func WithImage(image string) SandboxOption ``` Set the root filesystem source: an OCI image name, local directory path, or disk image path (e.g. `"python:3.12"`, `"docker.io/library/alpine"`). Required unless [`WithFromSnapshot`](#withfromsnapshot) is used. Use [`WithImageDisk`](#withimagedisk) when a disk-image root needs an explicit filesystem type.

Parameters

imagestring

OCI image, local path, or disk image.

#### WithOCIUpperSize() ```go func WithOCIUpperSize(mebibytes uint32) SandboxOption ``` Set the writable overlay upper size for an OCI image, in MiB. Valid only with an OCI image rootfs, not disk images or snapshots.

Parameters

mebibytesuint32

Upper layer size in MiB.

#### WithImageDisk() Local-only ```go func WithImageDisk(path string, fstype string) SandboxOption ``` Use a disk image as the root filesystem and optionally provide the inner filesystem type, e.g. `"ext4"`. The disk format is inferred from the path extension (`.qcow2`, `.raw`, or `.vmdk`).

Parameters

pathstring

Host path to the disk image.

fstypestring

Inner filesystem hint, empty to auto-detect.

--- #### WithFromSnapshot()

option

```go func WithFromSnapshot(pathOrName string) SandboxOption ``` Boot from a snapshot artifact by bare name or filesystem path. Mutually exclusive with [`WithImage`](#withimage). See [Snapshots](/sdk/go/snapshots).

Parameters

pathOrNamestring

Snapshot artifact path or bare name.

#### WithMemory() ```go func WithMemory(mebibytes uint32) SandboxOption ``` Set the guest memory limit in MiB. This is a limit, not an upfront reservation. Default: `512` MiB.

Parameters

mebibytesuint32

Memory in MiB.

#### WithMaxMemory() On cloud ```go func WithMaxMemory(mebibytes uint32) SandboxOption ``` Set the boot-time maximum hotpluggable guest memory in MiB. 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

mebibytesuint32

Maximum memory in MiB.

#### WithTHP() ```go func WithTHP(policy THPPolicy) SandboxOption ``` Select the guest transparent huge-page policy applied through the kernel command line at boot. Default: `THPMadvise`.

Parameters

policyTHPPolicy

THPAlways, THPMadvise, or THPNever.

#### WithCPUs() ```go func WithCPUs(cpus uint8) SandboxOption ``` Set the number of virtual CPUs. This is a limit, not a reservation. Default: `1`.

Parameters

cpusuint8

Number of vCPUs.

#### WithMaxCPUs() On cloud ```go func WithMaxCPUs(cpus uint8) SandboxOption ``` 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

cpusuint8

Maximum possible vCPUs.

#### WithWorkdir() ```go func WithWorkdir(path string) SandboxOption ``` Set the default working directory for all commands.

Parameters

pathstring

Absolute path inside the guest.

#### WithShell() ```go func WithShell(shell string) SandboxOption ``` Set the shell used by [`Shell`](/sdk/go/execution) and [`AttachShell`](#sb-attachshell). Defaults to `/bin/sh` on most images.

Parameters

shellstring

Shell path, e.g. "/bin/bash".

#### WithSecurityProfile() ```go func WithSecurityProfile(profile SecurityProfile) SandboxOption ``` Set the in-guest security profile. [`SecurityProfileRestricted`](#securityprofile) applies stronger hardening: sets `no_new_privs`, drops mount-admin capability from user commands, and forces `nosuid,nodev` on user mounts.

Parameters

profileSecurityProfile

Security profile.

#### WithEnv() ```go func WithEnv(env map[string]string) SandboxOption ``` Set environment variables visible to all commands. Called repeatedly, the maps merge; later keys overwrite earlier ones.

Parameters

envmap[string]string

Environment variables.

#### WithLabels() ```go func WithLabels(labels map[string]string) SandboxOption ``` Attach labels to the sandbox for metrics attribution and [`ListSandboxesWith`](#m-listsandboxeswith) filtering. Called repeatedly, the maps merge; later keys overwrite earlier ones. Keys must not use the reserved prefixes `sandbox.`, `microsandbox.`, or `service.`.

Parameters

labelsmap[string]string

Label key-value pairs.

#### WithLabel() ```go func WithLabel(key, value string) SandboxOption ``` Attach a single label. Shorthand for [`WithLabels`](#withlabels) with one entry.

Parameters

keystring

Label key.

valuestring

Label value.

#### WithHostname() On cloud ```go func WithHostname(hostname string) SandboxOption ``` Set the guest hostname.

Parameters

hostnamestring

Hostname.

#### WithUser() ```go func WithUser(user string) SandboxOption ``` Set the default guest user (UID or name) for all commands.

Parameters

userstring

User name or UID.

#### WithReplace() Local-only ```go func WithReplace() SandboxOption ``` Replace any existing sandbox with the same name. Sends SIGTERM, waits up to 10s for graceful exit, then escalates to SIGKILL. Without this, creation fails on name conflict. Use [`WithReplaceWithTimeout`](#withreplacewithtimeout) to set a different window. #### WithReplaceWithTimeout() Local-only ```go func WithReplaceWithTimeout(timeout time.Duration) SandboxOption ``` Like [`WithReplace`](#withreplace) but with a caller-specified timeout between SIGTERM and SIGKILL. Implies `WithReplace`; calling this alone is enough. A zero duration skips SIGTERM and SIGKILLs immediately.

Parameters

timeouttime.Duration

Grace period before SIGKILL.

#### WithDetached() ```go func WithDetached() SandboxOption ``` Create the sandbox in detached mode. The VM continues running after the Go process exits; reattach via [`GetSandbox`](#m-getsandbox). [`Close`](#sb-close) stops a detached sandbox; use [`Detach`](#sb-detach) to leave it running. #### WithEphemeral() ```go func WithEphemeral(ephemeral bool) SandboxOption ``` Mark whether the runtime should remove the sandbox's DB row, on-disk state, logs, and captured output after it reaches a terminal status.

Parameters

ephemeralbool

true to delete all state on termination.

#### WithEntrypoint() ```go func WithEntrypoint(cmd ...string) SandboxOption ``` Override the image ENTRYPOINT used by default-workload execution. Literal `Exec`, `Attach`, and `Shell` calls ignore it. This is the user workload, **not** the guest PID 1; for that, use [`WithInit`](#withinit) instead.

Parameters

cmd...string

Entrypoint command and arguments.

#### WithCmd() ```go func WithCmd(cmd ...string) SandboxOption ``` Override the image CMD used by default-workload execution. Calling `WithCmd()` with no arguments explicitly clears the image CMD. This describes durable configuration and does not execute anything during `CreateSandbox`. ```go sb, err := m.CreateSandbox(ctx, "worker", m.WithImage("example/worker:latest"), m.WithCmd("worker.py", "--once"), ) ``` #### WithInit() ```go func WithInit(cfg InitConfig) SandboxOption ``` ```go sb, err := m.CreateSandbox(ctx, "worker", m.WithImage("jrei/systemd-debian:12"), m.WithInit(m.Init.Auto()), ) ``` Hand off PID 1 inside the guest to a custom init binary after agentd finishes boot-time setup. Construct `cfg` via the [`Init`](#init) factory. See [Custom init system](/sandboxes/bootstrap#custom-init-system) for image picks and shutdown semantics.

Parameters

cfgInitConfig

Init specification.

#### WithLogLevel() ```go func WithLogLevel(level LogLevel) SandboxOption ``` Override the sandbox process's log verbosity. See [`LogLevel`](#loglevel).

Parameters

levelLogLevel

Log level.

#### WithQuietLogs() ```go func WithQuietLogs() SandboxOption ``` Suppress sandbox-level log output entirely. #### WithScripts() ```go func WithScripts(scripts map[string]string) SandboxOption ``` Add named scripts mounted at `/.msb/scripts/` inside the guest. Scripts are added to `PATH` and can be called by name. Called repeatedly, entries merge; later names overwrite earlier ones.

Parameters

scriptsmap[string]string

Script name to script content.

#### WithPullPolicy() ```go func WithPullPolicy(p PullPolicy) SandboxOption ``` Control when the OCI image is pulled from the registry. See [`PullPolicy`](#pullpolicy).

Parameters

pPullPolicy

Pull behavior.

#### WithMaxDuration() ```go func WithMaxDuration(d time.Duration) SandboxOption ``` Cap the sandbox's total runtime. When exceeded, the sandbox is drained and stopped. Zero means unlimited. Sub-second precision is rounded up to whole seconds. Enforced on the host side.

Parameters

dtime.Duration

Maximum lifetime.

#### WithIdleTimeout() ```go func WithIdleTimeout(d time.Duration) SandboxOption ``` Stop the sandbox after this much wall-clock time without exec activity. Zero means unlimited. Sub-second precision is rounded up to whole seconds.

Parameters

dtime.Duration

Idle timeout.

#### WithRegistryAuth() ```go func WithRegistryAuth(auth RegistryAuth) SandboxOption ``` Set credentials for pulling from a private OCI registry. See [`RegistryAuth`](#registryauth).

Parameters

authRegistryAuth

Registry credentials.

#### WithRegistryInsecure() ```go func WithRegistryInsecure() SandboxOption ``` Use plain HTTP for the registry instead of HTTPS, for local or self-hosted registries served without TLS such as `localhost:5050/my-app:latest`. The cloud backend rejects this override. #### WithRegistryCACerts() ```go func WithRegistryCACerts(pem []byte) SandboxOption ``` Trust additional PEM-encoded CA certificates when pulling, for registries served with a private certificate authority. Called repeatedly, the bundles accumulate. The cloud backend rejects this override.

Parameters

pem[]byte

PEM-encoded CA certificates.

#### WithRegistryCACertsPath() ```go func WithRegistryCACertsPath(path string) SandboxOption ``` Like [`WithRegistryCACerts`](#withregistrycacerts) but reads the PEM bundle from a file. The file is read when [`CreateSandbox`](#m-createsandbox) runs, which fails if it is unreadable. Called repeatedly, the bundles accumulate. The cloud backend rejects this override.

Parameters

pathstring

Path to a PEM file.

#### WithPorts() Local-only ```go func WithPorts(ports map[uint16]uint16) SandboxOption ``` Publish guest TCP ports onto host ports (map key = host port, value = guest port). The default host bind address is `127.0.0.1`. Called repeatedly, the maps merge.

Parameters

portsmap[uint16]uint16

Host port to guest port.

#### WithPortsUDP() Local-only ```go func WithPortsUDP(ports map[uint16]uint16) SandboxOption ``` Publish guest UDP ports onto host ports. The default host bind address is `127.0.0.1`.

Parameters

portsmap[uint16]uint16

Host port to guest port.

#### WithPortBindings() Local-only ```go func WithPortBindings(bindings ...PortBinding) SandboxOption ``` Publish ports on explicit host bind addresses, such as `0.0.0.0`. See [`PortBinding`](/sdk/go/networking#portbinding) for the type definition and UDP examples.

Parameters

bindings...PortBinding

Explicit bind-address port mappings.

#### WithNetwork() ```go func WithNetwork(net *NetworkConfig) SandboxOption ``` ```go sb, err := m.CreateSandbox(ctx, "api", m.WithImage("python"), m.WithNetwork(m.NetworkPolicy.FromProfiles(m.NetworkProfilePublic)), ) ``` Configure the network stack: profiles, custom rules, DNS, and TLS interception. Build via the [`NetworkPolicy`](/sdk/go/networking) factory or a [`*NetworkConfig`](/sdk/go/networking#networkconfig) literal. See [Networking](/sdk/go/networking).

Parameters

net*NetworkConfig

Network configuration.

#### WithSecrets() ```go func WithSecrets(secrets ...SecretEntry) SandboxOption ``` Append credential secrets to the sandbox. Secrets never enter the VM; the network proxy substitutes them at the transport layer. Build entries via the [`Secret`](/sdk/go/secrets) factory. See [Secrets](/sdk/go/secrets).

Parameters

secrets...SecretEntry

Secret injection entries.

#### WithPatches() ```go func WithPatches(patches ...PatchConfig) SandboxOption ``` ```go sb, err := m.CreateSandbox(ctx, "api", m.WithImage("python"), m.WithPatches( m.Patch.Mkdir("/app", m.PatchOptions{}), m.Patch.Text("/app/config.txt", "ready\n", m.PatchOptions{}), ), ) ``` Append rootfs patches applied before the VM boots. Patches go into the writable layer; the base image is untouched. Only compatible with OverlayFS rootfs (not disk images). Build entries via the [`Patch`](#patch) factory.

Parameters

patches...PatchConfig

Ordered rootfs patches.

#### WithMounts() ```go func WithMounts(mounts map[string]MountConfig) SandboxOption ``` ```go sb, err := m.CreateSandbox(ctx, "api", m.WithImage("python"), m.WithMounts(map[string]m.MountConfig{ "/data": m.Mount.Named("my-vol", m.MountOptions{}), "/tmp": m.Mount.Tmpfs(m.TmpfsOptions{SizeMiB: 256}), }), ) ``` Add volume mount configurations keyed by guest path. Build values via the [`Mount`](/sdk/go/volumes) factory. Called repeatedly, the maps merge; later entries overwrite earlier ones for the same guest path. See [Volumes](/sdk/go/volumes).

Parameters

mountsmap[string]MountConfig

Guest path to mount config.

#### WithStopTimeout() ```go func WithStopTimeout(timeout time.Duration) StopOption ``` Set how long [`Stop`](#sb-stop) waits for graceful shutdown before force-killing. Default: 10 seconds. This is a `StopOption`, not a `SandboxOption`. Pass it to [`Stop`](#sb-stop).

Parameters

timeouttime.Duration

Graceful shutdown window.

#### WithKillTimeout() ```go func WithKillTimeout(timeout time.Duration) KillOption ``` Set how long [`Kill`](#sb-kill) waits for stopped-state observation. Default: 5 seconds. This is a `KillOption`, pass it to [`Kill`](#sb-kill).

Parameters

timeouttime.Duration

Observation window.

The setup-only `WithSkipDownload()` option is documented under [Runtime setup](/sdk/setup#customize-installation).

Attach options

#### WithAttachCwd() ```go func WithAttachCwd(path string) AttachOption ``` Set the working directory for the attached session. Defaults to the sandbox's workdir.

Parameters

pathstring

Absolute path inside the guest.

#### WithAttachUser() ```go func WithAttachUser(user string) AttachOption ``` Run the attached session as the given guest user instead of the sandbox's default user (set via [`WithUser`](#withuser)).

Parameters

userstring

Guest user as a UID or name, optionally user:group.

#### WithAttachEnv() ```go func WithAttachEnv(env map[string]string) AttachOption ``` Add environment variables for the attached session, merged on top of the sandbox's env. Called repeatedly, maps merge; later keys overwrite earlier ones.

Parameters

envmap[string]string

Environment variables to set.

#### WithAttachDetachKeys() ```go func WithAttachDetachKeys(keys string) AttachOption ``` Set the key sequence that detaches from the session without stopping it. Uses Docker-style syntax: `ctrl-]` (the default), `ctrl-p,ctrl-q`, or a single character like `q`.

Parameters

keysstring

Detach key sequence.

## Patch

Produces PatchConfig for WithPatches()

Factory for [`PatchConfig`](#patchconfig) values. #### Patch.Text() ```go func (patchFactory) Text(path, content string, opts PatchOptions) PatchConfig ``` Write UTF-8 text content at `path`.

Parameters

pathstring

Absolute path inside the guest.

contentstring

Text content.

optsPatchOptions

Mode and Replace.

#### Patch.Append() ```go func (patchFactory) Append(path, content string) PatchConfig ``` Append `content` to an existing file at `path`. If the file lives in a lower image layer, it is copied up first.

Parameters

pathstring

Absolute path inside the guest.

contentstring

Text to append.

#### Patch.Mkdir() On cloud ```go func (patchFactory) Mkdir(path string, opts PatchOptions) PatchConfig ``` Create a directory. Idempotent. Only `opts.Mode` is honored; `Replace` is ignored.

Parameters

pathstring

Absolute path inside the guest.

optsPatchOptions

Only Mode applies.

#### Patch.Remove() ```go func (patchFactory) Remove(path string) PatchConfig ``` Delete a file or directory at `path`. Idempotent.

Parameters

pathstring

Absolute path inside the guest.

#### Patch.Symlink() ```go func (patchFactory) Symlink(target, link string, opts PatchOptions) PatchConfig ``` Create a symlink at `link` pointing to `target`. Only `opts.Replace` is honored.

Parameters

targetstring

What the symlink points to.

linkstring

Absolute path of the symlink itself.

optsPatchOptions

Only Replace applies.

#### Patch.CopyFile() On cloud ```go func (patchFactory) CopyFile(src, dst string, opts PatchOptions) PatchConfig ``` Copy a single host file at `src` into the guest rootfs at `dst`.

Parameters

srcstring

Host source file.

dststring

Absolute destination path inside the guest.

optsPatchOptions

Mode and Replace.

#### Patch.CopyDir() On cloud ```go func (patchFactory) CopyDir(src, dst string, opts PatchOptions) PatchConfig ``` Recursively copy a host directory at `src` into the guest rootfs at `dst`. Only `opts.Replace` is honored.

Parameters

srcstring

Host source directory.

dststring

Absolute destination path inside the guest.

optsPatchOptions

Only Replace applies.

## Init

Produces InitConfig for WithInit()

Factory for [`InitConfig`](#initconfig) values. #### Init.Auto() ```go func (initFactory) Auto() InitConfig ``` ```go m.WithInit(m.Init.Auto()) ``` Use a known init at the start of the image ENTRYPOINT when present, preserving attached init-entrypoint commands; otherwise delegate to agentd to probe common init paths (`/sbin/init`, `/lib/systemd/systemd`, ...) inside the guest.

Returns

InitConfig

Auto-detect init config.

#### Init.Cmd() ```go func (initFactory) Cmd(cmd string, opts InitOptions) InitConfig ``` ```go m.WithInit(m.Init.Cmd( "/lib/systemd/systemd", m.InitOptions{ Args: []string{"--unit=multi-user.target"}, Env: map[string]string{"container": "microsandbox"}, }, )) ``` Specify the init binary explicitly with optional argv and env. `cmd` must be an absolute path inside the guest rootfs.

Parameters

cmdstring

Absolute path to the init binary inside the guest.

optsInitOptions

Argv and env.

## SandboxHandle

Returned by GetSandbox() · ListSandboxes() · ListSandboxesWith()

A sandbox metadata and lifecycle handle that does not require an active guest-agent connection. #### h.Name() ```go Name() ``` Sandbox name, up to 128 UTF-8 bytes

Returns

`string` #### h.Status() ```go Status() ``` Last-known lifecycle status

Returns

[`SandboxStatus`](#sandboxstatus) #### h.ConfigJSON() ```go ConfigJSON() ``` Raw JSON configuration

Returns

`string` #### h.Config() ```go Config() ``` Parsed configuration

Returns

`(*`[`SandboxConfig`](#sandboxconfig)`, error)` #### h.CreatedAt() ```go CreatedAt() ``` Creation time, zero value if unknown

Returns

`time.Time` #### h.UpdatedAt() ```go UpdatedAt() ``` Last-update time, zero value if unknown

Returns

`time.Time` #### h.Refresh() ```go Refresh(ctx) ``` Fresh handle for the same name

Returns

`(*SandboxHandle, error)` #### h.Ping() ```go Ping(ctx) ``` Check agent reachability without refreshing idle activity; does not start stopped sandboxes

Returns

`(*`[`SandboxPingResult`](#sandboxpingresult)`, error)` #### h.Touch() ```go Touch(ctx) ``` Explicitly refresh idle activity; does not start stopped sandboxes

Returns

`(*`[`SandboxTouchResult`](#sandboxtouchresult)`, error)` #### h.Modify() ```go Modify(ctx, opts) ``` Plan or apply a configuration change; same [`ModifyOptions`](#modifyoptions) as [`Modify()`](#sb-modify). Does not start stopped sandboxes; changes persist for the next boot

Returns

`(*`[`SandboxModificationPlan`](#sandboxmodificationplan)`, error)` #### h.Metrics() ```go Metrics(ctx) ``` Point-in-time resource metrics

Returns

`(*`[`Metrics`](#metrics)`, error)` #### h.Logs() ```go Logs(ctx, opts) ``` Read captured `exec.log` (works without starting)

Returns

`([]`[`LogEntry`](#logentry)`, error)` #### h.LogStream() ```go LogStream(ctx, opts) ``` Stream captured output

Returns

`(*`[`LogStreamHandle`](#logstreamhandle)`, error)` #### h.Connect() ```go Connect(ctx) ``` Reattach to the running sandbox

Returns

`(*`[`Sandbox`](#methods)`, error)` #### h.Start() ```go Start(ctx) ``` Boot a stopped sandbox in attached mode

Returns

`(*`[`Sandbox`](#methods)`, error)` #### h.StartDetached() ```go StartDetached(ctx) ``` Boot a stopped sandbox in detached mode

Returns

`(*`[`Sandbox`](#methods)`, error)` #### h.Stop() ```go Stop(ctx, opts...) ``` Graceful shutdown; accepts [`StopOption`](#withstoptimeout)

Returns

`error` #### h.RequestStop() ```go RequestStop(ctx) ``` Async stop request

Returns

`error` #### h.Kill() ```go Kill(ctx, opts...) ``` Force terminate; accepts [`KillOption`](#withkilltimeout)

Returns

`error` #### h.RequestKill() ```go RequestKill(ctx) ``` Async kill request

Returns

`error` #### h.RequestDrain() ```go RequestDrain(ctx) ``` Async drain request

Returns

`error` #### h.WaitUntilStopped() ```go WaitUntilStopped(ctx) ``` Block until terminal state

Returns

`(*`[`SandboxStopResult`](#sandboxstopresult)`, error)` #### h.Remove() ```go Remove(ctx) ``` Delete sandbox and persisted state

Returns

`error` #### h.Snapshot() ```go Snapshot(ctx, name) ``` Snapshot a stopped sandbox under a bare name

Returns

`(*SnapshotArtifact, error)` ## MetricsStreamHandle

Returned by MetricsStream()

Live metrics subscription. Call `Close` to release Rust-side resources. #### metricsStream.Recv() ```go Recv(ctx) ``` Block until the next snapshot arrives. Returns `(nil, nil)` when the stream ends (sandbox exited)

Returns

`(*`[`Metrics`](#metrics)`, error)` #### metricsStream.Close() ```go Close() ``` Stop the stream and release Rust-side resources

Returns

`error` ## LogEntry

Returned by Logs() · LogStream()

A single captured log entry. #### entry.Source [`LogSource`](#logsource) Origin of the captured data #### entry.SessionID `*uint64` Relay-monotonic session id; nil for system entries #### entry.Timestamp `time.Time` Wall-clock capture time on the host #### entry.Data `[]byte` The captured bytes #### entry.Cursor `string` Opaque resume token; pass to [`LogStreamOptions.FromCursor`](#logstreamoptions) #### entry.Text() ```go Text() ``` Captured bytes as a string

Returns

`string` ## LogStreamHandle

Returned by LogStream()

Live log subscription. Call `Close` to release Rust-side resources. #### logStream.Recv() ```go Recv(ctx) ``` Block until the next entry arrives. Returns `(nil, nil)` when the stream ends

Returns

`(*`[`LogEntry`](#logentry)`, error)` #### logStream.Close() ```go Close() ``` Stop the stream and release Rust-side resources

Returns

`error` ## Types ### SandboxPingResult

Returned by Ping()

Agent reachability result. | Field | Type | Description | |-------|------|-------------| | Name | `string` | Sandbox name | | Latency | `time.Duration` | Round-trip latency | ### SandboxTouchResult

Returned by Touch()

Explicit idle-refresh result. | Field | Type | Description | |-------|------|-------------| | Name | `string` | Sandbox name | | ActivitySeq | `uint64` | Monotonic activity sequence after the touch | ### ModifyOptions

Used by Modify()

A requested sandbox modification. Zero-valued fields are left unchanged (`0` is not a valid CPU, memory, or disk size). | Field | Type | Description | |-------|------|-------------| | CPUs | `uint8` | Desired effective vCPU count. Live when within the booted `MaxCPUs` | | MaxCPUs | `uint8` | Boot-time maximum possible vCPUs (restart-backed) | | MemoryMiB | `uint32` | Desired effective guest memory in MiB. Live when within the booted `MaxMemoryMiB` | | MaxMemoryMiB | `uint32` | Boot-time maximum hotpluggable memory in MiB (restart-backed) | | RootDiskSizeMiB | `uint32` | Desired root disk size in MiB. Managed and flat OCI disks are grow-only; applies on restart or next start | | Env | `map[string]string` | Environment variables to set for future execs | | EnvRemove | `[]string` | Environment variable keys to remove | | Labels | `map[string]string` | Labels to set | | LabelsRemove | `[]string` | Label keys to remove | | Workdir | `string` | Working directory for future execs | | Secrets | `map[string]SecretModifySpec` | Desired secret specs keyed by stable secret name | | SecretsRemove | `[]string` | Secret names to remove explicitly | | Policy | `ModificationPolicy` | `ModificationPolicyNoRestart` (default) applies only changes that can complete without restarting; `ModificationPolicyNextStart` persists changes for the next start without mutating a running VM; `ModificationPolicyRestart` restarts if needed so restart-required changes become active now | | DryRun | `bool` | Compute the plan without applying anything | ### SecretModifySpec

Used by Modify()

Desired state for one secret. `Env`, `Value`, and `Store` are mutually exclusive sources. Leave all three empty to update only the placeholder or allowed hosts. | Field | Type | Description | |-------|------|-------------| | Env | `string` | Host environment variable to resolve when applying the modification | | Value | `string` | Raw secret value. Stored in the durable sandbox config until replaced by a source reference | | Store | `string` | Reserved for a host-side secret store reference; currently unsupported | | Placeholder | `string` | Explicit guest-visible placeholder. New secrets default to `$MSB_` | | AllowedHosts | `[]string` | Desired allowed host patterns. A new secret requires at least one; an empty slice leaves existing hosts unchanged | ### SandboxModificationPlan

Returned by Modify()

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` | 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 | | Changes | `[]PlannedChange` | Planned changes, one entry per field or secret (see below) | | Conflicts | `[]ModificationConflict` | Conflicts (`Field` + `Message`) that must be resolved before the patch can apply | | Warnings | `[]ModificationWarning` | Non-fatal warnings (`Field` + `Message`), e.g. the future-execs-only env caveat | | ResizeStatus | `[]ResourceResizeStatus` | Live resource resize outcomes, populated by apply when a live change ran (see below) | `PlannedChange` is one planned entry. `Kind` is `"config"` or `"secret"`; config entries carry `Before` / `After` while secret entries carry `Name`, `BeforeRef` / `AfterRef` (guest-visible references, values are omitted by construction), and `AllowHosts`: | Field | Type | Description | |-------|------|-------------| | Kind | `string` | `"config"` or `"secret"` | | Field | `string` | Config field being changed; always `"secret"` for secret entries | | Name | `string` | Secret name (secret entries only) | | Change | `string` | `"added"`, `"updated"`, or `"removed"` for config; `"added"`, `"rotated"`, `"removed"`, `"renamed"`, `"hosts updated"`, or `"placeholder updated"` for secrets | | Before / After | `*string` | Previous / new visible state (config entries) | | BeforeRef / AfterRef | `*string` | Previous / new guest-visible reference (secret entries) | | Disposition | `string` | `"live"`, `"next start"`, `"requires restart"`, or `"unsupported"` | | AllowHosts | `[]string` | Allowed hosts after the requested change (secret entries) | | Reason | `*string` | Human-readable reason for the classification, when useful | `ResourceResizeStatus` reports runtime convergence for a live resize; enforcement applies immediately, the guest converges asynchronously: | Field | Type | Description | |-------|------|-------------| | Resource | `string` | `"cpus"` or `"memory"` | | Requested | `string` | Requested value | | Actual | `string` | Actual value observed in the guest/runtime | | Enforced | `string` | Host/VMM-enforced value | | State | `string` | `"applied"` when requested, actual, and enforced match; `"converging"` while the guest is still onlining CPUs or plugging memory; `"guest-refused"` when the guest would not cooperate (the host enforces the new limit anyway); `"accepted"` or `"failed"` otherwise | ### SandboxPage One stable, newest-first page returned by [`ListSandboxes`](#m-listsandboxes) or [`ListSandboxesWith`](#m-listsandboxeswith). Pass `NextCursor` back through `WithListCursor` with the same filters to continue. | Field | Type | Description | |-------|------|-------------| | `Sandboxes` | `[]*SandboxHandle` | Handles in this page | | `NextCursor` | `*string` | Opaque continuation cursor, or `nil` on the final page | ### SandboxListOption Functional options accepted by [`ListSandboxesWith`](#m-listsandboxeswith). ### SandboxConfig

Populated by SandboxOption · parsed by SandboxHandle.Config()

The full configuration of a sandbox. Most callers build a sandbox via `CreateSandbox(ctx, name, ...opts)`; `SandboxConfig` is exported for callers that prefer to construct a value directly. | Field | Type | Description | |-------|------|-------------| | Name | `string` | Sandbox name, up to 128 UTF-8 bytes | | Image | `string` | OCI image, local path, or disk image | | ImageFstype | `string` | Optional inner filesystem type for disk-image roots | | OCIUpperSizeMiB | `uint32` | Writable overlay upper size for OCI image roots | | Snapshot | `string` | Snapshot artifact path or bare name; mutually exclusive with `Image` | | MemoryMiB | `uint32` | Guest memory in MiB | | CPUs | `uint8` | Virtual CPUs | | MaxMemoryMiB | `uint32` | Boot-time maximum hotpluggable memory in MiB | | MaxCPUs | `uint8` | Boot-time maximum possible virtual CPUs | | Workdir | `string` | Default working directory | | Shell | `string` | Shell binary used by `Shell` calls | | SecurityProfile | [`SecurityProfile`](#securityprofile) | In-guest security profile | | Hostname | `string` | Guest hostname | | User | `string` | Default guest user | | Replace | `bool` | Replace existing sandbox with same name | | ReplaceWithTimeout | `*time.Duration` | Timeout between SIGTERM and SIGKILL (implies `Replace`) | | Env | `map[string]string` | Environment variables | | Labels | `map[string]string` | Labels for metrics attribution and filtering | | Detached | `bool` | If `true`, sandbox survives after the process exits | | Ephemeral | `bool` | If `true`, all state is removed on termination | | Entrypoint | `[]string` | Override the image ENTRYPOINT used by default-workload execution | | Cmd | `[]string` | Override the image CMD used by default-workload execution; an empty non-nil slice clears CMD | | Init | [`*InitConfig`](#initconfig) | Hand PID 1 off to a guest init binary | | LogLevel | [`LogLevel`](#loglevel) | Sandbox log verbosity override | | QuietLogs | `bool` | Suppress sandbox-level log output | | Scripts | `map[string]string` | Named scripts mounted at `/.msb/scripts/` | | PullPolicy | [`PullPolicy`](#pullpolicy) | Image pull behaviour | | MaxDuration | `time.Duration` | Maximum sandbox lifetime | | IdleTimeout | `time.Duration` | Idle timeout | | RegistryAuth | [`*RegistryAuth`](#registryauth) | Private registry credentials | | Ports | `map[uint16]uint16` | Host to guest TCP port mappings | | PortsUDP | `map[uint16]uint16` | Host to guest UDP port mappings | | PortBindings | [`[]PortBinding`](/sdk/go/networking#portbinding) | Port mappings with explicit bind addresses | | Network | [`*NetworkConfig`](/sdk/go/networking#networkconfig) | Network policy and configuration | | Secrets | [`[]SecretEntry`](/sdk/go/secrets#secretentry) | Secret injection entries | | Patches | [`[]PatchConfig`](#patchconfig) | Rootfs modifications applied before boot | | Volumes | `map[string]MountConfig` | Volume mounts keyed by guest path | ### SandboxOption

Consumed by CreateSandbox()

```go type SandboxOption func(*SandboxConfig) ``` A functional option for [`CreateSandbox`](#m-createsandbox). Every `WithX` helper in the [Options](#options) section returns one. The lifecycle setters [`WithStopTimeout`](#withstoptimeout) and [`WithKillTimeout`](#withkilltimeout) return distinct `StopOption` / `KillOption` types passed to [`Stop`](#sb-stop) and [`Kill`](#sb-kill) instead. ### AttachConfig

Populated by AttachOption

Configures a single [`AttachWith`](#sb-attachwith) call. Most callers set fields through the `WithAttach*` functional options; `AttachConfig` is exported for parity with the other SDKs' config types. | Field | Type | Description | |-------|------|-------------| | `Cwd` | `string` | Working directory inside the guest; defaults to the sandbox workdir | | `User` | `string` | Guest user (UID or name, optionally `user:group`); defaults to the sandbox user | | `Env` | `map[string]string` | Environment variables merged on top of the sandbox env | | `DetachKeys` | `string` | Detach key sequence; defaults to `ctrl-]` | ### AttachOption

Accepted by sb.AttachWith()

```go type AttachOption func(*AttachConfig) ``` A functional option that mutates an [`AttachConfig`](#attachconfig). Construct them with the `WithAttach*` functions below. ### Metrics

Returned by Metrics() · MetricsStream() · AllSandboxMetrics()

Point-in-time resource usage snapshot. | Field | Type | Description | |-------|------|-------------| | CPUPercent | `float64` | CPU usage as a percentage | | VCPUTimeNs | `uint64` | Cumulative vCPU time in nanoseconds | | MemoryBytes | `uint64` | Current memory usage in bytes | | MemoryAvailableBytes | `*uint64` | Guest-reported available memory when known | | MemoryHostResidentBytes | `*uint64` | Host RSS backing the guest when known | | MemoryLimitBytes | `uint64` | Memory limit in bytes | | DiskReadBytes | `uint64` | Total bytes read from disk since boot | | DiskWriteBytes | `uint64` | Total bytes written to disk since boot | | NetRxBytes | `uint64` | Total bytes received over the network since boot | | NetTxBytes | `uint64` | Total bytes sent over the network since boot | | UpperUsedBytes | `*uint64` | Guest-visible OCI upper filesystem used bytes when the protected reporter is available and fresh | | UpperFreeBytes | `*uint64` | Guest-visible OCI upper filesystem free bytes when the protected reporter is available and fresh | | UpperHostAllocatedBytes | `*uint64` | Host-allocated bytes for the writable OCI upper image when available | | Uptime | `time.Duration` | Time since the sandbox was created | ### SandboxStopResult

Returned by WaitUntilStopped()

Describes a terminal sandbox state observed by [`WaitUntilStopped`](#sb-waituntilstopped). | Field | Type | Description | |-------|------|-------------| | Name | `string` | Sandbox name | | Status | [`SandboxStatus`](#sandboxstatus) | Terminal status (`stopped` or `crashed`) | | ExitCode | `*int` | Process exit code when known | | Signal | `*int` | Terminating signal when known | | ObservedAt | `time.Time` | When the terminal state was observed | | Source | `*string` | Origin of the stop observation when known | ### SandboxStatus

Used by SandboxHandle.Status() · SandboxStopResult.Status

```go type SandboxStatus string ``` | Constant | Value | Description | |----------|-------|-------------| | `SandboxStatusRunning` | `"running"` | Guest agent is ready; `Exec`, `Shell`, `FS` work | | `SandboxStatusStopped` | `"stopped"` | VM shut down; configuration persisted; can be restarted | | `SandboxStatusCrashed` | `"crashed"` | VM exited unexpectedly (kernel panic, OOM, etc.) | | `SandboxStatusDraining` | `"draining"` | Graceful shutdown in progress; existing commands finish, new ones rejected | | `SandboxStatusPaused` | `"paused"` | VM is paused | ### LogOptions

Used by Logs()

Filters passed to [`Logs`](#sb-logs). The zero value returns everything for the default sources (stdout + stderr). | Field | Type | Description | |-------|------|-------------| | Tail | `uint64` | Keep only the last N matching entries | | Since | `time.Time` | Inclusive lower timestamp bound | | Until | `time.Time` | Exclusive upper timestamp bound | | Sources | `[]`[`LogSource`](#logsource) | Sources to include; empty = stdout + stderr. Add `LogSourceOutput` or `LogSourceSystem` for PTY-merged output or runtime/kernel diagnostics | ### LogStreamOptions

Used by LogStream()

Configures a live log stream. The zero value reads the default sources from the beginning with follow off. `Since` and `FromCursor` are mutually exclusive. | Field | Type | Description | |-------|------|-------------| | Sources | `[]`[`LogSource`](#logsource) | Sources to include; empty = stdout + stderr + output | | Since | `time.Time` | Start at the first entry with timestamp >= this; mutually exclusive with `FromCursor` | | FromCursor | `string` | Resume strictly after the entry whose `Cursor` matches; mutually exclusive with `Since` | | Until | `time.Time` | Stop at the first entry with timestamp >= this | | Follow | `bool` | Keep the stream open past EOF and yield new entries as written | ### LogSource

Used by LogEntry.Source · LogOptions.Sources · LogStreamOptions.Sources

```go type LogSource string ``` | Constant | Value | Description | |----------|-------|-------------| | `LogSourceStdout` | `"stdout"` | Captured stdout (pipe mode, streams stayed separated) | | `LogSourceStderr` | `"stderr"` | Captured stderr (pipe mode) | | `LogSourceOutput` | `"output"` | PTY-merged stdout and stderr from a session running in pty mode | | `LogSourceSystem` | `"system"` | Synthetic lifecycle markers plus runtime/kernel diagnostic lines | ### LogLevel

Used by WithLogLevel()

```go type LogLevel string ``` Sandbox process log verbosity. | Constant | Value | Description | |----------|-------|-------------| | `LogLevelDefault` | `""` | Runtime default | | `LogLevelTrace` | `"trace"` | Most verbose, all diagnostic output | | `LogLevelDebug` | `"debug"` | Debug and higher | | `LogLevelInfo` | `"info"` | Info and higher | | `LogLevelWarn` | `"warn"` | Warnings and errors only | | `LogLevelError` | `"error"` | Errors only | ### PullPolicy

Used by WithPullPolicy()

```go type PullPolicy string ``` Controls when the SDK fetches an OCI image from the registry. | Constant | Value | Description | |----------|-------|-------------| | `PullPolicyDefault` | `""` | Runtime default (currently `PullPolicyIfMissing`) | | `PullPolicyAlways` | `"always"` | Pull every time, even if cached locally | | `PullPolicyIfMissing` | `"if-missing"` | Pull only if not already cached | | `PullPolicyNever` | `"never"` | Never pull; fail if missing | ### SecurityProfile

Used by WithSecurityProfile()

```go type SecurityProfile string ``` Sandbox-wide in-guest security profile. | Constant | Value | Description | |----------|-------|-------------| | `SecurityProfileDefault` | `"default"` | Normal guest-root semantics | | `SecurityProfileRestricted` | `"restricted"` | Stronger hardening: `no_new_privs`, dropped mount-admin capability, forced `nosuid,nodev` on user mounts | ### RegistryAuth

Used by WithRegistryAuth()

Credentials for a private OCI registry. | Field | Type | Description | |-------|------|-------------| | Username | `string` | Registry username | | Password | `string` | Registry password | ### InitConfig

Built by Init · used by WithInit()

Custom guest PID-1 init specification. Construct via the [`Init`](#init) factory rather than building the struct directly. | Field | Type | Description | |-------|------|-------------| | Cmd | `string` | Absolute path inside the guest, or `"auto"` | | Args | `[]string` | Supplemental argv (`argv[0]` is implicitly `Cmd`) | | Env | `map[string]string` | Extra env vars merged on top of the inherited env | ### InitOptions

Used by Init.Cmd()

Tuning struct for [`Init.Cmd`](#init-cmd) beyond the required cmd. | Field | Type | Description | |-------|------|-------------| | Args | `[]string` | Supplemental argv | | Env | `map[string]string` | Extra env vars | ### PatchConfig

Built by Patch · used by WithPatches()

A single rootfs patch. Construct via the [`Patch`](#patch) factory; the fields populated depend on the [`PatchKind`](#patchkind). | Field | Type | Description | |-------|------|-------------| | Kind | [`PatchKind`](#patchkind) | Patch flavour | | Path | `string` | Absolute guest path (text / append / mkdir / remove) | | Content | `string` | Text content (text / append) | | Mode | `*uint32` | File or directory mode, e.g. `0o644` | | Replace | `bool` | When `true`, overwrite an existing path at the destination | | Src | `string` | Host source path (copy_file / copy_dir) | | Dst | `string` | Guest destination path (copy_file / copy_dir) | | Target | `string` | Symlink target | | Link | `string` | Symlink path | ### PatchOptions

Used by Patch methods

Tuning struct passed to [`Patch`](#patch) methods that accept a mode and replace flag. | Field | Type | Description | |-------|------|-------------| | Mode | `*uint32` | File or directory mode | | Replace | `bool` | Overwrite an existing path | ### PatchKind

Used by PatchConfig.Kind

```go type PatchKind string ``` Discriminator for [`PatchConfig`](#patchconfig). Prefer the [`Patch`](#patch) factory. | Constant | Value | |----------|-------| | `PatchKindText` | `"text"` | | `PatchKindAppend` | `"append"` | | `PatchKindMkdir` | `"mkdir"` | | `PatchKindRemove` | `"remove"` | | `PatchKindSymlink` | `"symlink"` | | `PatchKindCopyFile` | `"copy_file"` | | `PatchKindCopyDir` | `"copy_dir"` | ### SetupOption The setup-only `SetupOption` type is documented under [Runtime setup](/sdk/setup#customize-installation).