--- 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. Examples assume the package is imported as `m "github.com/superradcompany/microsandbox/sdk/go"`.

Functions13

m.CreateSandbox()configure and boot a new sandbox m.GetSandbox()handle to an existing one m.ListSandboxes()all sandboxes m.ListSandboxesWith()filter by labels m.NewSandboxFilter()build a label filter m.StartSandbox()restart a stopped one m.StartSandboxDetached()restart detached m.RemoveSandbox()delete a stopped one m.AllSandboxMetrics()metrics for every sandbox m.EnsureInstalled()install the runtime up front m.IsInstalled()is the runtime present m.SDKVersion()pinned release version m.RuntimeVersion()loaded FFI version

Methods · *Sandbox21

sb.Name()sandbox name sb.Exec()run a command sb.Shell()run via /bin/sh -c sb.FS()read / write files sb.SSH()SSH client / server sb.Logs()captured output sb.LogStream()stream output sb.Metrics()resource snapshot sb.MetricsStream()stream metrics sb.Attach()interactive PTY sb.AttachShell()interactive shell sb.Stop()graceful shutdown sb.RequestStop()async stop request sb.Kill()force terminate sb.RequestKill()async kill request sb.RequestDrain()async drain request sb.WaitUntilStopped()block until it exits sb.Detach()release, keep running sb.Close()release the handle sb.OwnsLifecycle()attached vs detached sb.OwnsLifecycleOrFalse()attached, false on error

Options37

WithImage() WithMemory() WithCPUs() WithEnv() WithPorts() WithMounts() WithNetwork() WithSecrets() WithInit() WithPatches() WithDetached() WithReplace() + 25 more in the Options section

Types

SandboxHandle SandboxFilter SandboxConfig SandboxOption Metrics MetricsStreamHandle SandboxStopResult SandboxStatus LogEntry LogOptions LogStreamOptions LogStreamHandle LogSource LogLevel PullPolicy SecurityProfile RegistryAuth InitConfig InitOptions Init PatchConfig PatchOptions PatchKind Patch SetupOption

Typical flow

```go import m "github.com/superradcompany/microsandbox/sdk/go" sb, err := m.CreateSandbox(ctx, "api", // 1. configure + boot m.WithImage("python"), m.WithMemory(1024), ) if err != nil { return err } defer sb.Close() // 4. shut down out, err := sb.Exec(ctx, "python", []string{"-V"}) // 2. run if err != nil { return err } fmt.Println(out.Stdout()) // 3. read output ``` ## Functions --- #### m.CreateSandbox()

function

```go func CreateSandbox(ctx context.Context, name string, opts ...SandboxOption) (*Sandbox, error) ``` 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.

```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() }() ``` --- #### m.GetSandbox()

function

```go func GetSandbox(ctx context.Context, name string) (*SandboxHandle, error) ``` 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`, `Metrics`, `Logs`, and snapshot methods.

Parameters

namestring

Sandbox name, up to 128 UTF-8 bytes.

Returns

*SandboxHandle

Metadata handle with status and lifecycle control.

```go h, err := m.GetSandbox(ctx, "api") if err != nil { return err } fmt.Println(h.Status()) ``` --- #### m.ListSandboxes()

function

```go func ListSandboxes(ctx context.Context) ([]*SandboxHandle, error) ``` Return metadata for every known sandbox (running, stopped, draining, crashed), ordered by creation time, newest first.

Returns

[]*SandboxHandle

All sandbox handles.

```go handles, err := m.ListSandboxes(ctx) if err != nil { return err } for _, h := range handles { fmt.Printf("%s — %s\n", h.Name(), h.Status()) } ``` --- #### m.ListSandboxesWith()

function

```go func ListSandboxesWith(ctx context.Context, filter SandboxFilter) ([]*SandboxHandle, error) ``` Return sandbox metadata narrowed by a [`SandboxFilter`](#sandboxfilter). Label selectors are AND-matched: a sandbox matches only if it carries every label in the filter.

Parameters

filterSandboxFilter

Label selector. The zero value matches every sandbox.

Returns

[]*SandboxHandle

Matching sandbox handles.

```go filter := m.NewSandboxFilter().WithLabels(map[string]string{"user.id": "alice"}) handles, err := m.ListSandboxesWith(ctx, filter) ``` --- #### m.NewSandboxFilter()

function

```go func NewSandboxFilter() SandboxFilter ``` Return an empty [`SandboxFilter`](#sandboxfilter) that matches every sandbox. Chain [`WithLabels`](#sandboxfilter) to narrow the results passed to [`ListSandboxesWith`](#m-listsandboxeswith).

Returns

SandboxFilter

Empty filter.

--- #### m.StartSandbox()

function

```go func StartSandbox(ctx context.Context, name string) (*Sandbox, error) ``` 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.

```go sb, err := m.StartSandbox(ctx, "api") ``` --- #### m.StartSandboxDetached()

function

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

function

```go func RemoveSandbox(ctx context.Context, name string) error ``` Delete a stopped sandbox and all its persisted state from disk. Fails if the sandbox is still running, stop it first.

Parameters

namestring

Sandbox name, up to 128 UTF-8 bytes.

```go err := m.RemoveSandbox(ctx, "api") ``` --- #### m.AllSandboxMetrics()

function

```go func AllSandboxMetrics(ctx context.Context) (map[string]*Metrics, error) ``` 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.

```go all, err := m.AllSandboxMetrics(ctx) for name, metrics := range all { fmt.Printf("%s: %.1f%% CPU\n", name, metrics.CPUPercent) } ``` --- #### m.EnsureInstalled()

function

```go func EnsureInstalled(ctx context.Context, opts ...SetupOption) error ``` Optional. Ensure msb + libkrunfw are present under `~/.microsandbox/`, downloading them from the matching GitHub release if not. Call at startup to surface install errors up front; otherwise the first sandbox call handles it. The FFI library is embedded in the Go binary and loads automatically, `EnsureInstalled` does not govern it. Idempotent; options apply only to the first call.

Parameters

ctxcontext.Context

Cancels an in-flight msb + libkrunfw download.

opts...SetupOption

Install knobs, e.g. WithSkipDownload().

```go if err := m.EnsureInstalled(ctx); err != nil { log.Fatal(err) } ``` --- #### m.IsInstalled()

function

```go func IsInstalled() bool ``` Report whether msb + libkrunfw are present on disk at the SDK's pinned version. Does **not** dlopen the FFI library (which ships embedded).

Returns

bool

true if the runtime is present at the expected version.

--- #### m.SDKVersion()

function

```go func SDKVersion() string ``` Return the microsandbox release version this SDK was compiled against.

Returns

string

Pinned release version, e.g. "0.5.8".

--- #### m.RuntimeVersion()

function

```go func RuntimeVersion() (string, error) ``` Return the version reported by the loaded FFI library. Auto-loads the library on first use; returns an error with `Kind == ErrLibraryNotLoaded` only if loading fails (e.g. unsupported platform or GLIBC mismatch).

Returns

string

FFI library version.

--- ## Methods The `*Sandbox` returned by [`CreateSandbox`](#m-createsandbox), [`StartSandbox`](#m-startsandbox), and [`SandboxHandle.Connect`](#sandboxhandle) carries the methods below. `*Sandbox` is **safe for concurrent use** from multiple goroutines. The command-execution methods, `Exec`, `ExecStream`, `Shell`, and `ShellStream`, live on the same value and are documented under [Execution](/sdk/go/execution). --- #### sb.Name()

method

```go func (s *Sandbox) Name() string ``` Return the sandbox name.

Returns

string

Sandbox name, up to 128 UTF-8 bytes.

--- #### sb.FS()

method

```go func (s *Sandbox) FS() *SandboxFSOps ``` 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.

```go err := sb.FS().Write(ctx, "/tmp/hello.txt", []byte("hi")) ``` --- #### sb.SSH()

method

```go func (s *Sandbox) SSH() *SandboxSSHOps ``` 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.

```go client, err := sb.SSH().OpenClient(ctx) ``` --- #### sb.Logs()

method

```go func (s *Sandbox) Logs(ctx context.Context, opts LogOptions) ([]LogEntry, error) ``` 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.

```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()) } ``` --- #### sb.LogStream()

method

```go func (s *Sandbox) LogStream(ctx context.Context, opts LogStreamOptions) (*LogStreamHandle, error) ``` 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.

```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()) } ``` --- #### sb.Metrics()

method

```go func (s *Sandbox) Metrics(ctx context.Context) (*Metrics, error) ``` 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.

```go metrics, err := sb.Metrics(ctx) fmt.Printf("cpu %.1f%% · mem %d MiB\n", metrics.CPUPercent, metrics.MemoryBytes/(1<<20)) ``` --- #### sb.MetricsStream()

method

```go func (s *Sandbox) MetricsStream(ctx context.Context, interval time.Duration) (*MetricsStreamHandle, error) ``` 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.

```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) } ``` --- #### sb.Attach()

method

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

method

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

method

```go func (s *Sandbox) Stop(ctx context.Context, opts ...StopOption) error ``` 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).

```go err := sb.Stop(ctx, m.WithStopTimeout(30*time.Second)) ``` --- #### sb.RequestStop()

method

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

method

```go func (s *Sandbox) Kill(ctx context.Context, opts ...KillOption) error ``` 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.

```go err := sb.Kill(ctx) ``` --- #### sb.RequestKill()

method

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

method

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

method

```go func (s *Sandbox) WaitUntilStopped(ctx context.Context) (*SandboxStopResult, error) ``` Block until the sandbox is observed in a terminal state, then return how it ended.

Returns

*SandboxStopResult

Terminal status, exit code, and signal.

```go result, err := sb.WaitUntilStopped(ctx) fmt.Printf("ended as %s\n", result.Status) ``` --- #### sb.Detach()

method

```go func (s *Sandbox) Detach(ctx context.Context) error ``` 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). ```go err := sb.Detach(ctx) // keeps running in the background ``` --- #### sb.Close()

method

```go func (s *Sandbox) Close() error ``` 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. ```go defer sb.Close() ``` --- #### sb.OwnsLifecycle()

method

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

method

```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 [`CreateSandbox`](#m-createsandbox). Map and slice options merge across repeated calls; single-value setters like [`WithImage`](#withimage) replace. Simple setters are demonstrated by the [Typical flow](#typical-flow) above. --- #### WithImage()

option

```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 [`WithSnapshot`](#withsnapshot) 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()

option

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

option

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

--- #### WithSnapshot()

option

```go func WithSnapshot(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()

option

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

--- #### WithCPUs()

option

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

--- #### WithWorkdir()

option

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

Parameters

pathstring

Absolute path inside the guest.

--- #### WithShell()

option

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

option

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

option

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

option

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

option

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

option

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

Parameters

hostnamestring

Hostname.

--- #### WithUser()

option

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

Parameters

userstring

User name or UID.

--- #### WithReplace()

option

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

option

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

option

```go func WithDetached() SandboxOption ``` Create the sandbox in detached mode. The VM continues running after the Go process exits; reattach via [`GetSandbox`](#m-getsandbox). Note that [`Close`](#sb-close) stops a detached sandbox, use [`Detach`](#sb-detach) to leave it running. --- #### WithEphemeral()

option

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

option

```go func WithEntrypoint(cmd ...string) SandboxOption ``` Override the user-workload entrypoint baked into the image: the command the agent execs per request. This is the user workload, **not** the guest PID 1, for that, use [`WithInit`](#withinit) instead.

Parameters

cmd...string

Entrypoint command and arguments.

--- #### WithInit()

option

```go func WithInit(cfg InitConfig) SandboxOption ``` 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/customize#custom-init-system) for image picks and shutdown semantics.

Parameters

cfgInitConfig

Init specification.

```go sb, err := m.CreateSandbox(ctx, "worker", m.WithImage("jrei/systemd-debian:12"), m.WithInit(m.Init.Auto()), ) ``` --- #### WithLogLevel()

option

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

Parameters

levelLogLevel

Log level.

--- #### WithQuietLogs()

option

```go func WithQuietLogs() SandboxOption ``` Suppress sandbox-level log output entirely. --- #### WithScripts()

option

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

option

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

Parameters

pPullPolicy

Pull behavior.

--- #### WithMaxDuration()

option

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

option

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

option

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

Parameters

authRegistryAuth

Registry credentials.

--- #### WithPorts()

option

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

option

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

option

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

option

```go func WithNetwork(net *NetworkConfig) SandboxOption ``` Configure the network stack: preset, 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.

```go sb, err := m.CreateSandbox(ctx, "api", m.WithImage("python"), m.WithNetwork(m.NetworkPolicy.PublicOnly()), ) ``` --- #### WithSecrets()

option

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

option

```go func WithPatches(patches ...PatchConfig) SandboxOption ``` 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.

```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{}), ), ) ``` --- #### WithMounts()

option

```go func WithMounts(mounts map[string]MountConfig) SandboxOption ``` 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.

```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}), }), ) ``` --- #### WithStopTimeout()

option

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

option

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

--- #### WithSkipDownload()

option

```go func WithSkipDownload() SetupOption ``` Prevent [`EnsureInstalled`](#m-ensureinstalled) from fetching the msb + libkrunfw bundle from GitHub. Use when the runtime is already on disk at the install path (e.g. air-gapped CI). The embedded FFI library is unaffected. This is a [`SetupOption`](#setupoption), pass it to `EnsureInstalled`. --- ## Patch Factory that constructs rootfs patches for [`WithPatches`](#withpatches). Access via the package-level `Patch` value. Each method returns a [`PatchConfig`](#patchconfig). `Mkdir` and `Remove` are idempotent; other operations error at boot when targeting a path already present in the image unless `Replace: true` is passed in [`PatchOptions`](#patchoptions). See [Patches](/sandboxes/customize#patches) for conceptual context. --- #### Patch.Text()

factory

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

factory

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

factory

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

factory

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

Parameters

pathstring

Absolute path inside the guest.

--- #### Patch.Symlink()

factory

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

factory

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

factory

```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 Factory that constructs [`InitConfig`](#initconfig) values for [`WithInit`](#withinit), handing off PID 1 inside the guest after agentd setup. Access via the package-level `Init` value. See [Custom init system](/sandboxes/customize#custom-init-system) for image picks and shutdown semantics. --- #### Init.Auto()

factory

```go func (initFactory) Auto() InitConfig ``` 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.

```go m.WithInit(m.Init.Auto()) ``` --- #### Init.Cmd()

factory

```go func (initFactory) Cmd(cmd string, opts InitOptions) InitConfig ``` 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.

```go m.WithInit(m.Init.Cmd( "/lib/systemd/systemd", m.InitOptions{ Args: []string{"--unit=multi-user.target"}, Env: map[string]string{"container": "microsandbox"}, }, )) ``` --- ## Types ### SandboxHandle

struct

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

A lightweight reference to a sandbox's persisted state. Carries metadata (name, status, config JSON, timestamps) and offers lifecycle methods that operate on the sandbox **without** an active guest-agent connection. You cannot `Exec` or `FS` on a handle, call `Connect` or `Start` to upgrade to a full [`*Sandbox`](#methods). | Method | Returns | Description | |--------|---------|-------------| | `Name()` | `string` | Sandbox name, up to 128 UTF-8 bytes | | `Status()` | [`SandboxStatus`](#sandboxstatus) | Last-known lifecycle status | | `ConfigJSON()` | `string` | Raw JSON configuration | | `Config()` | `(*`[`SandboxConfig`](#sandboxconfig)`, error)` | Parsed configuration | | `CreatedAt()` | `time.Time` | Creation time, zero value if unknown | | `UpdatedAt()` | `time.Time` | Last-update time, zero value if unknown | | `Refresh(ctx)` | `(*SandboxHandle, error)` | Fresh handle for the same name | | `Metrics(ctx)` | `(*`[`Metrics`](#metrics)`, error)` | Point-in-time resource metrics | | `Logs(ctx, opts)` | `([]`[`LogEntry`](#logentry)`, error)` | Read captured `exec.log` (works without starting) | | `LogStream(ctx, opts)` | `(*`[`LogStreamHandle`](#logstreamhandle)`, error)` | Stream captured output | | `Connect(ctx)` | `(*`[`Sandbox`](#methods)`, error)` | Reattach to the running sandbox | | `Start(ctx)` | `(*`[`Sandbox`](#methods)`, error)` | Boot a stopped sandbox in attached mode | | `StartDetached(ctx)` | `(*`[`Sandbox`](#methods)`, error)` | Boot a stopped sandbox in detached mode | | `Stop(ctx, opts...)` | `error` | Graceful shutdown; accepts [`StopOption`](#withstoptimeout) | | `RequestStop(ctx)` | `error` | Async stop request | | `Kill(ctx, opts...)` | `error` | Force terminate; accepts [`KillOption`](#withkilltimeout) | | `RequestKill(ctx)` | `error` | Async kill request | | `RequestDrain(ctx)` | `error` | Async drain request | | `WaitUntilStopped(ctx)` | `(*`[`SandboxStopResult`](#sandboxstopresult)`, error)` | Block until terminal state | | `Remove(ctx)` | `error` | Delete sandbox and persisted state | | `Snapshot(ctx, name)` | `(*SnapshotArtifact, error)` | Snapshot a stopped sandbox under a bare name | | `SnapshotTo(ctx, path)` | `(*SnapshotArtifact, error)` | Snapshot a stopped sandbox to an explicit path | ### SandboxFilter

struct

Built by NewSandboxFilter() · used by ListSandboxesWith()

Narrows the results of [`ListSandboxesWith`](#m-listsandboxeswith). The zero value matches every sandbox. Built fluently; `WithLabels` returns a new value so calls chain. | Method | Returns | Description | |--------|---------|-------------| | `WithLabels(labels)` | `SandboxFilter` | Require all of these labels (AND-matched). Repeated calls merge; later keys overwrite earlier ones | ### SandboxConfig

struct

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

type

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. ### Metrics

struct

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

struct

Returned by MetricsStream()

Live metrics subscription. Call `Close` to release Rust-side resources. | Method | Returns | Description | |--------|---------|-------------| | `Recv(ctx)` | `(*`[`Metrics`](#metrics)`, error)` | Block until the next snapshot arrives. Returns `(nil, nil)` when the stream ends (sandbox exited) | | `Close()` | `error` | Stop the stream and release Rust-side resources | ### SandboxStopResult

struct

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

enum

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

struct

Returned by Logs() · LogStream()

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

struct

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

struct

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

struct

Returned by LogStream()

Live log subscription. Call `Close` to release Rust-side resources. | Method | Returns | Description | |--------|---------|-------------| | `Recv(ctx)` | `(*`[`LogEntry`](#logentry)`, error)` | Block until the next entry arrives. Returns `(nil, nil)` when the stream ends | | `Close()` | `error` | Stop the stream and release Rust-side resources | ### LogSource

enum

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

enum

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

enum

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

enum

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

struct

Used by WithRegistryAuth()

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

struct

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

struct

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

factory

Produces InitConfig for WithInit()

Package-level factory namespace for [`InitConfig`](#initconfig) values. See the [Init](#init) section for its methods. | Method | Returns | Description | |--------|---------|-------------| | [`Auto()`](#init-auto) | [`InitConfig`](#initconfig) | Auto-detect a guest init | | [`Cmd(cmd, opts)`](#init-cmd) | [`InitConfig`](#initconfig) | Explicit init binary with argv and env | ### PatchConfig

struct

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

struct

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

enum

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"` | ### Patch

factory

Produces PatchConfig for WithPatches()

Package-level factory namespace for [`PatchConfig`](#patchconfig) values. See the [Patch](#patch) section for its methods. | Method | Returns | Description | |--------|---------|-------------| | [`Text(path, content, opts)`](#patch-text) | [`PatchConfig`](#patchconfig) | Write UTF-8 text | | [`Append(path, content)`](#patch-append) | [`PatchConfig`](#patchconfig) | Append to an existing file | | [`Mkdir(path, opts)`](#patch-mkdir) | [`PatchConfig`](#patchconfig) | Create a directory (idempotent) | | [`Remove(path)`](#patch-remove) | [`PatchConfig`](#patchconfig) | Delete a file or directory (idempotent) | | [`Symlink(target, link, opts)`](#patch-symlink) | [`PatchConfig`](#patchconfig) | Create a symlink | | [`CopyFile(src, dst, opts)`](#patch-copyfile) | [`PatchConfig`](#patchconfig) | Copy a host file into the rootfs | | [`CopyDir(src, dst, opts)`](#patch-copydir) | [`PatchConfig`](#patchconfig) | Copy a host directory into the rootfs | ### SetupOption

type

Consumed by EnsureInstalled()

```go type SetupOption func(*setupConfig) ``` A functional option for [`EnsureInstalled`](#m-ensureinstalled). The only helper is [`WithSkipDownload`](#withskipdownload).