docs/sdk/go/sandbox.mdx
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.
func CreateSandbox(ctx context.Context, name string, opts ...SandboxOption) (*Sandbox, error)
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.
func GetSandbox(ctx context.Context, name string) (*SandboxHandle, error)
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.
func ListSandboxes(ctx context.Context) (*SandboxPage, error)
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.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">*SandboxPage</span></div> <div className="msb-param-desc">Handles in this page and an optional cursor for the next page.</div> </div> </div>func ListSandboxesWith(ctx context.Context, options ...SandboxListOption) (*SandboxPage, error)
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>options</code><span className="msb-type">...SandboxListOption</span></div> <div className="msb-param-desc"><code>WithListLimit</code>, <code>WithListCursor</code>, and/or <code>WithListLabels</code> options.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">*SandboxPage</span></div> <div className="msb-param-desc">Matching handles and an optional cursor for the next page.</div> </div> </div>func StartSandbox(ctx context.Context, name string) (*Sandbox, error)
sb, err := m.StartSandbox(ctx, "api")
Restart a previously stopped sandbox. The VM reboots using the persisted configuration and returns a live *Sandbox.
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>name</code><span className="msb-type">string</span></div> <div className="msb-param-desc">Name of a stopped sandbox, up to 128 UTF-8 bytes.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#methods">*Sandbox</a></div> <div className="msb-param-desc">Running sandbox in detached mode.</div> </div> </div>func RemoveSandbox(ctx context.Context, name string) error
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>name</code><span className="msb-type">string</span></div> <div className="msb-param-desc">Sandbox name, up to 128 UTF-8 bytes.</div> </div> </div><Tooltip tip="Resource metrics are not available on microsandbox cloud; use an external monitoring system."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
func AllSandboxMetrics(ctx context.Context) (map[string]*Metrics, error)
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.
<span id="m-ensureinstalled"></span> <span id="m-isinstalled"></span> <span id="m-sdkversion"></span> <span id="m-runtimeversion"></span>
Runtime installation and verification helpers are documented under Runtime setup. The Go-only version helpers are under Inspect Go versions.
A live sandbox connection that is safe for concurrent use.
func (s *Sandbox) Name() string
Return the sandbox name.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">string</span></div> <div className="msb-param-desc">Sandbox name, up to 128 UTF-8 bytes.</div> </div> </div>func (s *Sandbox) FS() *SandboxFSOps
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.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="/sdk/go/filesystem">*SandboxFSOps</a></div> <div className="msb-param-desc">Filesystem accessor.</div> </div> </div>func (s *Sandbox) SSH() *SandboxSSHOps
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.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="/sdk/go/ssh">*SandboxSSHOps</a></div> <div className="msb-param-desc">SSH accessor.</div> </div> </div><Tooltip tip="Bounded log reads are not available on microsandbox cloud; follow live with log streaming and persist output externally."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
func (s *Sandbox) Logs(ctx context.Context, opts LogOptions) ([]LogEntry, error)
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.
<Tooltip tip="On microsandbox cloud, log streaming is follow-only; set follow. Bounded, non-follow reads are not available."><span className="msb-badge-limited">Limited on cloud <Icon icon="circle-info" size={11} /></span></Tooltip>
func (s *Sandbox) LogStream(ctx context.Context, opts LogStreamOptions) (*LogStreamHandle, error)
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.
<Tooltip tip="Not available on microsandbox cloud."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
func (s *Sandbox) Ping(ctx context.Context) (*SandboxPingResult, error)
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.
<Tooltip tip="Not available on microsandbox cloud."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
func (s *Sandbox) Touch(ctx context.Context) (*SandboxTouchResult, error)
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.
<Tooltip tip="modify is not available on microsandbox cloud; recreate the sandbox with the new configuration."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
func (s *Sandbox) Modify(ctx context.Context, opts ModifyOptions) (*SandboxModificationPlan, error)
// 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.
<Tooltip tip="Resource metrics are not available on microsandbox cloud; use an external monitoring system."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
func (s *Sandbox) Metrics(ctx context.Context) (*Metrics, error)
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.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#metrics">*Metrics</a></div> <div className="msb-param-desc">Resource snapshot.</div> </div> </div><Tooltip tip="Resource metrics are not available on microsandbox cloud; use an external monitoring system."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
func (s *Sandbox) MetricsStream(ctx context.Context, interval time.Duration) (*MetricsStreamHandle, error)
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.
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>cmd</code><span className="msb-type">string</span></div> <div className="msb-param-desc">Command to run.</div> </div> <div className="msb-param"> <div className="msb-param-key"><code>args</code><span className="msb-type">...string</span></div> <div className="msb-param-desc">Command arguments.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">int</span></div> <div className="msb-param-desc">Exit code of the process.</div> </div> </div>func (s *Sandbox) AttachWith(ctx context.Context, cmd string, args []string, opts ...AttachOption) (int, error)
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.
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.
func (s *Sandbox) Stop(ctx context.Context, opts ...StopOption) error
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.
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.
<Tooltip tip="Not available on microsandbox cloud; use a graceful stop."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
func (s *Sandbox) Kill(ctx context.Context, opts ...KillOption) error
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.
<Tooltip tip="Not available on microsandbox cloud; use a graceful stop."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
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.
<Tooltip tip="Not available on microsandbox cloud; use a graceful stop."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
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.
func (s *Sandbox) WaitUntilStopped(ctx context.Context) (*SandboxStopResult, error)
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.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#sandboxstopresult">*SandboxStopResult</a></div> <div className="msb-param-desc">Terminal status, exit code, and signal.</div> </div> </div>func (s *Sandbox) Detach(ctx context.Context) error
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.
<Tooltip tip="On microsandbox cloud this does not stop the sandbox; the cloud handle does not own the host process, so call stop() or remove() explicitly."><span className="msb-badge-limited">Limited on cloud <Icon icon="circle-info" size={11} /></span></Tooltip>
func (s *Sandbox) Close() error
defer sb.Close()
Release the Rust-side handle. Safe to call multiple times; the second call returns an error with Kind == ErrInvalidHandle. For a sandbox created with WithDetached, Close stops the VM. Use Detach instead to leave it running.
<Tooltip tip="On microsandbox cloud this is false; the cloud worker owns the sandbox process, not your handle."><span className="msb-badge-note">On cloud <Icon icon="circle-info" size={11} /></span></Tooltip>
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 when you don't care.
<Tooltip tip="On microsandbox cloud this is false; the cloud worker owns the sandbox process, not your handle."><span className="msb-badge-note">On cloud <Icon icon="circle-info" size={11} /></span></Tooltip>
func (s *Sandbox) OwnsLifecycleOrFalse() bool
Convenience wrapper around OwnsLifecycle that swallows the error and returns false on any failure. Suitable for log lines and best-effort branching.
Functional options for creating and listing sandboxes. Map and slice options merge across repeated calls; single-value setters like WithImage replace.
func WithListLimit(limit uint32) SandboxListOption
Set the maximum number of sandboxes returned in a page. The limit must be between 1 and 100.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>limit</code><span className="msb-type">uint32</span></div> <div className="msb-param-desc">Maximum number of sandboxes in the page.</div> </div> </div>func WithListCursor(cursor string) SandboxListOption
Continue listing after a previous page's NextCursor. Keep the same label filters when requesting the next page.
func WithListLabels(labels map[string]string) SandboxListOption
Require every supplied label. Repeated selectors are AND-matched.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>labels</code><span className="msb-type">map[string]string</span></div> <div className="msb-param-desc">Label key-value pairs that every result must match.</div> </div> </div><Tooltip tip="On microsandbox cloud, only OCI image references are accepted; host-directory and disk-image root filesystems are local-only."><span className="msb-badge-note">On cloud <Icon icon="circle-info" size={11} /></span></Tooltip>
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.
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>mebibytes</code><span className="msb-type">uint32</span></div> <div className="msb-param-desc">Upper layer size in MiB.</div> </div> </div><Tooltip tip="Disk-image root filesystems are not available on microsandbox cloud; use an OCI image."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
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).
func WithFromSnapshot(pathOrName string) SandboxOption
Boot from a snapshot artifact by bare name or filesystem path. Mutually exclusive with WithImage. See Snapshots.
func WithMemory(mebibytes uint32) SandboxOption
Set the guest memory limit in MiB. This is a limit, not an upfront reservation. Default: 512 MiB.
<Tooltip tip="On microsandbox cloud these ceilings are not carried; the maximum is pinned to the initial value. Recreate the sandbox to resize."><span className="msb-badge-note">On cloud <Icon icon="circle-info" size={11} /></span></Tooltip>
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>mebibytes</code><span className="msb-type">uint32</span></div> <div className="msb-param-desc">Maximum memory in MiB.</div> </div> </div>func WithTHP(policy THPPolicy) SandboxOption
Select the guest transparent huge-page policy applied through the kernel command line at boot. Default: THPMadvise.
func WithCPUs(cpus uint8) SandboxOption
Set the number of virtual CPUs. This is a limit, not a reservation. Default: 1.
<Tooltip tip="On microsandbox cloud these ceilings are not carried; the maximum is pinned to the initial value. Recreate the sandbox to resize."><span className="msb-badge-note">On cloud <Icon icon="circle-info" size={11} /></span></Tooltip>
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>cpus</code><span className="msb-type">uint8</span></div> <div className="msb-param-desc">Maximum possible vCPUs.</div> </div> </div>func WithWorkdir(path string) SandboxOption
Set the default working directory for all commands.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>path</code><span className="msb-type">string</span></div> <div className="msb-param-desc">Absolute path inside the guest.</div> </div> </div>func WithShell(shell string) SandboxOption
Set the shell used by Shell and AttachShell. Defaults to /bin/sh on most images.
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.
func WithEnv(env map[string]string) SandboxOption
Set environment variables visible to all commands. Called repeatedly, the maps merge; later keys overwrite earlier ones.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>env</code><span className="msb-type">map[string]string</span></div> <div className="msb-param-desc">Environment variables.</div> </div> </div>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..
func WithLabel(key, value string) SandboxOption
Attach a single label. Shorthand for WithLabels with one entry.
<Tooltip tip="On microsandbox cloud, the hostname is assigned by the platform; a value set here is ignored."><span className="msb-badge-note">On cloud <Icon icon="circle-info" size={11} /></span></Tooltip>
func WithHostname(hostname string) SandboxOption
Set the guest hostname.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>hostname</code><span className="msb-type">string</span></div> <div className="msb-param-desc">Hostname.</div> </div> </div>func WithUser(user string) SandboxOption
Set the default guest user (UID or name) for all commands.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>user</code><span className="msb-type">string</span></div> <div className="msb-param-desc">User name or UID.</div> </div> </div><Tooltip tip="Replace-on-create is not available on microsandbox cloud; remove the existing sandbox first."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
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.
<Tooltip tip="Replace-on-create is not available on microsandbox cloud; remove the existing sandbox first."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
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.
func WithDetached() SandboxOption
Create the sandbox in detached mode. The VM continues running after the Go process exits; reattach via GetSandbox. Close stops a detached sandbox; use Detach to leave it running.
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>ephemeral</code><span className="msb-type">bool</span></div> <div className="msb-param-desc"><code>true</code> to delete all state on termination.</div> </div> </div>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.
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"),
)
func WithInit(cfg InitConfig) SandboxOption
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.
func WithLogLevel(level LogLevel) SandboxOption
Override the sandbox process's log verbosity. See LogLevel.
func WithQuietLogs() SandboxOption
Suppress sandbox-level log output entirely.
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.
func WithPullPolicy(p PullPolicy) SandboxOption
Control when the OCI image is pulled from the registry. See PullPolicy.
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>d</code><span className="msb-type">time.Duration</span></div> <div className="msb-param-desc">Maximum lifetime.</div> </div> </div>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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>d</code><span className="msb-type">time.Duration</span></div> <div className="msb-param-desc">Idle timeout.</div> </div> </div>func WithRegistryAuth(auth RegistryAuth) SandboxOption
Set credentials for pulling from a private OCI registry. See RegistryAuth.
func WithRegistryInsecure() SandboxOption
Use plain HTTP for the registry instead of HTTPS, for local or self-hosted registries served without TLS such as localhost:5050/my-app:latest. The cloud backend rejects this override.
func WithRegistryCACerts(pem []byte) SandboxOption
Trust additional PEM-encoded CA certificates when pulling, for registries served with a private certificate authority. Called repeatedly, the bundles accumulate. The cloud backend rejects this override.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>pem</code><span className="msb-type">[]byte</span></div> <div className="msb-param-desc">PEM-encoded CA certificates.</div> </div> </div>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. The cloud backend rejects this override.
<Tooltip tip="Publishing host ports is not available on microsandbox cloud."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
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.
<Tooltip tip="Publishing host ports is not available on microsandbox cloud."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
func WithPortsUDP(ports map[uint16]uint16) SandboxOption
Publish guest UDP ports onto host ports. The default host bind address is 127.0.0.1.
<Tooltip tip="Publishing host ports is not available on microsandbox cloud."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
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.
func WithNetwork(net *NetworkConfig) SandboxOption
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.
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.
func WithPatches(patches ...PatchConfig) SandboxOption
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.
func WithMounts(mounts map[string]MountConfig) SandboxOption
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.
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.
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.
<span id="withskipdownload"></span>
The setup-only WithSkipDownload() option is documented under Runtime setup.
func WithAttachCwd(path string) AttachOption
Set the working directory for the attached session. Defaults to the sandbox's workdir.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>path</code><span className="msb-type">string</span></div> <div className="msb-param-desc">Absolute path inside the guest.</div> </div> </div>func WithAttachUser(user string) AttachOption
Run the attached session as the given guest user instead of the sandbox's default user (set via WithUser).
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>env</code><span className="msb-type">map[string]string</span></div> <div className="msb-param-desc">Environment variables to set.</div> </div> </div>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.
Factory for PatchConfig values.
func (patchFactory) Text(path, content string, opts PatchOptions) PatchConfig
Write UTF-8 text content at path.
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.
<Tooltip tip="On microsandbox cloud, host sources resolve against your organization's host volume, not the computer running the SDK or CLI."><span className="msb-badge-note">On cloud <Icon icon="circle-info" size={11} /></span></Tooltip>
func (patchFactory) Mkdir(path string, opts PatchOptions) PatchConfig
Create a directory. Idempotent. Only opts.Mode is honored; Replace is ignored.
func (patchFactory) Remove(path string) PatchConfig
Delete a file or directory at path. Idempotent.
func (patchFactory) Symlink(target, link string, opts PatchOptions) PatchConfig
Create a symlink at link pointing to target. Only opts.Replace is honored.
<Tooltip tip="On microsandbox cloud, host sources resolve against your organization's host volume, not the computer running the SDK or CLI."><span className="msb-badge-note">On cloud <Icon icon="circle-info" size={11} /></span></Tooltip>
func (patchFactory) CopyFile(src, dst string, opts PatchOptions) PatchConfig
Copy a single host file at src into the guest rootfs at dst.
<Tooltip tip="On microsandbox cloud, host sources resolve against your organization's host volume, not the computer running the SDK or CLI."><span className="msb-badge-note">On cloud <Icon icon="circle-info" size={11} /></span></Tooltip>
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.
Factory for InitConfig values.
func (initFactory) Auto() InitConfig
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.
func (initFactory) Cmd(cmd string, opts InitOptions) InitConfig
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.
A sandbox metadata and lifecycle handle that does not require an active guest-agent connection.
Name()
Sandbox name, up to 128 UTF-8 bytes
<p className="msb-label">Returns</p>string
Status()
Last-known lifecycle status
<p className="msb-label">Returns</p>ConfigJSON()
Raw JSON configuration
<p className="msb-label">Returns</p>string
Config()
Parsed configuration
<p className="msb-label">Returns</p>(*SandboxConfig, error)
CreatedAt()
Creation time, zero value if unknown
<p className="msb-label">Returns</p>time.Time
UpdatedAt()
Last-update time, zero value if unknown
<p className="msb-label">Returns</p>time.Time
Refresh(ctx)
Fresh handle for the same name
<p className="msb-label">Returns</p>(*SandboxHandle, error)
Ping(ctx)
Check agent reachability without refreshing idle activity; does not start stopped sandboxes
<p className="msb-label">Returns</p>(*SandboxPingResult, error)
Touch(ctx)
Explicitly refresh idle activity; does not start stopped sandboxes
<p className="msb-label">Returns</p>(*SandboxTouchResult, error)
Modify(ctx, opts)
Plan or apply a configuration change; same ModifyOptions as Modify(). Does not start stopped sandboxes; changes persist for the next boot
(*SandboxModificationPlan, error)
Metrics(ctx)
Point-in-time resource metrics
<p className="msb-label">Returns</p>(*Metrics, error)
Logs(ctx, opts)
Read captured exec.log (works without starting)
([]LogEntry, error)
LogStream(ctx, opts)
Stream captured output
<p className="msb-label">Returns</p>(*LogStreamHandle, error)
Connect(ctx)
Reattach to the running sandbox
<p className="msb-label">Returns</p>(*Sandbox, error)
Start(ctx)
Boot a stopped sandbox in attached mode
<p className="msb-label">Returns</p>(*Sandbox, error)
StartDetached(ctx)
Boot a stopped sandbox in detached mode
<p className="msb-label">Returns</p>(*Sandbox, error)
Stop(ctx, opts...)
Graceful shutdown; accepts StopOption
error
RequestStop(ctx)
Async stop request
<p className="msb-label">Returns</p>error
Kill(ctx, opts...)
Force terminate; accepts KillOption
error
RequestKill(ctx)
Async kill request
<p className="msb-label">Returns</p>error
RequestDrain(ctx)
Async drain request
<p className="msb-label">Returns</p>error
WaitUntilStopped(ctx)
Block until terminal state
<p className="msb-label">Returns</p>(*SandboxStopResult, error)
Remove(ctx)
Delete sandbox and persisted state
<p className="msb-label">Returns</p>error
Snapshot(ctx, name)
Snapshot a stopped sandbox under a bare name
<p className="msb-label">Returns</p>(*SnapshotArtifact, error)
Live metrics subscription. Call Close to release Rust-side resources.
Recv(ctx)
Block until the next snapshot arrives. Returns (nil, nil) when the stream ends (sandbox exited)
(*Metrics, error)
Close()
Stop the stream and release Rust-side resources
<p className="msb-label">Returns</p>error
A single captured log entry.
Origin of the captured data
*uint64
Relay-monotonic session id; nil for system entries
time.Time
Wall-clock capture time on the host
[]byte
The captured bytes
string
Opaque resume token; pass to LogStreamOptions.FromCursor
Text()
Captured bytes as a string
<p className="msb-label">Returns</p>string
Live log subscription. Call Close to release Rust-side resources.
Recv(ctx)
Block until the next entry arrives. Returns (nil, nil) when the stream ends
(*LogEntry, error)
Close()
Stop the stream and release Rust-side resources
<p className="msb-label">Returns</p>error
Agent reachability result.
| Field | Type | Description |
|---|---|---|
| Name | string | Sandbox name |
| Latency | time.Duration | Round-trip latency |
Explicit idle-refresh result.
| Field | Type | Description |
|---|---|---|
| Name | string | Sandbox name |
| ActivitySeq | uint64 | Monotonic activity sequence after the touch |
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 |
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 |
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 |
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 |
Functional options accepted by ListSandboxesWith.
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 |
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.
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-] |
type AttachOption func(*AttachConfig)
A functional option that mutates an AttachConfig. Construct them with the WithAttach* functions below.
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
Credentials for a private OCI registry.
| Field | Type | Description |
|---|---|---|
| Username | string | Registry username |
| Password | string | Registry password |
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 |
Tuning struct for Init.Cmd beyond the required cmd.
| Field | Type | Description |
|---|---|---|
| Args | []string | Supplemental argv |
| Env | map[string]string | Extra env vars |
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 |
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 |
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" |
The setup-only SetupOption type is documented under Runtime setup.