Sandbox - microsandbox

See Overview for configuration examples and Lifecycle for state management.

Setup

EnsureInstalled()

func EnsureInstalled(ctx context.Context, opts ...SetupOption) error

Optional. Ensure msb + libkrunfw are present at ~/.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. Parameters

Name	Type	Description
ctx	`context.Context`	Cancels an in-flight msb + libkrunfw download
opts	`...SetupOption`	See `SetupOption` for the available knobs

IsInstalled()

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

SDKVersion()

func SDKVersion() string

Return the microsandbox release version this SDK was compiled against.

RuntimeVersion()

func RuntimeVersion() (string, error)

Return the version reported by the loaded FFI library. Auto-loads the library on first use; returns ErrLibraryNotLoaded only if loading fails (e.g. unsupported platform or GLIBC mismatch).

SetupOption

Configures EnsureInstalled. Pass any of the options below as variadic arguments. Options apply only to the first call; subsequent calls are no-ops.

Option	Effect
`WithSkipDownload()`	Refuse to download msb + libkrunfw — require them to be pre-installed

WithSkipDownload()

func WithSkipDownload() SetupOption

Prevent 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 — it ships with the SDK.

Top-level functions

CreateSandbox()

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 owns the VM process — call Close (or Stop + Close) when done. Parameters

Name	Type	Description
ctx	`context.Context`	Cancels the boot operation. Cancelling after this function returns has no effect on the running sandbox
name	`string`	Sandbox name, up to 128 UTF-8 bytes
opts	`...SandboxOption`	Functional options — see Options

Returns

Type	Description
`*Sandbox`	Running sandbox
`error`	Typed `*Error` — see Error Handling

sb, err := m.CreateSandbox(ctx, "my-sandbox",
    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()
}()

StartSandbox()

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

Restart a previously stopped sandbox. The VM reboots using the persisted configuration. Parameters

Name	Type	Description
ctx	`context.Context`	Cancels the boot operation
name	`string`	Name of a stopped sandbox, up to 128 UTF-8 bytes

Returns

Type	Description
`*Sandbox`	Running sandbox

StartSandboxDetached()

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

Boot a stopped sandbox in detached mode.

GetSandbox()

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

Look up a sandbox by name and return a metadata handle without connecting to it. Sandbox names are limited to 128 UTF-8 bytes. Returns ErrSandboxNotFound if no such sandbox exists. The returned *SandboxHandle exposes Connect, Start, Stop, Kill, Remove, Metrics, and Logs.

ListSandboxes()

func ListSandboxes(ctx context.Context) ([]*SandboxHandle, error)

Return metadata for every known sandbox (running, stopped, draining, crashed) ordered by creation time, newest first.

RemoveSandbox()

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

Delete a stopped sandbox and all its persisted state from disk. Fails with ErrSandboxStillRunning if the sandbox is still running.

AllSandboxMetrics()

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

Return a point-in-time metrics snapshot for every running sandbox, keyed by sandbox name. Only running and draining sandboxes appear.

Instance methods

The *Sandbox returned by CreateSandbox and friends has the following methods. *Sandbox is safe for concurrent use from multiple goroutines.

Name()

func (s *Sandbox) Name() string

Return the sandbox’s name.

FS()

func (s *Sandbox) FS() *SandboxFsOps

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

Exec()

func (s *Sandbox) Exec(
    ctx context.Context,
    cmd string,
    args []string,
    opts ...ExecOption,
) (*ExecOutput, error)

Run a command inside the sandbox and wait for it to complete. Collects all stdout and stderr into memory and returns them along with the exit code. For long-running processes or large output, use ExecStream. A non-zero exit code is not a Go error — inspect ExecOutput.Success or ExecOutput.ExitCode instead. Transport, timeout, and spawn failures are returned as errors.

out, err := sb.Exec(ctx, "python3", []string{"-c", "print(1 + 1)"})
if err != nil {
    return err
}
fmt.Println(out.Stdout())    // "2\n"
fmt.Println(out.ExitCode())  // 0

See Execution for ExecOption details.

ExecStream()

func (s *Sandbox) ExecStream(
    ctx context.Context,
    cmd string,
    args []string,
    opts ...ExecOption,
) (*ExecHandle, error)

Run a command with streaming output. Returns a handle that emits Started, Stdout, Stderr, Exited, and Done events as they happen. The handle MUST be closed with Close when done. See ExecHandle for the event loop.

Shell()

func (s *Sandbox) Shell(
    ctx context.Context,
    command string,
    opts ...ExecOption,
) (*ExecOutput, error)

Run a command through /bin/sh -c. Shell syntax like pipes, redirects, and && chains works.

out, err := sb.Shell(ctx, "ls -la /app && echo done")

ShellStream()

func (s *Sandbox) ShellStream(
    ctx context.Context,
    command string,
    opts ...ExecOption,
) (*ExecHandle, error)

Shell command with streaming output.

Attach()

func (s *Sandbox) Attach(ctx context.Context, cmd string, args ...string) (int, error)

Bridge the caller’s terminal directly to a process inside the sandbox for a fully interactive PTY session. The caller’s terminal must be a real TTY; primarily useful for CLI tools, not library code. Returns

Type	Description
`int`	Exit code of the process

AttachShell()

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

Attach to the sandbox’s default shell (configured via WithShell, defaults to /bin/sh).

Stop()

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

Gracefully shut down the sandbox and wait until stopped state is observed. Pass WithStopTimeout(...) to control the graceful shutdown window before force-kill.

RequestStop()

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

Request graceful shutdown and return once the request is sent.

Kill()

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

Force-terminate the sandbox and wait until stopped state is observed. Pass WithKillTimeout(...) to control the observation timeout.

RequestKill()

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

Request force termination and return once the request is sent.

RequestDrain()

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

Request graceful drain and return once the request is sent.

WaitUntilStopped()

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

Block until the sandbox is observed in terminal state.

Detach()

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

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. After Detach, the handle is invalid; a subsequent Close returns ErrInvalidHandle.

Close()

func (s *Sandbox) Close() error

Release the Rust-side handle. Safe to call multiple times; the second call returns ErrInvalidHandle. For a sandbox created with WithDetached, Close will stop the VM — use Detach instead if the intent is to leave it running.

OwnsLifecycle()

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

Report whether this handle owns the VM process. When true, closing or stopping the handle terminates the sandbox; when false the sandbox is detached.

OwnsLifecycleOrFalse()

func (s *Sandbox) OwnsLifecycleOrFalse() bool

Convenience that swallows the error and returns false on any failure. Suitable for log lines and best-effort branching.

RemoveSandbox()

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

Remove a stopped sandbox’s persisted state by name.

Metrics()

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

Get a point-in-time snapshot of the sandbox’s resource usage.

metrics, err := sb.Metrics(ctx)
fmt.Printf("CPU: %.1f%% Mem: %d bytes Uptime: %s\n",
    metrics.CPUPercent, metrics.MemoryBytes, metrics.Uptime)

Logs()

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

Read persisted sandbox output. Works for running and stopped sandboxes.

entries, err := sb.Logs(ctx, m.LogOptions{
    Sources: []m.LogSource{m.LogSourceStdout, m.LogSourceStderr},
})

MetricsStream()

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

Start a streaming metrics subscription that delivers a snapshot every interval. Sub-millisecond precision is rounded up. Close the returned handle when done.

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%%  Mem: %d bytes\n", metrics.CPUPercent, metrics.MemoryBytes)
}

Patch

Helpers that construct rootfs patches for WithPatches. Access via the package-level Patch value. Each method returns a 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. See Patches for conceptual context.

Patch.Text()

func (patchFactory) Text(path, content string, opts PatchOptions) PatchConfig

Write UTF-8 text content at path.

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.

Patch.Mkdir()

func (patchFactory) Mkdir(path string, opts PatchOptions) PatchConfig

Create a directory. Only opts.Mode is honoured; Replace is ignored (the operation is idempotent).

Patch.Remove()

func (patchFactory) Remove(path string) PatchConfig

Delete a file or directory. Idempotent.

Patch.Symlink()

func (patchFactory) Symlink(target, link string, opts PatchOptions) PatchConfig

Create a symlink at link pointing to target. Only opts.Replace is honoured.

Patch.CopyFile()

func (patchFactory) CopyFile(src, dst string, opts PatchOptions) PatchConfig

Copy a single host file at src into the guest rootfs at dst.

Patch.CopyDir()

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

Init

Helpers that construct InitConfig values for WithInit to hand off PID 1 inside the guest after agentd setup. Access via the package-level Init value. See Custom init system for image picks and shutdown semantics.

Init.Auto()

func (initFactory) Auto() InitConfig

Probe common init paths inside the guest (/sbin/init, /lib/systemd/systemd, …).

m.WithInit(m.Init.Auto())

Init.Cmd()

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

Specify the init binary explicitly with optional argv/env. cmd must be an absolute path inside the guest rootfs.

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

Options

Functional options for CreateSandbox. Most options merge across repeated calls; WithImage and similar single-value setters replace.

WithImage()

func WithImage(image string) SandboxOption

OCI image, local path, or disk image (e.g. "python:3.12", "docker.io/library/alpine"). Use WithImageDisk when a disk-image root needs an explicit filesystem type. Required unless WithSnapshot is used.

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.

WithImageDisk()

func WithImageDisk(path string, fstype string) SandboxOption

Use a disk image as the root filesystem and optionally provide the inner filesystem type, for example "ext4". The disk format is inferred from the path extension (.qcow2, .raw, or .vmdk).

WithSnapshot()

func WithSnapshot(pathOrName string) SandboxOption

Boot from a snapshot artifact by bare name or filesystem path. Mutually exclusive with WithImage. See Snapshots.

WithMemory()

func WithMemory(mebibytes uint32) SandboxOption

Guest memory in MiB. This is a limit, not a reservation.

WithCPUs()

func WithCPUs(cpus uint8) SandboxOption

Virtual CPUs.

WithWorkdir()

func WithWorkdir(path string) SandboxOption

Default working directory for commands.

WithShell()

func WithShell(shell string) SandboxOption

Shell binary used by Sandbox.Shell and Sandbox.AttachShell. Defaults to /bin/sh on most images.

WithSecurityProfile()

func WithSecurityProfile(profile SecurityProfile) SandboxOption

Set the in-guest security profile. Use SecurityProfileRestricted for stronger hardening that sets no_new_privs, drops mount-admin capability from user commands, and forces nosuid,nodev on user mounts.

WithEnv()

func WithEnv(env map[string]string) SandboxOption

Environment variables visible to all commands. Called repeatedly, the maps merge; later keys overwrite earlier ones.

WithHostname()

func WithHostname(hostname string) SandboxOption

Guest hostname.

WithUser()

func WithUser(user string) SandboxOption

Default user (UID or name) to run sandbox commands as.

WithReplace()

func WithReplace() SandboxOption

Replace any existing sandbox with the same name. Sends SIGTERM, waits up to 10s for graceful exit, then escalates to SIGKILL.

WithReplaceWithTimeout()

func WithReplaceWithTimeout(timeout time.Duration) SandboxOption

Like WithReplace but with a caller-specified timeout between SIGTERM and SIGKILL. Implies WithReplace. A zero duration skips SIGTERM and SIGKILLs immediately.

WithDetached()

func WithDetached() SandboxOption

Create the sandbox in detached mode. The VM continues running after the Go process exits.

WithEntrypoint()

func WithEntrypoint(cmd ...string) SandboxOption

Override the image’s stored ENTRYPOINT. Consulted by msb exec / msb run (CLI command resolution against this sandbox), not by Sandbox.Exec / Sandbox.Shell — those pass cmd literally to the guest agent. Use this when configuring sandboxes via the SDK for later CLI attachment. For PID 1 handoff, use WithInit instead.

WithInit()

func WithInit(cfg InitConfig) SandboxOption

Hand off PID 1 to a guest init binary. Construct cfg via Init.

WithLogLevel()

func WithLogLevel(level LogLevel) SandboxOption

Override the sandbox process log verbosity. See LogLevel.

WithQuietLogs()

func WithQuietLogs() SandboxOption

Suppress sandbox-level log output entirely.

WithScripts()

func WithScripts(scripts map[string]string) SandboxOption

Named scripts mounted at /.msb/scripts/<name>. Called repeatedly, entries merge.

WithPullPolicy()

func WithPullPolicy(p PullPolicy) SandboxOption

Image pull behaviour. See PullPolicy.

WithMaxDuration()

func WithMaxDuration(d time.Duration) SandboxOption

Maximum sandbox lifetime. Zero means unlimited. Sub-second precision is rounded up to whole seconds.

WithIdleTimeout()

func WithIdleTimeout(d time.Duration) SandboxOption

Stop the sandbox after this much wall-clock time without exec activity. Zero means unlimited.

WithRegistryAuth()

func WithRegistryAuth(auth RegistryAuth) SandboxOption

Credentials for pulling from a private OCI registry. See RegistryAuth.

WithPorts()

func WithPorts(ports map[uint16]uint16) SandboxOption

Publish host TCP ports into the sandbox (map key = host port, value = guest port). The default host bind address is 127.0.0.1.

WithPortBindings()

func WithPortBindings(bindings ...PortBinding) SandboxOption

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

WithPortsUDP()

func WithPortsUDP(ports map[uint16]uint16) SandboxOption

Publish host UDP ports into the sandbox. The default host bind address is 127.0.0.1.

WithNetwork()

func WithNetwork(net *NetworkConfig) SandboxOption

Configure the network stack — preset, custom rules, DNS, TLS interception. See Networking.

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

WithPatches()

func WithPatches(patches ...PatchConfig) SandboxOption

Append rootfs patches applied before the VM boots. Patches are only compatible with OverlayFS rootfs (not disk images). Construct via Patch.

WithMounts()

func WithMounts(mounts map[string]MountConfig) SandboxOption

Volume mount configurations keyed by guest path. See Volumes.

SandboxHandle

A lightweight metadata reference to a sandbox returned by GetSandbox and ListSandboxes. Holds last-known name, status, config JSON, and timestamps; offers lifecycle methods that operate on the sandbox without an active connection. Call Connect or Start to upgrade to a full *Sandbox.

Method	Returns	Description
`Name()`	`string`	Sandbox name, up to 128 UTF-8 bytes
`Status()`	`SandboxStatus`	Last-known lifecycle status
`ConfigJSON()`	`string`	Raw JSON configuration
`CreatedAt()`	`time.Time`	Creation time, zero value if unknown
`UpdatedAt()`	`time.Time`	Last-update time, zero value if unknown
`Metrics(ctx)`	`(*Metrics, error)`	Point-in-time resource metrics
`Logs(ctx, opts)`	`([]LogEntry, error)`	Persisted sandbox logs
`Connect(ctx)`	`(*Sandbox, error)`	Reattach to the running sandbox
`Start(ctx)`	`(*Sandbox, error)`	Boot a stopped sandbox in attached mode
`StartDetached(ctx)`	`(*Sandbox, error)`	Boot a stopped sandbox in detached mode
`Stop(ctx)`	`error`	Graceful shutdown
`Kill(ctx)`	`error`	Force terminate
`Remove(ctx)`	`error`	Delete sandbox and persisted state
`Snapshot(ctx, name)`	`(*SnapshotArtifact, error)`	Snapshot stopped/crashed sandbox under a bare name
`SnapshotTo(ctx, path)`	`(*SnapshotArtifact, error)`	Snapshot stopped/crashed sandbox to an explicit path

Types

SandboxConfig

The config struct populated by SandboxOption functions. Most callers build a sandbox via CreateSandbox(ctx, name, ...opts); SandboxConfig is exported for callers that prefer to construct a value directly and pass its fields explicitly.

Field	Type	Description
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`	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
Detached	`bool`	If `true`, sandbox survives after process exits
Entrypoint	`[]string`	Override image entrypoint
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→guest TCP port mappings
PortsUDP	`map[uint16]uint16`	Host→guest UDP port mappings
PortBindings	`[]PortBinding`	Host→guest 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

type SandboxOption func(*SandboxConfig)

A functional option for CreateSandbox. All WithX helpers listed above return a SandboxOption.

SecurityProfile

type SecurityProfile string

const (
    SecurityProfileDefault    SecurityProfile = "default"
    SecurityProfileRestricted SecurityProfile = "restricted"
)

Sandbox-wide in-guest security profile.

InitConfig

Custom init specification.

Field	Type	Description
Cmd	`string`	Absolute path or `"auto"` to the init binary inside the guest rootfs
Args	`[]string`	Supplemental argv (`argv[0]` is implicitly `Cmd`)
Env	`map[string]string`	Extra env vars merged on top of the inherited env

InitOptions

Tuning struct for Init.Cmd.

Field	Type	Description
Args	`[]string`	Supplemental argv
Env	`map[string]string`	Extra env vars

RegistryAuth

Private registry credentials.

Field	Type	Description
Username	`string`	Registry username
Password	`string`	Registry password

PatchConfig

A single rootfs patch produced by Patch.

Field	Type	Description
Kind	`PatchKind`	Patch flavour
Path	`string`	Absolute guest path (text / file / mkdir / remove / append)
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

Tuning struct passed to Patch methods.

Field	Type	Description
Mode	`*uint32`	File or directory mode
Replace	`bool`	Overwrite an existing path

PatchKind

type PatchKind string

Constant	Value
`PatchKindText`	`"text"`
`PatchKindAppend`	`"append"`
`PatchKindMkdir`	`"mkdir"`
`PatchKindRemove`	`"remove"`
`PatchKindSymlink`	`"symlink"`
`PatchKindCopyFile`	`"copy_file"`
`PatchKindCopyDir`	`"copy_dir"`

PullPolicy

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

LogOptions

Filters for Logs.

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 uses the runtime default

LogEntry

One persisted log entry.

Field	Type	Description
Source	`LogSource`	Origin of the captured data
SessionID	`*uint64`	Relay session ID, nil for system entries
Timestamp	`time.Time`	Capture timestamp
Data	`[]byte`	Captured bytes

Method	Returns	Description
`Text()`	`string`	Captured bytes as a string

LogSource

type LogSource string

Constant	Value
`LogSourceStdout`	`"stdout"`
`LogSourceStderr`	`"stderr"`
`LogSourceOutput`	`"output"`
`LogSourceSystem`	`"system"`

LogLevel

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

SandboxStatus

type SandboxStatus string

Constant	Value	Description
`SandboxStatusRunning`	`"running"`	Guest agent is ready
`SandboxStatusStopped`	`"stopped"`	VM shut down; can be restarted
`SandboxStatusCrashed`	`"crashed"`	VM exited unexpectedly
`SandboxStatusDraining`	`"draining"`	Graceful shutdown in progress
`SandboxStatusPaused`	`"paused"`	VM is paused

Metrics

Point-in-time resource usage snapshot returned by Metrics.

Field	Type	Description
CPUPercent	`float64`	CPU usage as a percentage
MemoryBytes	`uint64`	Current memory usage in bytes
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
Uptime	`time.Duration`	Time since the sandbox was created

MetricsStreamHandle

Live metrics subscription returned by MetricsStream.

Method	Returns	Description
`Recv(ctx)`	`(*Metrics, error)`	Block until the next snapshot arrives. Returns `(nil, nil)` when the stream ends
`Close()`	`error`	Stop the stream and release Rust-side resources

​Setup

​EnsureInstalled()

​IsInstalled()

​SDKVersion()

​RuntimeVersion()

​SetupOption

​WithSkipDownload()

​Top-level functions

​CreateSandbox()

​StartSandbox()

​StartSandboxDetached()

​GetSandbox()

​ListSandboxes()

​RemoveSandbox()

​AllSandboxMetrics()

​Instance methods

​Name()

​FS()

​Exec()

​ExecStream()

​Shell()

​ShellStream()

​Attach()

​AttachShell()

​Stop()

​RequestStop()

​Kill()

​RequestKill()

​RequestDrain()

​WaitUntilStopped()

​Detach()

​Close()

​OwnsLifecycle()

​OwnsLifecycleOrFalse()

​RemoveSandbox()

​Metrics()

​Logs()

​MetricsStream()

​Patch

​Patch.Text()

​Patch.Append()

​Patch.Mkdir()

​Patch.Remove()

​Patch.Symlink()

​Patch.CopyFile()

​Patch.CopyDir()

​Init

​Init.Auto()

​Init.Cmd()

​Options

​WithImage()

​WithOCIUpperSize()

​WithImageDisk()

​WithSnapshot()

​WithMemory()

​WithCPUs()

​WithWorkdir()

​WithShell()

​WithSecurityProfile()

​WithEnv()

​WithHostname()

​WithUser()

​WithReplace()

​WithReplaceWithTimeout()

​WithDetached()

​WithEntrypoint()

​WithInit()

​WithLogLevel()

​WithQuietLogs()

​WithScripts()

​WithPullPolicy()

​WithMaxDuration()

​WithIdleTimeout()

​WithRegistryAuth()

​WithPorts()

​WithPortBindings()

​WithPortsUDP()

​WithNetwork()

​WithSecrets()

​WithPatches()

Setup

EnsureInstalled()

IsInstalled()

SDKVersion()

RuntimeVersion()

SetupOption

WithSkipDownload()

Top-level functions

CreateSandbox()

StartSandbox()

StartSandboxDetached()

GetSandbox()

ListSandboxes()

RemoveSandbox()

AllSandboxMetrics()

Instance methods

Name()

FS()

Exec()

ExecStream()

Shell()

ShellStream()

Attach()

AttachShell()

Stop()

RequestStop()

Kill()

RequestKill()

RequestDrain()

WaitUntilStopped()

Detach()

Close()

OwnsLifecycle()

OwnsLifecycleOrFalse()

RemoveSandbox()

Metrics()

Logs()

MetricsStream()

Patch

Patch.Text()

Patch.Append()

Patch.Mkdir()

Patch.Remove()

Patch.Symlink()

Patch.CopyFile()

Patch.CopyDir()

Init

Init.Auto()

Init.Cmd()

Options

WithImage()

WithOCIUpperSize()

WithImageDisk()

WithSnapshot()

WithMemory()

WithCPUs()

WithWorkdir()

WithShell()

WithSecurityProfile()

WithEnv()

WithHostname()

WithUser()

WithReplace()

WithReplaceWithTimeout()

WithDetached()

WithEntrypoint()

WithInit()

WithLogLevel()

WithQuietLogs()

WithScripts()

WithPullPolicy()

WithMaxDuration()

WithIdleTimeout()

WithRegistryAuth()

WithPorts()

WithPortBindings()

WithPortsUDP()

WithNetwork()

WithSecrets()

WithPatches()