microvm

package
v0.6.13 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source
const FeatureFilesWatch = apiclient.FeatureFilesWatch

FeatureFilesWatch is the feature an *UnsupportedFeatureError names when a sandbox's agent predates file watching.

View Source
const HeaderTeam = apiclient.HeaderTeam

HeaderTeam is the header the client sends its team in (MicroVMConfig.Team or SB_TEAM) on every request.

Variables

View Source
var (
	ErrNotFound              = apiclient.ErrNotFound
	ErrConflict              = apiclient.ErrConflict
	ErrCapacity              = apiclient.ErrCapacity
	ErrTimeout               = apiclient.ErrTimeout
	ErrAuth                  = apiclient.ErrAuth
	ErrNameLookupUnsupported = apiclient.ErrNameLookupUnsupported
	ErrUnsupportedFeature    = apiclient.ErrUnsupportedFeature
	// ErrFileTooLarge means a download was larger than its MaxBytes.
	ErrFileTooLarge = apiclient.ErrFileTooLarge
)

Sentinels for errors.Is. ErrNotFound matches a 404 (and a GetByName miss), ErrConflict a 409, ErrCapacity a 503, ErrTimeout a 408 or 504, ErrAuth a 401 or 403, ErrNameLookupUnsupported a server that ignored `?name=`, and ErrUnsupportedFeature an *UnsupportedFeatureError. The status sentinels match an *APIError, which errors.As still reads for the details.

Functions

This section is empty.

Types

type APIError added in v0.6.5

type APIError = apiclient.APIError

APIError is an HTTP error response from sandboxd: status, the server's optional stable error code, and its message (Error() returns the message unchanged). Use errors.As to read it.

type Client

type Client struct {
	// contains filtered or unexported fields
}

func NewClient

func NewClient() (*Client, error)

func NewClientWithConfig

func NewClientWithConfig(config *sdktypes.MicroVMConfig) (*Client, error)

func (*Client) AttachSession

func (c *Client) AttachSession(ctx context.Context, sandboxID, sessionID string, options SessionAttachOptions) (*SessionAttachHandle, error)

func (*Client) BuildImage added in v0.1.7

func (c *Client) BuildImage(ctx context.Context, image *Image) (string, error)

BuildImage compiles an Image builder into a content-addressed image tag via POST /v1/images/build. Older daemons that do not register the route return a tailored error telling the caller to fall back to a plain string image.

func (*Client) BuildImageWithOptions added in v0.1.7

func (c *Client) BuildImageWithOptions(ctx context.Context, image *Image, opts sdktypes.BuildImageOptions) (sdktypes.BuildImageResult, error)

BuildImageWithOptions builds an Image and optionally pushes the result to a remote registry. Push credentials are forwarded to the daemon as a one-shot X-Registry-Auth header and never persisted server-side. Returns the local content-addressed tag and (when push was requested) the pushed reference.

func (*Client) CheckNetworkPolicy added in v0.6.6

CheckNetworkPolicy asks whether a sandbox created with these egress fields would reach a destination, with the same matcher the filter enforces. No sandbox is needed.

func (*Client) CloneGeneration added in v0.5.2

func (c *Client) CloneGeneration(ctx context.Context, id string) (sdktypes.CloneGeneration, error)

CloneGeneration reads a sandbox's clone-generation token. The token changes whenever the sandbox is resumed from a snapshot, so a change signals "this is a clone." Read-only — the SDK cannot reseed a process inside the guest; see the "Randomness in cloned sandboxes" docs for the in-guest pattern.

func (*Client) Create

func (c *Client) Create(ctx context.Context, opts sdktypes.CreateSandboxOptions) (*Sandbox, error)

Create creates a sandbox. It sends a random Idempotency-Key, made once for this call and sent unchanged on each of its automatic retries, so a create retried after a timeout gets back the sandbox the first attempt made instead of making a second one. Use CreateWithIdempotencyKey to choose the key.

func (*Client) CreateSession

func (c *Client) CreateSession(ctx context.Context, sandboxID string, opts sdktypes.CreateSessionOptions) (sdktypes.Session, error)

func (*Client) CreateSnapshot added in v0.1.7

func (c *Client) CreateSnapshot(ctx context.Context, id, name string, opts ...SnapshotOption) (sdktypes.SandboxSnapshot, error)

CreateSnapshot saves the sandbox id's files as a snapshot named name.

func (*Client) CreateTemplate added in v0.4.1

func (c *Client) CreateTemplate(ctx context.Context, opts sdktypes.CreateTemplateOptions) (sdktypes.Template, error)

CreateTemplate registers a Firecracker rootfs template. Returns immediately with a status="pending" row; poll Client.GetTemplate until the row reaches "ready" (fast-boot available) or "ready_no_snapshot" (cold boot only).

Idempotent when opts.ID is set: a duplicate ID returns 409 so a retried CI step does not register two rows for the same logical template.

func (*Client) CreateWasmModule added in v0.5.3

func (c *Client) CreateWasmModule(ctx context.Context, opts sdktypes.CreateWasmModuleOptions) (sdktypes.WasmModule, error)

CreateWasmModule registers a WASM module in the host catalogue. Resolution is synchronous — the returned row is typically already ready.

func (*Client) CreateWithIdempotencyKey added in v0.6.10

func (c *Client) CreateWithIdempotencyKey(ctx context.Context, opts sdktypes.CreateSandboxOptions, key string) (*Sandbox, error)

CreateWithIdempotencyKey is Create with key as the Idempotency-Key. A create sent again with the same key and the same options returns the sandbox the first one made instead of making a second, so your own retries of the whole call are safe too, such as after your process restarts. The same key with different options fails with an *APIError whose Code is "idempotency_key_reused" (HTTP 422). Keys are scoped to the caller's account. A blank key gets a random one, as Create does.

func (*Client) CreateWithImage added in v0.1.7

func (c *Client) CreateWithImage(ctx context.Context, image *Image, opts sdktypes.CreateSandboxOptions) (*Sandbox, error)

CreateWithImage builds an Image to a content-addressed tag, then creates the sandbox using the resolved string image. This keeps CreateSandboxOptions source-compatible with the server's request model.

func (*Client) DNSTarget added in v0.3.1

func (c *Client) DNSTarget(ctx context.Context) (sdktypes.IngressTarget, error)

DNSTarget returns the cluster-published ingress target — the hostname and/or IP set that custom-domain DNS records must point at. Source disambiguates the shape ("hostname" / "ips" / "mixed" / "unknown"), so callers don't have to inspect which fields are populated to know whether to render a CNAME or A/AAAA setup hint.

func (*Client) DeleteEgressProfile added in v0.6.6

func (c *Client) DeleteEgressProfile(ctx context.Context, name string) error

DeleteEgressProfile deletes a profile; one that sandboxes still reference is refused (409).

func (*Client) DeleteIdentityRole added in v0.6.12

func (c *Client) DeleteIdentityRole(ctx context.Context, tag, team string) error

DeleteIdentityRole takes a role tag off a team's allow list (team "" is the operator namespace). Admin only. Sandboxes that use it keep their current token (at most one hour) and get no new one. Deleting a tag that is already gone succeeds.

func (*Client) DeleteSession

func (c *Client) DeleteSession(ctx context.Context, sandboxID, sessionID string) error

func (*Client) DeleteSnapshot added in v0.6.7

func (c *Client) DeleteSnapshot(ctx context.Context, name string) error

DeleteSnapshot removes a named snapshot. Returns ErrNotFound (404) when no snapshot by that name exists.

func (*Client) DeleteTeamQuota added in v0.6.12

func (c *Client) DeleteTeamQuota(ctx context.Context, team string) error

DeleteTeamQuota removes a team's quota. Removing one that is already gone succeeds.

func (*Client) DeleteTemplate added in v0.4.1

func (c *Client) DeleteTemplate(ctx context.Context, id string) error

func (*Client) DeleteWarmPool added in v0.6.12

func (c *Client) DeleteWarmPool(ctx context.Context, image string) error

DeleteWarmPool deletes an image's warm-pool entry; its warm sandboxes are removed. Deleting a missing entry succeeds.

func (*Client) DeleteWasmModule added in v0.5.3

func (c *Client) DeleteWasmModule(ctx context.Context, id string) error

func (*Client) Destroy

func (c *Client) Destroy(ctx context.Context, id string) error

func (*Client) DestroyAll added in v0.6.12

func (c *Client) DestroyAll(ctx context.Context, tags map[string]string) ([]string, error)

DestroyAll deletes every sandbox of the caller's that carries all of tags and returns the IDs of the ones now gone. It lists every page first, then deletes them one at a time. A sandbox that is already gone (404) counts as deleted, so a second call, or two calls at once, is safe. Any other failed delete stops it: the error is returned with the IDs deleted so far, and calling it again finishes the job. tags must not be empty, since with no filter it would delete every sandbox the caller owns.

func (*Client) ExecStream

func (c *Client) ExecStream(ctx context.Context, id string, options sdktypes.ExecStreamOptions) (*ExecStreamHandle, error)

func (*Client) Get

func (c *Client) Get(ctx context.Context, id string, opts ...GetOption) (*Sandbox, error)

func (*Client) GetAudit added in v0.6.6

func (c *Client) GetAudit(ctx context.Context, id string, opts sdktypes.AuditOptions) (sdktypes.AuditPage, error)

GetAudit reads one page of a sandbox's audit log: outbound connections and egress denials (Kind "egress") and secret reads.

func (*Client) GetByName added in v0.6.5

func (c *Client) GetByName(ctx context.Context, name string, opts ...GetOption) (*Sandbox, error)

GetByName returns the caller's sandbox called name, with one request. Names are unique per owner. A missing name returns an error matching ErrNotFound. A server that predates name lookup ignores `?name=` and returns an unfiltered list; GetByName detects that and returns an error matching ErrNameLookupUnsupported instead of picking a row.

func (*Client) GetEgressProfile added in v0.6.6

func (c *Client) GetEgressProfile(ctx context.Context, name string) (sdktypes.EgressProfile, error)

GetEgressProfile reads one named egress profile.

func (*Client) GetNetworkLearned added in v0.6.6

func (c *Client) GetNetworkLearned(ctx context.Context, id string) (sdktypes.NetworkLearned, error)

GetNetworkLearned reads what a sandbox reached in learn mode and the allow list that would have allowed it.

func (*Client) GetNetworkUsage added in v0.1.7

func (c *Client) GetNetworkUsage(ctx context.Context, id string) (sdktypes.NetworkUsage, error)

GetNetworkUsage returns current cumulative ingress/egress byte counters and the configured per-direction caps for a sandbox. A `*Limit` of zero means unlimited.

func (*Client) GetOrCreate added in v0.6.12

func (c *Client) GetOrCreate(ctx context.Context, name string, opts sdktypes.CreateSandboxOptions) (*Sandbox, bool, error)

GetOrCreate returns the caller's sandbox called name, creating it from opts when there is none; created is true only when this call made it. It is safe to retry and to run concurrently:

GET ?name=name ── hit ──► (existing, false)
      │ miss
POST {opts, name}
      ├─ 201 ──────────────► (new, true)
      ├─ 409 ─► GET ?name= ─► (the winner, false)
      └─ lost reply ─► the client retries the same POST (same
         Idempotency-Key) ─► 201, or 409 as above

Names are unique per owner, so of two callers racing to create a name one gets a 409 and reads the other's sandbox. A 409 whose name still cannot be found is a conflict on something else and is returned as is. An existing sandbox is returned unchanged: its image and settings are not compared with opts. opts.Name may be empty or repeat name.

func (*Client) GetSession

func (c *Client) GetSession(ctx context.Context, sandboxID, sessionID string) (sdktypes.Session, error)

func (*Client) GetSnapshot added in v0.6.7

func (c *Client) GetSnapshot(ctx context.Context, name string) (sdktypes.SandboxSnapshot, error)

GetSnapshot reads one named snapshot's metadata. Returns ErrNotFound (404) when no snapshot by that name exists.

func (*Client) GetTeamQuota added in v0.6.12

func (c *Client) GetTeamQuota(ctx context.Context, team string) (sdktypes.TeamQuota, error)

GetTeamQuota reads a team's quota and what the team holds now (Usage). A team with no quota is a 404 *APIError.

func (*Client) GetTemplate added in v0.4.1

func (c *Client) GetTemplate(ctx context.Context, id string) (sdktypes.Template, error)

func (*Client) GetWarmPool added in v0.6.12

func (c *Client) GetWarmPool(ctx context.Context, image string) (sdktypes.WarmPool, error)

GetWarmPool reads an image's warm-pool entry with its status (ready and target, in total and per server).

func (*Client) GetWasmModule added in v0.5.3

func (c *Client) GetWasmModule(ctx context.Context, id string) (sdktypes.WasmModule, error)

func (*Client) Health

func (c *Client) Health(ctx context.Context) (sdktypes.HealthStatus, error)

func (*Client) List

func (c *Client) List(ctx context.Context, opts ...ListOption) ([]*Sandbox, error)

func (*Client) ListEgressProfiles added in v0.6.6

ListEgressProfiles reads one page of your egress profiles by name.

func (*Client) ListIdentityRoles added in v0.6.12

ListIdentityRoles reads one page of a team's cloud identity allow list. Admin only.

func (*Client) ListPage added in v0.6.1

func (c *Client) ListPage(ctx context.Context, pageToken string, opts ...ListOption) ([]*Sandbox, string, error)

ListPage fetches one bounded page and returns the server's opaque token for the next page. Callers inventorying large fleets should loop until the token is empty instead of materializing every sandbox in one slice.

func (*Client) ListSessions

func (c *Client) ListSessions(ctx context.Context, sandboxID string) ([]sdktypes.Session, error)

func (*Client) ListSnapshots added in v0.6.7

ListSnapshots reads one page of your snapshots ordered by name. Pass opts.Limit to cap the page and opts.StartingAfter (the last name of the previous page) to keep paging while the returned SnapshotList.HasMore is true.

func (*Client) ListTemplates added in v0.4.1

func (c *Client) ListTemplates(ctx context.Context) ([]sdktypes.Template, error)

func (*Client) ListWarmPools added in v0.6.12

func (c *Client) ListWarmPools(ctx context.Context) ([]sdktypes.WarmPool, error)

ListWarmPools reads every warm-pool entry, by image, with its status.

func (*Client) ListWasmModules added in v0.5.3

func (c *Client) ListWasmModules(ctx context.Context) ([]sdktypes.WasmModule, error)

func (*Client) Mounts

func (c *Client) Mounts(ctx context.Context, id string) ([]sdktypes.MountSpecRedacted, error)

Mounts returns the redacted mount config for a sandbox. Credentials are never included; this endpoint is for showing the user what their sandbox has configured, not for retrieving secrets.

func (*Client) PushWasmModule added in v0.5.3

PushWasmModule uploads a compiled core-wasip1 module to the registry under your own credentials and returns the oci:// ref to use as ModuleRef on a later Create. The daemon validates and forwards the bytes; it never stores them.

func (*Client) PutEgressProfile added in v0.6.6

func (c *Client) PutEgressProfile(ctx context.Context, name string, opts sdktypes.EgressProfileOptions) (sdktypes.EgressProfile, error)

PutEgressProfile creates or replaces a named egress profile (a full replace: the same body twice is a no-op). Sandboxes reference it through EgressProfiles, and a change reaches every one of them.

func (*Client) PutIdentityRole added in v0.6.12

func (c *Client) PutIdentityRole(ctx context.Context, tag string, opts sdktypes.IdentityRoleOptions) (sdktypes.IdentityRole, error)

PutIdentityRole puts a role tag on a team's cloud identity allow list, or changes its minimum caller role ("runner" or "admin"). Admin only. The same call twice changes nothing, so it is safe to retry. Sandboxes are created with a tag through CreateSandboxOptions.Identity.

func (*Client) PutTeamQuota added in v0.6.12

func (c *Client) PutTeamQuota(ctx context.Context, team string, opts sdktypes.TeamQuotaOptions) (sdktypes.TeamQuota, error)

PutTeamQuota sets a team's quota: the most sandboxes, CPU and memory its sandboxes may hold. Admin only. The same limits twice change nothing. A create, resize or start past the quota fails with an *APIError whose StatusCode is 429 and Code is "team_quota_exceeded".

func (*Client) PutWarmPool added in v0.6.12

func (c *Client) PutWarmPool(ctx context.Context, image string, opts sdktypes.WarmPoolOptions) (sdktypes.WarmPool, error)

PutWarmPool sets how many ready sandboxes every server with a warm pool keeps for an image (a full replace: the same call twice is a no-op). A create that names the image then starts from a warm sandbox. Admin only.

func (*Client) RebuildTemplate added in v0.4.1

func (c *Client) RebuildTemplate(ctx context.Context, id string) (sdktypes.Template, error)

RebuildTemplate re-runs the snapshot phase against an existing template. Idempotent under concurrent retry: the daemon's CAS collapses N parallel calls for the same ready template into one rebuild kick. Returns the row in its post-transition state (typically "unhealthy"); poll GetTemplate to observe the transition back to "ready".

Returns an HTTP error (status 412) when the template is in a state where rebuild is not safe (build in flight) or not supported (ready_no_snapshot, failed — those need delete+recreate today).

func (*Client) Reconcile added in v0.1.1

func (c *Client) Reconcile(ctx context.Context) error

func (*Client) RegisterSnapshot added in v0.1.7

RegisterSnapshot persists a named snapshot pointing at either a pre-built image (opts.Image) or a Dockerfile the daemon will build (opts.Dockerfile — typically obtained from Image.Dockerfile()). The returned snapshot's Image field reflects the resolved registry reference (for the build path this is the daemon's content-addressed tag).

Once registered, callers can reference the snapshot by name in CreateSandboxOptions.Snapshot — the server resolves it to the image at create time.

func (*Client) RegisterSnapshotFromImage added in v0.1.7

func (c *Client) RegisterSnapshotFromImage(ctx context.Context, name string, image *Image, opts sdktypes.RegisterSnapshotOptions) (sdktypes.SandboxSnapshot, error)

RegisterSnapshotFromImage compiles an Image-builder graph and registers the resulting Dockerfile as a named snapshot. Convenience wrapper around RegisterSnapshot that mirrors CreateWithImage's ergonomics — pass an *Image instead of remembering to call Image.Dockerfile() yourself.

func (*Client) Resize

func (c *Client) Resize(ctx context.Context, id string, opts sdktypes.ResizeSandboxOptions) (*Sandbox, error)

func (*Client) ResizeSession

func (c *Client) ResizeSession(ctx context.Context, sandboxID, sessionID string, cols, rows int) error

func (*Client) RevokeSandboxTokens added in v0.6.12

func (c *Client) RevokeSandboxTokens(ctx context.Context, id string) (sdktypes.RevokeSandboxTokensResult, error)

RevokeSandboxTokens makes every token issued for the sandbox id so far stop working (see Sandbox.RevokeTokens).

func (*Client) SessionLog

func (c *Client) SessionLog(ctx context.Context, sandboxID, sessionID string) ([]byte, error)

func (*Client) SessionRecording

func (c *Client) SessionRecording(ctx context.Context, sandboxID, sessionID string) ([]byte, error)

func (*Client) SetNetworkLimits added in v0.1.7

func (c *Client) SetNetworkLimits(ctx context.Context, id string, opts sdktypes.SetNetworkLimitsOptions) (sdktypes.NetworkUsage, error)

SetNetworkLimits raises or lifts the per-direction byte caps. Leave a field nil to keep the current value; pass a pointer to zero to set "unlimited". Raising a cap above current usage clears the per-IP iptables block on the next reconcile pass (or immediately if it's already over the new cap).

func (*Client) SetNetworkPolicy added in v0.6.6

func (c *Client) SetNetworkPolicy(ctx context.Context, id string, opts sdktypes.NetworkPolicyOptions) (sdktypes.NetworkPolicy, error)

SetNetworkPolicy replaces a sandbox's egress policy while it runs and returns once the new policy is enforced. Sending the same policy again is a no-op, so it is safe to retry.

func (*Client) SignalSession

func (c *Client) SignalSession(ctx context.Context, sandboxID, sessionID, signal string) error

func (*Client) Start

func (c *Client) Start(ctx context.Context, id string) (*Sandbox, error)

func (*Client) Stop

func (c *Client) Stop(ctx context.Context, id string) (*Sandbox, error)

func (*Client) Tokens added in v0.6.8

func (c *Client) Tokens() *Tokens

Tokens manages scoped API tokens (avm_…) for services and CI. Creating and revoking needs an admin credential; listing needs an auditor or an admin.

func (*Client) UpdateLifecycle

func (c *Client) UpdateLifecycle(ctx context.Context, id string, lifecycle sdktypes.Lifecycle) (*Sandbox, error)

UpdateLifecycle replaces the per-sandbox lifecycle timers. Pass zero in any field to clear that timer; pass non-zero to set or extend it. The server validates and rejects negative durations, durations over the configured cap, or stop/destroy pairs where destroy fires before stop.

func (*Client) WatchFiles added in v0.6.12

func (c *Client) WatchFiles(ctx context.Context, id, path string, options sdktypes.WatchOptions) (*WatchHandle, error)

WatchFiles streams changes under path in sandbox id: create, write, remove, rename and chmod events, plus overflow when events were lost. It returns once the watch is armed.

Only gVisor and Firecracker sandboxes can watch; any other runtime answers an *APIError with status 501. A sandbox whose agent predates file watching answers an *UnsupportedFeatureError (errors.Is(err, ErrUnsupportedFeature)). The request is not retried: a watch is a stream.

ctx bounds the whole watch, not only the call that arms it: cancelling it (or its deadline passing) ends the stream, as Stop on the handle does. To arm with a time limit and then watch for longer, pass a ctx without a deadline and stop the watch through the handle.

func (*Client) WhoAmI added in v0.6.8

func (c *Client) WhoAmI(ctx context.Context) (sdktypes.WhoAmI, error)

WhoAmI returns who the server says the caller is: its principal, role, team and when the credential expires. Every valid credential may call it.

type CustomDomainOption added in v0.4.1

type CustomDomainOption func(*customDomainOptions)

CustomDomainOption customizes an AddCustomDomain call. Build values with WithTargetPort; the variadic shape leaves room for future expansion.

func WithTargetPort added in v0.4.1

func WithTargetPort(port int) CustomDomainOption

WithTargetPort routes the custom hostname to the given in-container TCP port instead of the default toolbox agent. Set once at attach time; changing the port for an already-attached hostname requires RemoveCustomDomain + AddCustomDomain so in-flight traffic can't silently redirect. Re-adding the same hostname with a different port returns 409.

type ExecStreamHandle

type ExecStreamHandle struct {
	// contains filtered or unexported fields
}

func (*ExecStreamHandle) Close

func (h *ExecStreamHandle) Close() error

func (*ExecStreamHandle) Resize

func (h *ExecStreamHandle) Resize(cols, rows int) error

func (*ExecStreamHandle) Signal

func (h *ExecStreamHandle) Signal(name string) error

func (*ExecStreamHandle) Wait

func (*ExecStreamHandle) Write

func (h *ExecStreamHandle) Write(data []byte) error

func (*ExecStreamHandle) WriteString

func (h *ExecStreamHandle) WriteString(data string) error

type ExposeOption added in v0.1.6

type ExposeOption func(*exposeOptions)

ExposeOption customizes an ExposePort call. Build values with WithProtocol; the variadic shape leaves room for future expansion (e.g. tags, idle TTL) without breaking call sites.

func WithProtocol added in v0.1.6

func WithProtocol(p sdktypes.ExposeProtocol) ExposeOption

WithProtocol selects the wire surface the exposure publishes through. Defaults to ExposeProtocolHTTP when omitted.

func WithVisibility added in v0.6.12

func WithVisibility(v sdktypes.ExposeVisibility) ExposeOption

WithVisibility sets who can open the port's URL. ExposeVisibilityToken makes it need a sandbox token for this port (Sandbox.CreateToken with Port). Without it a new port is public and an exposed port keeps what it has; pass it to change it.

type GetOption added in v0.6.1

type GetOption func(*getOptions)

GetOption customizes a Get call.

func WithGetIncludeEnv added in v0.6.1

func WithGetIncludeEnv() GetOption

WithGetIncludeEnv requests env on Get (`?include_env=true`).

type Image added in v0.1.7

type Image struct {
	// contains filtered or unexported fields
}

Image is a fluent Dockerfile builder for the Go SDK. Build it locally, then pass it to Client.BuildImage or Client.CreateWithImage.

func BaseImage added in v0.1.7

func BaseImage(image string) *Image

BaseImage starts a Dockerfile with FROM <image>.

func FromDockerfile added in v0.1.7

func FromDockerfile(dockerfile string) *Image

FromDockerfile wraps an existing Dockerfile string and normalizes the final trailing newline so builds stay content-stable across callers.

func (*Image) Cmd added in v0.1.7

func (i *Image) Cmd(commands ...string) *Image

func (*Image) Dockerfile added in v0.1.7

func (i *Image) Dockerfile() string

func (*Image) Entrypoint added in v0.1.7

func (i *Image) Entrypoint(commands ...string) *Image

func (*Image) Env added in v0.1.7

func (i *Image) Env(envVars map[string]string) *Image

Env appends one ENV line containing all provided key/value pairs.

func (*Image) Err added in v0.1.7

func (i *Image) Err() error

func (*Image) Expose added in v0.1.7

func (i *Image) Expose(port int) *Image

func (*Image) RunCommands added in v0.1.7

func (i *Image) RunCommands(commands ...any) *Image

RunCommands appends one RUN per string argument. A []string argument is joined with && so the commands share one layer.

func (*Image) User added in v0.1.7

func (i *Image) User(username string) *Image

func (*Image) Workdir added in v0.1.7

func (i *Image) Workdir(dirPath string) *Image

type ListOption added in v0.2.1

type ListOption func(*listOptions)

ListOption customizes a List call. Build values with WithTags; the variadic shape leaves room for future filters (e.g. status, lifecycle) without breaking call sites.

func WithIncludeEnv added in v0.6.1

func WithIncludeEnv() ListOption

WithIncludeEnv requests sandbox env vars on List/Get (`?include_env=true`). Env is omitted by default; opt-in reads are audited server-side.

func WithLimit added in v0.6.5

func WithLimit(n int) ListOption

WithLimit asks for at most n sandboxes per page (`?limit=<n>`); with ListPage that bounds one call, and List still drains every page. The server clamps n to its maximum (500). Servers that predate single-node paging ignore it there and return every row, so a caller that needs a hard bound must also cap the slice it gets back.

func WithName added in v0.6.5

func WithName(name string) ListOption

WithName filters to the caller's sandbox with exactly this name (`?name=<name>`); the result has zero or one entries. Names are unique per owner. Servers that predate name lookup ignore the filter and return a normal list, so prefer GetByName, which checks the reply.

func WithTags added in v0.2.1

func WithTags(tags map[string]string) ListOption

WithTags filters the result to sandboxes whose Tags map contains every supplied key/value pair (AND semantics on the server). Wire format is `?tag.<key>=<value>`; the SDK percent-encodes keys and values for you. An empty or nil map is a no-op — the call is identical to List(ctx).

type Sandbox

type Sandbox struct {
	sdktypes.Sandbox
	// SSHPrivateKey is populated only on the response from Client.Create. It
	// is the per-sandbox ed25519 private key the gateway authorizes; persist
	// it locally before discarding the create response, the server cannot
	// regenerate it.
	SSHPrivateKey string
	// DestroyOnClose makes Close delete the sandbox. It is off by default,
	// so `defer sb.Close(ctx)` alone leaves the sandbox running; set it to
	// opt in to delete-on-exit (plan S2).
	DestroyOnClose bool
	// contains filtered or unexported fields
}

func (*Sandbox) AddCustomDomain added in v0.3.1

func (s *Sandbox) AddCustomDomain(ctx context.Context, hostname string, opts ...CustomDomainOption) ([]sdktypes.CustomDomain, error)

AddCustomDomain attaches a public hostname (e.g. "api.acme.com") to this sandbox. The server lowercases / trims and validates the hostname; the returned slice is the full per-hostname row list, so callers can read the canonical form and initial status without a follow-up GET.

412 Precondition Failed surfaces when the deployment is in IP mode or the custom-domain feature is disabled. 409 Conflict surfaces when the hostname is already attached to a different sandbox, the sandbox has any tcp/tls-protocol exposed port (the IRON RULE: SNI cannot route per host on a shared L4 listener), or the re-add target_port differs from the stored value. 400 Bad Request surfaces when target_port is outside [0, 65535].

func (*Sandbox) AttachSession

func (s *Sandbox) AttachSession(ctx context.Context, sessionID string, options SessionAttachOptions) (*SessionAttachHandle, error)

func (*Sandbox) Audit added in v0.6.6

Audit reads one page of this sandbox's audit log (see Client.GetAudit).

func (*Sandbox) CloneGeneration added in v0.5.2

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

CloneGeneration reads this sandbox's clone-generation token (changes on resume-from-snapshot). Read-only; does not reseed in-guest PRNGs.

func (*Sandbox) Close added in v0.6.12

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

Close deletes the sandbox when DestroyOnClose is true and does nothing otherwise, so `defer sb.Close(ctx)` is the Go form of a block that cleans up after itself. The delete ignores ctx's cancellation and deadline (it keeps ctx's values) and has its own two-minute bound. A sandbox that is already gone counts as deleted, and a second Close does nothing.

func (*Sandbox) CopyFile added in v0.6.12

func (s *Sandbox) CopyFile(ctx context.Context, source, destination string, opts sdktypes.CopyFileOptions) error

CopyFile copies a file, or a folder with Recursive.

func (*Sandbox) CreateSession

func (s *Sandbox) CreateSession(ctx context.Context, opts sdktypes.CreateSessionOptions) (sdktypes.Session, error)

func (*Sandbox) CreateSnapshot added in v0.1.7

func (s *Sandbox) CreateSnapshot(ctx context.Context, name string, opts ...SnapshotOption) (sdktypes.SandboxSnapshot, error)

CreateSnapshot saves this sandbox's files as a snapshot named name.

func (*Sandbox) CreateToken added in v0.6.12

CreateToken issues a signed token for this sandbox only, to hand to a browser or an end user. With opts.Port the token opens that port's public URL (a port exposed with token visibility); without it the token is for the toolbox: commands, files and sessions. Each call makes a new token, and the server keeps no copy, so Token is shown only in the result. A token stops working when it expires, when the sandbox is deleted, or when RevokeTokens is called.

func (*Sandbox) CustomDomainDNS added in v0.3.1

func (s *Sandbox) CustomDomainDNS(ctx context.Context) (sdktypes.CustomDomainDNSRecords, error)

CustomDomainDNS returns the ready-to-paste DNS records the user must add at their provider for every custom domain on this sandbox to reach the cluster, plus the raw ingress target the records were derived from. One row per (hostname × ingress address); branch on Target.Source to render a "CNAME vs A/AAAA" hint.

func (*Sandbox) DeleteFile added in v0.6.12

func (s *Sandbox) DeleteFile(ctx context.Context, path string, opts sdktypes.DeleteFileOptions) error

DeleteFile deletes a file, or a folder and its contents with Recursive.

func (*Sandbox) DeleteSession

func (s *Sandbox) DeleteSession(ctx context.Context, sessionID string) error

func (*Sandbox) Destroy

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

func (*Sandbox) DownloadFile

func (s *Sandbox) DownloadFile(ctx context.Context, targetPath string) ([]byte, error)

func (*Sandbox) DownloadFileStream added in v0.6.5

func (s *Sandbox) DownloadFileStream(ctx context.Context, targetPath string) (io.ReadCloser, error)

DownloadFileStream opens targetPath for reading without buffering it. The caller must Close the returned body; closing early ends the transfer, so reading only the head of a large file costs only the head.

func (*Sandbox) DownloadFileStreamWithOptions added in v0.6.12

func (s *Sandbox) DownloadFileStreamWithOptions(ctx context.Context, targetPath string, opts sdktypes.DownloadFileOptions) (io.ReadCloser, error)

DownloadFileStreamWithOptions is DownloadFileStream with a size limit: the read that passes opts.MaxBytes fails with ErrFileTooLarge.

func (*Sandbox) DownloadFileWithOptions added in v0.6.12

func (s *Sandbox) DownloadFileWithOptions(ctx context.Context, targetPath string, opts sdktypes.DownloadFileOptions) ([]byte, error)

DownloadFileWithOptions reads a whole file, refusing one larger than opts.MaxBytes with ErrFileTooLarge. It retries like DownloadFile.

func (*Sandbox) Exec

func (*Sandbox) ExecCommand

func (s *Sandbox) ExecCommand(ctx context.Context, command string) (sdktypes.ExecResult, error)

func (*Sandbox) ExecStream

func (s *Sandbox) ExecStream(ctx context.Context, options sdktypes.ExecStreamOptions) (*ExecStreamHandle, error)

func (*Sandbox) ExposePort

func (s *Sandbox) ExposePort(ctx context.Context, port int, opts ...ExposeOption) (sdktypes.ExposeResult, error)

ExposePort publishes a sandbox container port. Use WithProtocol to choose a non-HTTP surface:

  • WithProtocol(ExposeProtocolTCP): raw caddy-l4 listener on a parent-host port. Pair with native protocol clients (psql, redis-cli, mysql, mongosh). Result.Host and Result.HostPort are populated on this path.
  • WithProtocol(ExposeProtocolTLS): caddy-l4 TLS-SNI route on the shared listener. Requires --domain and SB_L4_TLS_LISTEN.

With no option (or WithProtocol(ExposeProtocolHTTP)) the result is the default Caddy HTTP reverse-proxy URL.

A sandbox created with AllowPublicTraffic omitted or false starts private, with no public URL; the first ExposePort makes it public, whichever of the two it was. Set AllowPublicTraffic to true to make it public from boot.

func (*Sandbox) FileExists added in v0.6.12

func (s *Sandbox) FileExists(ctx context.Context, path string) (bool, error)

FileExists reports whether path exists in the sandbox.

func (*Sandbox) FindInFiles added in v0.6.12

func (s *Sandbox) FindInFiles(ctx context.Context, path, text string) ([]sdktypes.FileMatch, error)

FindInFiles returns each line under path that contains text.

func (*Sandbox) GetFileInfo added in v0.6.12

func (s *Sandbox) GetFileInfo(ctx context.Context, path string) (sdktypes.FileInfo, error)

GetFileInfo describes one path. A symlink is followed.

func (*Sandbox) GetNetworkUsage added in v0.1.7

func (s *Sandbox) GetNetworkUsage(ctx context.Context) (sdktypes.NetworkUsage, error)

func (*Sandbox) GetSession

func (s *Sandbox) GetSession(ctx context.Context, sessionID string) (sdktypes.Session, error)

func (*Sandbox) Learned added in v0.6.6

func (s *Sandbox) Learned(ctx context.Context) (sdktypes.NetworkLearned, error)

Learned reads what this sandbox reached in learn mode (see Client.GetNetworkLearned). A recording stays readable after a switch to enforce, until the sandbox is destroyed.

func (*Sandbox) ListCustomDomains added in v0.3.1

func (s *Sandbox) ListCustomDomains(ctx context.Context) ([]sdktypes.CustomDomain, error)

ListCustomDomains returns the per-hostname rows currently attached to the sandbox. Use this to poll Status (pending_dns → issuing → ready/failed) after AddCustomDomain.

func (*Sandbox) ListFiles added in v0.6.12

func (s *Sandbox) ListFiles(ctx context.Context, path string, opts sdktypes.ListFilesOptions) (sdktypes.FileList, error)

ListFiles lists a folder. The zero options list one level, up to sdktypes.DefaultListLimit entries; FileList.Truncated says more exist.

func (*Sandbox) ListSessions

func (s *Sandbox) ListSessions(ctx context.Context) ([]sdktypes.Session, error)

func (*Sandbox) MakeDir added in v0.6.12

func (s *Sandbox) MakeDir(ctx context.Context, path string, opts sdktypes.MakeDirOptions) error

MakeDir makes a folder; with Parents, like mkdir -p.

func (*Sandbox) MoveFile added in v0.6.12

func (s *Sandbox) MoveFile(ctx context.Context, source, destination string, opts sdktypes.MoveFileOptions) error

MoveFile moves or renames a file or folder. Without Overwrite, an existing destination is a 409 conflict (errors.Is(err, ErrConflict)).

func (*Sandbox) Refresh

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

func (*Sandbox) RemoveCustomDomain added in v0.3.1

func (s *Sandbox) RemoveCustomDomain(ctx context.Context, hostname string) error

RemoveCustomDomain detaches a hostname previously attached via AddCustomDomain or CreateSandboxOptions.CustomDomains. Case-insensitive; the server normalizes before comparing.

func (*Sandbox) Resize

func (*Sandbox) ResizeSession

func (s *Sandbox) ResizeSession(ctx context.Context, sessionID string, cols, rows int) error

func (*Sandbox) RevokeTokens added in v0.6.12

RevokeTokens makes every token issued for this sandbox so far stop working, toolbox and port tokens alike. A token made after the call works. Safe to call again.

func (*Sandbox) SearchFiles added in v0.6.12

func (s *Sandbox) SearchFiles(ctx context.Context, path, pattern string) ([]string, error)

SearchFiles returns the paths under path whose name matches a glob such as "*.py".

func (*Sandbox) SessionLog

func (s *Sandbox) SessionLog(ctx context.Context, sessionID string) ([]byte, error)

func (*Sandbox) SessionRecording

func (s *Sandbox) SessionRecording(ctx context.Context, sessionID string) ([]byte, error)

func (*Sandbox) SetNetworkLimits added in v0.1.7

func (*Sandbox) SetNetworkPolicy added in v0.6.6

func (s *Sandbox) SetNetworkPolicy(ctx context.Context, opts sdktypes.NetworkPolicyOptions) (sdktypes.NetworkPolicy, error)

SetNetworkPolicy replaces this sandbox's egress policy (see Client.SetNetworkPolicy) and updates its policy fields.

func (*Sandbox) SignalSession

func (s *Sandbox) SignalSession(ctx context.Context, sessionID, signal string) error

func (*Sandbox) Start

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

func (*Sandbox) Stop

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

func (*Sandbox) ToolboxRequest added in v0.6.5

func (s *Sandbox) ToolboxRequest(ctx context.Context, method, path string, query url.Values, body []byte, contentType string) (*http.Response, error)

ToolboxRequest sends one raw request to this sandbox's toolbox (path such as "/files" or "/process/execute") and returns the response for the caller to read and close. Use it for toolbox endpoints without a typed method, or to bound how much of a response you read. A 4xx/5xx returns an *APIError. Reads (GET/HEAD) retry on transient statuses; requests with a body are sent once.

func (*Sandbox) UnexposePort

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

func (*Sandbox) UpdateLifecycle

func (s *Sandbox) UpdateLifecycle(ctx context.Context, lifecycle sdktypes.Lifecycle) error

func (*Sandbox) UploadDir added in v0.6.12

func (s *Sandbox) UploadDir(ctx context.Context, localDir, remoteDir string) error

UploadDir copies the local folder localDir into remoteDir in the sandbox, made if missing (a gzipped tar the sandbox unpacks safely: no entry can land outside remoteDir). Symlinks are sent as links and hard-linked files as separate files; devices, pipes and sockets are skipped. It is sent once and never retried. It needs an agent that lists files.extract.

func (*Sandbox) UploadFile

func (s *Sandbox) UploadFile(ctx context.Context, targetPath string, data []byte) error

func (*Sandbox) UploadFileStream added in v0.6.5

func (s *Sandbox) UploadFileStream(ctx context.Context, targetPath string, r io.Reader) error

UploadFileStream uploads r to targetPath without holding the file in memory; use it instead of UploadFile for large or unbounded inputs. The request is not retried (the reader is consumed as it is sent).

func (*Sandbox) UploadFileStreamWithOptions added in v0.6.12

func (s *Sandbox) UploadFileStreamWithOptions(ctx context.Context, targetPath string, r io.Reader, opts sdktypes.UploadFileOptions) error

UploadFileStreamWithOptions is UploadFileStream with write options. It is sent once and never retried.

func (*Sandbox) UploadFileWithOptions added in v0.6.12

func (s *Sandbox) UploadFileWithOptions(ctx context.Context, targetPath string, data []byte, opts sdktypes.UploadFileOptions) error

UploadFileWithOptions is UploadFile with write options: append, create-only, atomic replace and a file mode (see UploadFileOptions). A sandbox whose agent predates them fails with ErrUnsupportedFeature rather than ignoring them. Plain and atomic uploads retry like UploadFile; append and create-only retry only on 429 and 503.

func (*Sandbox) WatchFiles added in v0.6.12

func (s *Sandbox) WatchFiles(ctx context.Context, path string, options sdktypes.WatchOptions) (*WatchHandle, error)

WatchFiles streams changes under path in this sandbox. See Client.WatchFiles.

type SessionAttachHandle

type SessionAttachHandle struct {
	// contains filtered or unexported fields
}

SessionAttachHandle is the live-session counterpart of ExecStreamHandle. It outlives the underlying process — Close() detaches without killing.

func (*SessionAttachHandle) Close

func (h *SessionAttachHandle) Close() error

func (*SessionAttachHandle) Resize

func (h *SessionAttachHandle) Resize(cols, rows int) error

func (*SessionAttachHandle) Signal

func (h *SessionAttachHandle) Signal(name string) error

func (*SessionAttachHandle) Wait

func (h *SessionAttachHandle) Wait() (int, string, error)

func (*SessionAttachHandle) Write

func (h *SessionAttachHandle) Write(data []byte) error

func (*SessionAttachHandle) WriteString

func (h *SessionAttachHandle) WriteString(data string) error

type SessionAttachOptions

type SessionAttachOptions = apiclient.SessionAttachOptions

SessionAttachOptions mirrors apiclient.SessionAttachOptions; re-exported here so callers don't need to import the internal package.

type SnapshotOption added in v0.6.12

type SnapshotOption func(*snapshotOptions)

SnapshotOption configures CreateSnapshot.

func WithAllowPause added in v0.6.12

func WithAllowPause(allow bool) SnapshotOption

WithAllowPause says whether the snapshot may pause a running sandbox. Without it the answer is yes: a running sandbox is paused while it is copied (its disk writes wait; Docker pauses the container) and keeps running afterwards. WithAllowPause(false) has a sandbox that is not stopped refused with HTTP 409 instead, for a workload that must never stall. A stopped sandbox needs no pause.

type StreamError added in v0.6.6

type StreamError = apiclient.StreamError

StreamError is a failure the toolbox reported on an exec or session stream, such as a command that could not start, as opposed to the stream dropping. Use errors.As to tell the two apart.

type Tokens added in v0.6.8

type Tokens struct {
	// contains filtered or unexported fields
}

Tokens is the API token surface of a Client; get one from Client.Tokens.

func (*Tokens) Create added in v0.6.8

Create mints a token. The result's Token field is the secret, returned this once and never again, so store it before discarding the result. A 409 (errors.Is(err, ErrConflict)) means the name is taken, possibly by an earlier attempt whose reply was lost; that secret cannot be recovered, so revoke the token and create it again.

func (*Tokens) List added in v0.6.8

func (t *Tokens) List(ctx context.Context) (sdktypes.APITokenList, error)

List returns every token, expired ones included (Expired is true) until the server removes them 30 days after expiry. It never returns a secret.

func (*Tokens) Revoke added in v0.6.8

func (t *Tokens) Revoke(ctx context.Context, id string) error

Revoke deletes the token with this id (tok_…). Revoking a token that is already gone succeeds, so a retried revoke is safe.

type UnsupportedFeatureError added in v0.6.12

type UnsupportedFeatureError = apiclient.UnsupportedFeatureError

UnsupportedFeatureError is returned when the sandbox's agent (toolboxd) is older than an option the call needs; the SDK refuses rather than send an option the agent would silently ignore. Restart the sandbox, or re-create its Firecracker template, to get the current agent.

type WatchHandle added in v0.6.12

type WatchHandle struct {
	// contains filtered or unexported fields
}

WatchHandle is a running file watch.

func (*WatchHandle) Done added in v0.6.12

func (h *WatchHandle) Done() <-chan struct{}

Done is closed when the watch has ended.

func (*WatchHandle) Stop added in v0.6.12

func (h *WatchHandle) Stop() error

Stop ends the watch; Wait then returns nil.

func (*WatchHandle) Wait added in v0.6.12

func (h *WatchHandle) Wait() error

Wait blocks until the watch ends: nil after Stop, an error naming the reason when the agent ended it (the folder was removed or moved), or the error that dropped the connection.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL