microvm

package
v0.2.1 Latest Latest
Warning

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

 Go to latest Published: May 19, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

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

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

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) (sdktypes.SandboxSnapshot, error)

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

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

func (*Client) Destroy 

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

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) (*Sandbox, error)

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

func (c *Client) GetSession(ctx context.Context, sandboxID, sessionID string) (sdktypes.Session, 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) ListSessions 

func (c *Client) ListSessions(ctx context.Context, sandboxID string) ([]sdktypes.Session, 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) Reconcile added in v0.1.1 

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

func (*Client) RegisterSnapshot added in v0.1.7 

func (c *Client) RegisterSnapshot(ctx context.Context, opts sdktypes.RegisterSnapshotOptions) (sdktypes.SandboxSnapshot, error)

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

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 (h *ExecStreamHandle) Wait() (sdktypes.ExecExitInfo, error)

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.

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 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
	// contains filtered or unexported fields
}

func (*Sandbox) AttachSession 

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

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) (sdktypes.SandboxSnapshot, error)

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

func (s *Sandbox) Exec(ctx context.Context, request sdktypes.ExecRequest) (sdktypes.ExecResult, error)

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.

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

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

func (*Sandbox) Refresh 

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

func (*Sandbox) Resize 

func (s *Sandbox) Resize(ctx context.Context, opts sdktypes.ResizeSandboxOptions) error

func (*Sandbox) ResizeSession 

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

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 (s *Sandbox) SetNetworkLimits(ctx context.Context, opts sdktypes.SetNetworkLimitsOptions) (sdktypes.NetworkUsage, error)

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

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

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.