types

type BuildImageOptions ¶ added in v0.1.7

type BuildImageOptions struct {
	Push *BuildImagePushOptions
}

BuildImageOptions are optional knobs for Client.BuildImageWithOptions.

type BuildImagePushOptions ¶ added in v0.1.7

type BuildImagePushOptions struct {
	// Registry is the destination repository, e.g. "ghcr.io/my-org/my-image".
	Registry string
	// Tag is the destination tag. The daemon defaults to "latest" when empty.
	Tag string
	// Server is the registry serveraddress, e.g. "ghcr.io". Sent inside
	// X-Registry-Auth.
	Server   string
	Username string
	Password string
}

BuildImagePushOptions describes the per-request push directive for Client.BuildImageWithOptions. Credentials are forwarded to the daemon as a one-shot X-Registry-Auth header on the push call and are never persisted.

type BuildImageResult ¶ added in v0.1.7

type BuildImageResult struct {
	// Image is the local content-addressed tag (always returned).
	Image string
	// Pushed is the pushed reference (e.g. "ghcr.io/x/y:v1") when push was
	// requested, otherwise empty.
	Pushed string
}

BuildImageResult is the response from Client.BuildImageWithOptions.

type CloneGeneration ¶ added in v0.5.2

type CloneGeneration struct {
	// Generation is an opaque token that changes on every resume-from-snapshot.
	Generation string `json:"generation"`
	// ResumedAt is the host wall-clock of the last resume, in unix nanoseconds.
	// 0 means the sandbox has never been resumed.
	ResumedAt int64 `json:"resumedAt"`
}

CloneGeneration is a sandbox's clone-generation marker. Generation changes every time the sandbox is resumed from a snapshot (i.e. it is a clone). A long-lived process running inside the sandbox can poll this and reseed its own userspace PRNGs when the token changes — two clones otherwise share the snapshot's frozen seed state. Read-only: the SDK cannot reseed an in-guest process from the client side. See the "Randomness in cloned sandboxes" docs.

type CreateSandboxOptions ¶

type CreateSandboxOptions = models.CreateSandboxRequest

type CreateSessionOptions ¶

type CreateSessionOptions = models.CreateSessionRequest

type CreateTemplateOptions ¶ added in v0.4.1

type CreateTemplateOptions = models.CreateTemplateRequest

CreateTemplateOptions is the request body for Client.CreateTemplate. Supplying an explicit ID lets retries be idempotent — a duplicate ID returns 409 so a re-run CI step does not register two rows for the same logical template.

type CreateWasmModuleOptions ¶ added in v0.5.3

type CreateWasmModuleOptions = models.CreateWasmModuleRequest

CreateWasmModuleOptions is the request body for Client.CreateWasmModule.

type CustomDomain ¶ added in v0.3.1

type CustomDomain = models.CustomDomain

CustomDomain is the per-hostname row attached to a sandbox. Status moves pending_dns → issuing → ready (or failed), driven server-side by Caddy's on-demand TLS asks; clients read but never write Status.

type CustomDomainDNSRecords ¶ added in v0.3.1

type CustomDomainDNSRecords = models.CustomDomainDNSRecords

CustomDomainDNSRecords is the response body for the per-sandbox custom-domain DNS helper. Records is the flat list (one row per custom domain × per ingress address); Target is the raw aggregation Records was composed from, useful when callers want to render their own UI.

type CustomDomainStatus ¶ added in v0.3.1

type CustomDomainStatus = models.CustomDomainStatus

CustomDomainStatus enumerates the lifecycle states surfaced on CustomDomain.Status.

type DNSRecord ¶ added in v0.3.1

type DNSRecord = models.DNSRecord

DNSRecord is one ready-to-paste DNS row for a custom domain. Hostname is the full hostname; Name is the leftmost label (or "@" for apex); Value is the target. Notes carries provider-specific gotchas the daemon pre-renders.

type ExecExitInfo ¶

type ExecExitInfo struct {
	Code   int    `json:"code"`
	Signal string `json:"signal,omitempty"`
}

type ExecRequest ¶

type ExecRequest = models.ExecRequest

type ExecResult ¶

type ExecResult = models.ExecResult

type ExecStreamOptions ¶

type ExecStreamOptions struct {
	Command  string              `json:"command"`
	Workdir  string              `json:"workdir,omitempty"`
	Env      map[string]string   `json:"env,omitempty"`
	TTY      bool                `json:"tty,omitempty"`
	Cols     int                 `json:"cols,omitempty"`
	Rows     int                 `json:"rows,omitempty"`
	OnStdout StreamCallback      `json:"-"`
	OnStderr StreamCallback      `json:"-"`
	OnError  StreamErrorCallback `json:"-"`
}

type ExposeProtocol ¶ added in v0.1.6

type ExposeProtocol string

ExposeProtocol selects the wire surface an exposure publishes through.

const (
	// ExposeProtocolHTTP is the default — Caddy HTTP reverse proxy at
	// https://<id>-<port>.<domain> (or the path-mode equivalent on an
	// IP-only deployment).
	ExposeProtocolHTTP ExposeProtocol = "http"
	// ExposeProtocolTCP allocates a parent-host port from the configured
	// pool and forwards raw bytes to the container via caddy-l4.
	ExposeProtocolTCP ExposeProtocol = "tcp"
	// ExposeProtocolTLS adds a TLS-SNI route to the shared layer4 server.
	// Requires the daemon to have a domain configured AND
	// SB_L4_TLS_LISTEN set.
	ExposeProtocolTLS ExposeProtocol = "tls"
)

type ExposeResult ¶ added in v0.1.6

type ExposeResult = models.ExposePortResponse

ExposeResult is the structured outcome of a successful expose call. Host and HostPort are populated only when Protocol == ExposeProtocolTCP — for HTTP and TLS exposures the dialable URL is in URL alone.

type ExposedPort ¶

type ExposedPort = models.ExposedPort

type Failover ¶ added in v0.2.2

type Failover = models.Failover

type GPURequest ¶ added in v0.1.3

type GPURequest = models.GPURequest

type GPUVendor ¶ added in v0.1.3

type GPUVendor = models.GPUVendor

type HealthStatus ¶

type HealthStatus = models.HealthStatus

type IngressTarget ¶ added in v0.3.1

type IngressTarget = models.IngressTarget

IngressTarget is the cluster-published address(es) DNS for a custom domain must point at. Source disambiguates the shape: "hostname" — Hostname holds a stable name to CNAME at; "ips" — IPs holds one or more raw IPs to A/AAAA at; "mixed" — both are populated; "unknown" — neither is set, the cluster has not gossiped a public address yet.

type Lifecycle ¶

type Lifecycle = models.Lifecycle

type MicroVMConfig ¶

type MicroVMConfig struct {
	PATToken   string
	APIUrl     string
	HTTPClient *http.Client
	// APIVersion pins which wire version of the sandbox daemon API the
	// client speaks. Empty defaults to the SDK's pinned default ("v1"
	// today). The Go SDK's package version and the wire version evolve
	// independently — bumping the SDK doesn't move the wire version.
	APIVersion string
	// Retry configures the policy for transient transport errors and retryable
	// HTTP status codes (429, 502, 503, 504).
	Retry *RetryConfig
}

type MountSpec ¶

type MountSpec = models.MountSpec

type MountSpecRedacted ¶

type MountSpecRedacted = models.MountSpecRedacted

type MountType ¶

type MountType = models.MountType

type NetworkUsage ¶ added in v0.1.7

type NetworkUsage = models.NetworkUsage

type PlatformVolumeMount ¶ added in v0.5.4

type PlatformVolumeMount = models.PlatformVolumeMount

type PushWasmModuleOptions ¶ added in v0.5.3

type PushWasmModuleOptions = models.PushWasmModuleOptions

PushWasmModuleOptions is the input for Client.PushWasmModule (BYO upload).

type PushWasmModuleResponse ¶ added in v0.5.3

type PushWasmModuleResponse = models.PushWasmModuleResponse

PushWasmModuleResponse is the result of Client.PushWasmModule.

type RegisterSnapshotOptions ¶ added in v0.1.7

type RegisterSnapshotOptions struct {
	// Name is the human-readable identifier other callers use to reference
	// this snapshot in CreateSandboxOptions.Snapshot. Required.
	Name string
	// Image is a pre-built registry image reference (e.g. "python:3.12").
	// Mutually exclusive with DockerfileContent.
	Image string
	// DockerfileContent is the literal Dockerfile the daemon will build.
	// Mutually exclusive with Image. Use Image.Dockerfile() to obtain this
	// from an Image-builder graph, or RegisterSnapshotFromImage to skip the
	// indirection entirely.
	DockerfileContent string
	// ContextHashes references blobs uploaded ahead of time so COPY/ADD
	// steps in DockerfileContent can resolve. Requires the daemon to have
	// SB_IMAGE_BUILD_CONTEXT_ENABLED set; the resolver itself is not
	// implemented yet, so non-empty values currently return 501.
	ContextHashes []string
	// Entrypoint overrides the image's entrypoint. Echoed back on the
	// snapshot row so future sandbox-create calls inherit it.
	Entrypoint []string
	// RegionID pins the snapshot to a specific region for multi-region
	// deployments. Persisted on the row but not yet used for routing.
	RegionID string
	// CPU, GPU, MemoryMB, DiskGB are resource hints surfaced to clients.
	CPU      float64
	GPU      float64
	MemoryMB int
	DiskGB   int
}

RegisterSnapshotOptions is the input shape for Client.RegisterSnapshot. Exactly one of Image (a pre-built registry reference) or DockerfileContent (build inputs the daemon will compile) must be set.

The remaining fields capture the resource hints the snapshot will report when listed or used in CreateSandboxOptions.Snapshot.

type ResizeSandboxOptions ¶

type ResizeSandboxOptions = models.ResizeSandboxRequest

type RetryConfig ¶ added in v0.4.1

type RetryConfig struct {
	// MaxRetries is the maximum number of retry attempts after the initial
	// request fails. Set to a negative number to disable retry entirely.
	// Defaults to 3.
	MaxRetries *int
	// BaseDelayMs is the initial backoff delay in milliseconds. Defaults to 200.
	BaseDelayMs *int
	// MaxDelayMs is the hard ceiling on the computed delay. Defaults to 5000.
	MaxDelayMs *int
}

RetryConfig specifies how the SDK should retry transient errors.

type Sandbox ¶

type Sandbox = models.Sandbox

type SandboxSnapshot ¶ added in v0.1.7

type SandboxSnapshot = models.SandboxSnapshot

type Session ¶

type Session = models.Session

type SessionStatus ¶

type SessionStatus = models.SessionStatus

type SetNetworkLimitsOptions ¶ added in v0.1.7

type SetNetworkLimitsOptions = models.UpdateNetworkLimitsRequest

type StreamCallback ¶

type StreamCallback func([]byte)

type StreamErrorCallback ¶

type StreamErrorCallback func(string)

type Template ¶ added in v0.4.1

type Template = models.Template

Template is the server's Firecracker rootfs template row. Re-exported verbatim from pkg/models so the SDK stays aligned with the wire format.

type TemplateStatus ¶ added in v0.4.1

type TemplateStatus = models.TemplateStatus

TemplateStatus is the lifecycle of a Firecracker rootfs template. See plans/snapshot-clone-fast-boot.md for the state machine.

type UpdateLifecycleOptions ¶

type UpdateLifecycleOptions = models.UpdateLifecycleRequest

type WasmModule ¶ added in v0.5.3

type WasmModule = models.WasmModule

WasmModule is one row in the wasm_modules catalogue.

type WasmModuleStatus ¶ added in v0.5.3

type WasmModuleStatus = models.WasmModuleStatus

WasmModuleStatus is the catalogue lifecycle for WASM modules.