Sandbox

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 for configuration examples and Lifecycle for state management.

Lifecycle convergence

ConnectOrCreateSandbox(ctx, name, opts...) (*Sandbox, error)
handle.ConnectOrStart(ctx, opts...) (*Sandbox, error)
handle.WaitForStatus(ctx, status) (*SandboxHandle, error)
handle.Restart(ctx, opts...) (*Sandbox, error)
handle.Destroy(ctx, opts...) error
sandbox.ID() string
handle.ID() string

ConnectOrCreateSandbox converges on the current persisted sandbox by name and uses options only when it creates. Receiver lifecycle operations are bound to the stable opaque ID; a stale receiver returns ErrSandboxReplaced instead of acting on a replacement that reused the name. Sandbox also exposes WaitForStatus, Restart, and Destroy. See Lifecycle convergence and identity safety for state behavior and examples.

Functions

m.CreateSandbox()

func CreateSandbox(ctx context.Context, name string, opts ...SandboxOption) (*Sandbox, error)

Example

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 owns the VM process. Call Close (or Stop + Close) when done. See 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.ConnectOrCreateSandbox()

func ConnectOrCreateSandbox(ctx context.Context, name string, opts ...SandboxOption) (*Sandbox, error)

Converge on the current persisted sandbox by name. The function connects when it is running, waits through SandboxStatusStarting, starts it when it is created, stopped, or crashed, and creates it only when the name is absent. Options apply only to creation; an existing sandbox keeps its persisted configuration. Concurrent callers converge on the winning identity. WithReplace and WithReplaceWithTimeout are invalid with this function.

Parameters

• ctx: controls this convergence operation; cancellation does not stop a sandbox already returned.
• name: reusable sandbox name, up to 128 UTF-8 bytes.
• opts: the same creation options accepted by CreateSandbox, used only when creation is necessary.

Returns

(*Sandbox, error)

m.GetSandbox()

func GetSandbox(ctx context.Context, name string) (*SandboxHandle, error)

Example

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

func ListSandboxes(ctx context.Context) (*SandboxPage, error)

Example

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

func ListSandboxesWith(ctx context.Context, options ...SandboxListOption) (*SandboxPage, error)

Example

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

func StartSandbox(ctx context.Context, name string) (*Sandbox, error)

Example

sb, err := m.StartSandbox(ctx, "api")

Restart a previously stopped sandbox. The VM reboots using the persisted configuration and returns a live *Sandbox.

Parameters

namestring

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

Returns

*Sandbox

Running sandbox.

m.StartSandboxDetached()

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

func RemoveSandbox(ctx context.Context, name string) error

Example

err := m.RemoveSandbox(ctx, "api")

Delete a stopped sandbox by name. See 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

func AllSandboxMetrics(ctx context.Context) (map[string]*Metrics, error)

Example

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 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. The Go-only version helpers are under Inspect Go versions.

Sandbox

A live sandbox connection that is safe for concurrent use.

sb.Name()

func (s *Sandbox) Name() string

Return the sandbox name.

Returns

string

Sandbox name, up to 128 UTF-8 bytes.

sb.ID()

func (s *Sandbox) ID() string

Return the opaque stable identity of this persisted sandbox. It remains unchanged across stop and restart and changes when the reusable name is removed and recreated. Use it for equality, logging, and correlation; do not parse it.

sb.FS()

func (s *Sandbox) FS() *SandboxFSOps

Example

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 for the API.

Returns

*SandboxFSOps

Filesystem accessor.

sb.SSH()

func (s *Sandbox) SSH() *SandboxSSHOps

Example

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 for the API.

Returns

*SandboxSSHOps

SSH accessor.

sb.Logs()

Local-only

func (s *Sandbox) Logs(ctx context.Context, opts LogOptions) ([]LogEntry, error)

Example

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

func (s *Sandbox) LogStream(ctx context.Context, opts LogStreamOptions) (*LogStreamHandle, error)

Example

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 when done. Also available on 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

func (s *Sandbox) Ping(ctx context.Context) (*SandboxPingResult, error)

Example

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

func (s *Sandbox) Touch(ctx context.Context) (*SandboxTouchResult, error)

Example

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

func (s *Sandbox) Modify(ctx context.Context, opts ModifyOptions) (*SandboxModificationPlan, error)

Example

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

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

func (s *Sandbox) Metrics(ctx context.Context) (*Metrics, error)

Example

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

func (s *Sandbox) MetricsStream(ctx context.Context, interval time.Duration) (*MetricsStreamHandle, error)

Example

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 snapshot every interval. Sub-millisecond precision is rounded up; a zero or negative value uses the runtime minimum (~1 ms). Close the returned *MetricsStreamHandle when done.

Parameters

intervaltime.Duration

Time between snapshots.

Returns

*MetricsStreamHandle

Live subscription; call Recv in a loop.

sb.Attach()

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

func (s *Sandbox) AttachWith(ctx context.Context, cmd string, args []string, opts ...AttachOption) (int, error)

Example

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

func (s *Sandbox) AttachShell(ctx context.Context) (int, error)

Attach to the sandbox’s default shell (configured via WithShell, defaults to /bin/sh). Blocks until the shell exits and returns its exit code.

Returns

int

Exit code of the shell.

sb.Stop()

Limited on cloud

func (s *Sandbox) Stop(ctx context.Context, opts ...StopOption) error

Example

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 to change it.

Parameters

opts…StopOption

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

sb.RequestStop()

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 to await termination.

sb.Kill()

Local-only

func (s *Sandbox) Kill(ctx context.Context, opts ...KillOption) error

Example

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 for graceful shutdown. Defaults to a five-second observation window; pass WithKillTimeout to change it.

Parameters

opts…KillOption

Stopped-state observation window.

sb.RequestKill()

Local-only

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

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

func (s *Sandbox) WaitUntilStopped(ctx context.Context) (*SandboxStopResult, error)

Example

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

func (s *Sandbox) WaitForStatus(ctx context.Context, status SandboxStatus) (*SandboxHandle, error)

Wait until this exact sandbox reaches status, returning a refreshed metadata handle. The context supplies cancellation or a deadline. Returns ErrSandboxReplaced rather than following a reused name.

sb.Restart()

func (s *Sandbox) Restart(ctx context.Context, opts ...RestartOption) (*Sandbox, error)

Restart this exact sandbox. Defaults to graceful shutdown, a ten-second timeout, and attached local start. A created, stopped, or crashed sandbox starts directly; a starting sandbox is observed until it settles. Use WithRestartForce, WithRestartTimeout, and WithRestartDetached for explicit controls.

sb.Destroy()

func (s *Sandbox) Destroy(ctx context.Context, opts ...DestroyOption) error

Stop and remove this exact sandbox. Defaults to graceful shutdown with a ten-second timeout. Use WithDestroyForce or WithDestroyTimeout for explicit controls. Returns ErrSandboxReplaced instead of deleting a same-name replacement.

sb.Detach()

func (s *Sandbox) Detach(ctx context.Context) error

Example

err := sb.Detach(ctx) // keeps running in the background

Release the Rust-side handle without stopping the VM. Use on sandboxes created with 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.

sb.Close()

Limited on cloud

func (s *Sandbox) Close() error

Example

defer sb.Close()

Release the Rust-side handle. Safe to call multiple times; the second call returns an error with Kind == ErrInvalidHandle. A local attached handle stops its VM on Close; local detached and cloud handles release client resources only. Stop or remove a cloud sandbox explicitly.

sb.OwnsLifecycle()

func (s *Sandbox) OwnsLifecycle() (bool, error)

Report whether this handle owns the VM process. Local attached handles return true; local detached handles and all cloud handles return false, because the cloud worker owns the sandbox process. The error return covers stale handles and FFI failures; use OwnsLifecycleOrFalse when you don’t care.

Returns

bool

true for a local attached handle.

sb.OwnsLifecycleOrFalse()

func (s *Sandbox) OwnsLifecycleOrFalse() bool

Convenience wrapper around OwnsLifecycle that swallows the error and returns false for cloud, detached, or invalid handles. 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 replace.

WithListLimit()

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

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

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

Limited on cloud

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 is used. Use WithImageDisk when a disk-image root needs an explicit filesystem type.

Parameters

imagestring

OCI image, local path, or disk image.

WithOCIUpperSize()

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

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

Local-only

func WithFromSnapshot[T SnapshotSeed](snapshot T) SandboxOption

Boot from a snapshot using a backend-relative reference. Mutually exclusive with WithImage. Pass a SnapshotArtifact or SnapshotHandle directly to preserve its typed identifier-or-path reference without inspecting the selected backend.

Parameters

snapshotstring | *SnapshotArtifact | *SnapshotHandle

Snapshot object or backend-relative compatibility string.

WithMemory()

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

Local-only

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

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

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

Local-only

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

func WithWorkdir(path string) SandboxOption

Set the default working directory for all commands.

Parameters

pathstring

Absolute path inside the guest.

WithShell()

func WithShell(shell string) SandboxOption

Set the shell used by Shell and AttachShell. Defaults to /bin/sh on most images.

Parameters

shellstring

Shell path, e.g. “/bin/bash”.

WithSecurityProfile()

func WithSecurityProfile(profile SecurityProfile) SandboxOption

Set the in-guest security profile. SecurityProfileRestricted 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()

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

func WithLabels(labels map[string]string) SandboxOption

Attach labels to the sandbox for metrics attribution and 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()

func WithLabel(key, value string) SandboxOption

Attach a single label. Shorthand for WithLabels with one entry.

Parameters

keystring

Label key.

valuestring

Label value.

WithHostname()

Local-only

func WithHostname(hostname string) SandboxOption

Set the guest hostname.

Parameters

hostnamestring

Hostname.

WithUser()

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

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 to set a different window.

WithReplaceWithTimeout()

Local-only

func WithReplaceWithTimeout(timeout time.Duration) SandboxOption

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

func WithDetached() SandboxOption

Create the sandbox in detached mode. The VM continues running after the Go process exits; reattach via GetSandbox. Close releases this non-owning handle without stopping the VM.

WithEphemeral()

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

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

Parameters

cmd…string

Entrypoint command and arguments.

WithCmd()

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.

sb, err := m.CreateSandbox(ctx, "worker",
    m.WithImage("example/worker:latest"),
    m.WithCmd("worker.py", "--once"),
)

WithInit()

func WithInit(cfg InitConfig) SandboxOption

Example

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 factory. See Custom init system for image picks and shutdown semantics.

Parameters

cfgInitConfig

Init specification.

WithLogLevel()

func WithLogLevel(level LogLevel) SandboxOption

Override the sandbox process’s log verbosity. See LogLevel.

Parameters

levelLogLevel

Log level.

WithQuietLogs()

func WithQuietLogs() SandboxOption

Suppress sandbox-level log output entirely.

WithScripts()

func WithScripts(scripts map[string]string) SandboxOption

Add named scripts mounted at /.msb/scripts/<name> 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()

func WithPullPolicy(p PullPolicy) SandboxOption

Control when the OCI image is pulled from the registry. See PullPolicy.

Parameters

pPullPolicy

Pull behavior.

WithMaxDuration()

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

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

func WithRegistryAuth(auth RegistryAuth) SandboxOption

Set credentials for pulling from a private OCI registry. See RegistryAuth.

Parameters

authRegistryAuth

Registry credentials.

WithRegistryInsecure()

Local-only

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.

WithRegistryCACerts()

Local-only

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.

Parameters

pem[]byte

PEM-encoded CA certificates.

WithRegistryCACertsPath()

Local-only

func WithRegistryCACertsPath(path string) SandboxOption

Like WithRegistryCACerts but reads the PEM bundle from a file. The file is read when CreateSandbox runs, which fails if it is unreadable. Called repeatedly, the bundles accumulate.

Parameters

pathstring

Path to a PEM file.

WithPorts()

Local-only

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

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

func WithPortBindings(bindings ...PortBinding) SandboxOption

Publish ports on explicit host bind addresses, such as 0.0.0.0. See PortBinding for the type definition and UDP examples.

Parameters

bindings…PortBinding

Explicit bind-address port mappings.

WithNetwork()

func WithNetwork(net *NetworkConfig) SandboxOption

Example

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 factory or a *NetworkConfig literal. See Networking.

Parameters

net*NetworkConfig

Network configuration.

WithSecrets()

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 factory. See Secrets.

Parameters

secrets…SecretEntry

Secret injection entries.

WithPatches()

func WithPatches(patches ...PatchConfig) SandboxOption

Example

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

Parameters

patches…PatchConfig

Ordered rootfs patches.

WithMounts()

func WithMounts(mounts map[string]MountConfig) SandboxOption

Example

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 factory. Called repeatedly, the maps merge; later entries overwrite earlier ones for the same guest path. See Volumes.

Parameters

mountsmap[string]MountConfig

Guest path to mount config.

WithStopTimeout()

func WithStopTimeout(timeout time.Duration) StopOption

Set how long Stop waits for graceful shutdown before force-killing. Default: 10 seconds. This is a StopOption, not a SandboxOption. Pass it to Stop.

Parameters

timeouttime.Duration

Graceful shutdown window.

WithConnectOrStartDetached()

func WithConnectOrStartDetached() ConnectOrStartOption

When ConnectOrStart must start a local sandbox, start it in detached/background mode. This option does not change ownership when the sandbox is already running.

WithRestartForce()

func WithRestartForce() RestartOption

Force-kill instead of requesting graceful shutdown during Restart.

WithRestartTimeout()

func WithRestartTimeout(timeout time.Duration) RestartOption

Set the graceful-shutdown convergence window used by Restart. The default is ten seconds.

WithRestartDetached()

func WithRestartDetached() RestartOption

Start the restarted local sandbox in detached/background mode.

WithDestroyForce()

func WithDestroyForce() DestroyOption

Force-kill instead of requesting graceful shutdown during Destroy.

WithDestroyTimeout()

func WithDestroyTimeout(timeout time.Duration) DestroyOption

Set the graceful-shutdown convergence window used by Destroy. The default is ten seconds.

WithKillTimeout()

func WithKillTimeout(timeout time.Duration) KillOption

Set how long Kill waits for stopped-state observation. Default: 5 seconds. This is a KillOption, pass it to Kill.

Parameters

timeouttime.Duration

Observation window.

The setup-only WithSkipDownload() option is documented under Runtime setup.

Attach options

WithAttachCwd()

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

func WithAttachUser(user string) AttachOption

Run the attached session as the given guest user instead of the sandbox’s default user (set via WithUser).

Parameters

userstring

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

WithAttachEnv()

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

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

Patch.Text()

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

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

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

func (patchFactory) Remove(path string) PatchConfig

Delete a file or directory at path. Idempotent.

Parameters

pathstring

Absolute path inside the guest.

Patch.Symlink()

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

Limited on cloud

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

Limited on cloud

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

Init.Auto()

func (initFactory) Auto() InitConfig

Example

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

func (initFactory) Cmd(cmd string, opts InitOptions) InitConfig

Example

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

Name()

Sandbox name, up to 128 UTF-8 bytes

Returns

string

h.ID()

func (h *SandboxHandle) ID() string

Return the opaque stable identity captured by this metadata handle. Receiver lifecycle calls remain bound to this value and return ErrSandboxReplaced when the reusable name now points to another sandbox.

h.Status()

Status()

Last-known lifecycle status

Returns

SandboxStatus

h.ConfigJSON()

ConfigJSON()

Raw JSON configuration

Returns

string

h.Config()

Local-only

Config()

Parsed configuration

Returns

(*SandboxConfig, error)

h.CreatedAt()

CreatedAt()

Creation time, zero value if unknown

Returns

time.Time

h.UpdatedAt()

UpdatedAt()

Last-update time, zero value if unknown

Returns

time.Time

h.Refresh()

Refresh(ctx)

Fresh handle for the same name

Returns

(*SandboxHandle, error)

h.Ping()

Local-only

Ping(ctx)

Check agent reachability without refreshing idle activity; does not start stopped sandboxes

Returns

(*SandboxPingResult, error)

h.Touch()

Local-only

Touch(ctx)

Explicitly refresh idle activity; does not start stopped sandboxes

Returns

(*SandboxTouchResult, error)

h.Modify()

Local-only

Modify(ctx, opts)

Plan or apply a configuration change; same ModifyOptions as Modify(). Does not start stopped sandboxes; changes persist for the next boot

Returns

(*SandboxModificationPlan, error)

h.Metrics()

Local-only

Metrics(ctx)

Point-in-time resource metrics

Returns

(*Metrics, error)

h.Logs()

Local-only

Logs(ctx, opts)

Read captured exec.log (works without starting)

Returns

([]LogEntry, error)

h.LogStream()

LogStream(ctx, opts)

Stream captured output

Returns

(*LogStreamHandle, error)

h.Connect()

Connect(ctx)

Reattach to the running sandbox

Returns

(*Sandbox, error)

h.ConnectOrStart()

func (h *SandboxHandle) ConnectOrStart(ctx context.Context, opts ...ConnectOrStartOption) (*Sandbox, error)

Connect when this exact sandbox is running, wait through SandboxStatusStarting, or start it when it is created, stopped, or crashed. Draining and paused states are rejected. WithConnectOrStartDetached affects only a required local start; connecting to an already-running sandbox does not change ownership.

h.Start()

Start(ctx)

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

Returns

(*Sandbox, error)

h.StartDetached()

StartDetached(ctx)

Boot a stopped sandbox in detached mode

Returns

(*Sandbox, error)

h.WaitForStatus()

func (h *SandboxHandle) WaitForStatus(ctx context.Context, status SandboxStatus) (*SandboxHandle, error)

Wait until this exact sandbox reaches status, returning a refreshed handle. The context supplies cancellation or a deadline. Returns ErrSandboxReplaced rather than rebinding to a replacement.

h.Restart()

func (h *SandboxHandle) Restart(ctx context.Context, opts ...RestartOption) (*Sandbox, error)

Restart this exact sandbox with the same state and option semantics as Sandbox.Restart.

h.Destroy()

func (h *SandboxHandle) Destroy(ctx context.Context, opts ...DestroyOption) error

Stop and remove this exact sandbox. A stale handle returns ErrSandboxReplaced instead of destroying a same-name replacement.

h.Stop()

Limited on cloud

Stop(ctx, opts...)

Graceful shutdown; accepts StopOption

Returns

error

h.RequestStop()

RequestStop(ctx)

Async stop request

Returns

error

h.Kill()

Local-only

Kill(ctx, opts...)

Force terminate; accepts KillOption

Returns

error

h.RequestKill()

Local-only

RequestKill(ctx)

Async kill request

Returns

error

h.RequestDrain()

Local-only

RequestDrain(ctx)

Async drain request

Returns

error

h.WaitUntilStopped()

WaitUntilStopped(ctx)

Block until terminal state

Returns

(*SandboxStopResult, error)

h.Remove()

Remove(ctx)

Delete sandbox and persisted state

Returns

error

h.Snapshot()

Local-only

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

Recv(ctx)

Block until the next snapshot arrives. Returns (nil, nil) when the stream ends (sandbox exited)

Returns

(*Metrics, error)

metricsStream.Close()

Close()

Stop the stream and release Rust-side resources

Returns

error

LogEntry

Returned by Logs() · LogStream()

A single captured log entry.

entry.Source

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

entry.Text()

Text()

Captured bytes as a string

Returns

string

LogStreamHandle

Returned by LogStream()

Live log subscription. Call Close to release Rust-side resources.

logStream.Recv()

Recv(ctx)

Block until the next entry arrives. Returns (nil, nil) when the stream ends

Returns

(*LogEntry, error)

logStream.Close()

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_<NAME>
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 or 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.

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	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	Hand PID 1 off to a guest init binary
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	Image pull behaviour
MaxDuration	time.Duration	Maximum sandbox lifetime
IdleTimeout	time.Duration	Idle timeout
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	Port mappings with explicit bind addresses
Network	*NetworkConfig	Network policy and configuration
Secrets	[]SecretEntry	Secret injection entries
Patches	[]PatchConfig	Rootfs modifications applied before boot
Volumes	map[string]MountConfig	Volume mounts keyed by guest path

SandboxOption

Consumed by CreateSandbox()

type SandboxOption func(*SandboxConfig)

A functional option for CreateSandbox. Every WithX helper in the Options section returns one. The lifecycle setters WithStopTimeout and WithKillTimeout return distinct StopOption / KillOption types passed to Stop and Kill instead.

AttachConfig

Populated by AttachOption

Configures a single 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()

type AttachOption func(*AttachConfig)

A functional option that mutates an 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.

Field	Type	Description
Name	string	Sandbox name
Status	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

type SandboxStatus string

Constant	Value	Description
SandboxStatusCreated	"created"	Persisted resource exists but has not started
SandboxStatusStarting	"starting"	Runtime is booting or waiting for capacity
SandboxStatusRunning	"running"	Guest agent is ready; Exec, Shell, FS work
SandboxStatusDraining	"draining"	Graceful shutdown in progress; existing commands finish, new ones rejected
SandboxStatusPaused	"paused"	VM is paused
SandboxStatusStopped	"stopped"	VM shut down; configuration persisted; can be restarted
SandboxStatusCrashed	"crashed"	VM exited unexpectedly (kernel panic, OOM, etc.)

LogOptions

Used by Logs()

Filters passed to 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	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	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

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

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

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

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 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 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 factory; the fields populated depend on the PatchKind.

Field	Type	Description
Kind	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 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

type PatchKind string

Discriminator for PatchConfig. Prefer the 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.