Go SDK Reference

import "sigs.k8s.io/agent-sandbox/clients/go/sandbox"

const (

    // PodNameAnnotation is the deprecated annotation key on a Sandbox resource that identifies the name of the underlying pod.
    // Deprecated: New Sandboxes use their own name for the backing pod while non-empty legacy annotations may still be honored.
    PodNameAnnotation = "agents.x-k8s.io/pod-name"
)

var (
    AttrClaimName         = attribute.Key("sandbox.claim.name")
    AttrCommandExecutable = attribute.Key("sandbox.command.executable")
    AttrExitCode          = attribute.Key("sandbox.exit_code")
    AttrFilePath          = attribute.Key("sandbox.file.path")
    AttrFileSize          = attribute.Key("sandbox.file.size")
    AttrFileCount         = attribute.Key("sandbox.file.count")
    AttrFileExists        = attribute.Key("sandbox.file.exists")
    AttrGatewayName       = attribute.Key("sandbox.gateway.name")
    AttrGatewayNamespace  = attribute.Key("sandbox.gateway.namespace")
    AttrRequestID         = attribute.Key("sandbox.request_id")
)

var (
    ErrNotReady         = errors.New("sandbox is not ready")
    ErrTimeout          = errors.New("operation timed out")
    ErrClaimFailed      = errors.New("claim creation failed")
    ErrWarmPoolNotFound = errors.New("sandbox warm pool not found")
    ErrTemplateNotFound = errors.New("sandbox template not found")
    ErrPortForwardDied  = errors.New("port-forward connection lost")
    ErrNoSandboxService = errors.New("sandbox has no headless Service")
    ErrAlreadyOpen      = errors.New("sandbox is already open; call Close first")
    ErrOrphanedClaim    = errors.New("orphaned claim; call Close() to retry deletion")
    ErrRetriesExhausted = errors.New("retries exhausted")
    ErrSandboxDeleted   = errors.New("sandbox was deleted before becoming ready")
    ErrGatewayDeleted   = errors.New("gateway was deleted during address discovery")
    ErrResponseTooLarge = errors.New("response exceeded 16 MB limit")
    // ErrUnsupportedByRuntime is returned by operations the selected
    // runtime or connection cannot perform (e.g. Delete on the legacy
    // python-runtime, or Run with RuntimeSandboxd and APIURL).
    ErrUnsupportedByRuntime = errors.New("operation not supported by the sandbox runtime")
    // ErrProcessProtocol indicates an invalid or incomplete process event stream.
    ErrProcessProtocol = errors.New("invalid process event stream")
    // ErrConcurrentRecv indicates that another Recv is already in progress.
    ErrConcurrentRecv = errors.New("concurrent Recv on process handle")
)

func NewTracerProvider(ctx context.Context, serviceName string) (*sdktrace.TracerProvider, error)

type CallOption func(*callOptions)

func WithEnv(env map[string]string) CallOption

result, err := client.Run(ctx, "echo $GREETING", sandbox.WithEnv(map[string]string{"GREETING": "hi"}))

func WithMaxAttempts(n int) CallOption

result, err := client.Run(ctx, "cat /etc/hostname", sandbox.WithMaxAttempts(6))

func WithTimeout(d time.Duration) CallOption

func WithWorkingDir(dir string) CallOption

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

func NewClient(_ context.Context, opts Options) (*Client, error)

func (c *Client) CreateSandbox(ctx context.Context, warmPoolName, namespace string, opts ...CreateOption) (*Sandbox, error)

func (c *Client) DeleteAll(ctx context.Context)

func (c *Client) DeleteSandbox(ctx context.Context, claimName, namespace string) error

func (c *Client) EnableAutoCleanup() (stop func())

func (c *Client) GetSandbox(ctx context.Context, claimName, namespace string) (*Sandbox, error)

func (c *Client) ListActiveSandboxes() []Key

func (c *Client) ListAllSandboxes(ctx context.Context, namespace string, opts ...ListOption) ([]string, error)

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

func (c *Commands) Run(ctx context.Context, command string, opts ...CallOption) (*ExecutionResult, error)

result, err := client.Run(ctx, "cat /etc/hostname", sandbox.WithMaxAttempts(6))

func (c *Commands) Start(ctx context.Context, command string, opts ...CallOption) (handle *ProcessHandle, err error)

type ConnectionStrategy interface {
    Connect(ctx context.Context) (baseURL string, err error)
    Close() error
}

type Connectivity string

const (
    // ConnectivityPortForward reaches the sandbox over a SPDY port-forward
    // brokered by the apiserver. Works from anywhere a kubeconfig does,
    // including a laptop or CI runner. Default.
    //
    // With RuntimeSandboxd the forward targets the sandbox pod itself, which
    // does not work for Kata or gVisor pods: their workload does not listen in
    // the pod's host-side network namespace. Use an in-cluster mode for those.
    // RuntimeLegacyPython forwards to the sandbox-router instead and is
    // unaffected.
    ConnectivityPortForward Connectivity = "port-forward"
    // ConnectivityInClusterService dials the Sandbox's headless Service by
    // its in-cluster DNS name (Status.ServiceFQDN), taking the apiserver —
    // and, for RuntimeLegacyPython, the sandbox-router, off the data path.
    //
    // Prefer this over ConnectivityInClusterPodIP when sandboxes cross a trust
    // boundary. The Service's selector only ever matches its own Sandbox's
    // pod, so a pod IP that Kubernetes has since reassigned to another
    // tenant would be caught when the TTL expires. A deleted Sandbox takes
    // its Service with it: connections then fail rather than landing on a stranger.
    // (DNS caching still leaves a TTL-bounded window)
    //
    // Requires the Sandbox to have a Service — set spec.service: true on
    // the template. Open fails when Status.ServiceFQDN is empty rather than
    // falling back to the pod IP, so the safety property cannot be lost
    // silently.
    ConnectivityInClusterService Connectivity = "in-cluster-service"

    // ConnectivityInClusterPodIP dials Status.PodIP. It needs no Service, so
    // it works against any Sandbox without template changes.
    //
    // It carries the pod IP's reuse hazard: nothing detects that the sandbox
    // pod was rescheduled, so requests can continue to a stale address that
    // Kubernetes may have since reassigned to an unrelated pod. Use
    // ConnectivityInClusterService where that matters.
    ConnectivityInClusterPodIP Connectivity = "in-cluster-pod-ip"
)

type CreateOption func(*createOptions)

func WithAdoptExisting() CreateOption

func WithClaimEnv(env []extv1beta1.EnvVar) CreateOption

func WithClaimLabels(labels map[string]string) CreateOption

func WithClaimName(name string) CreateOption

func WithPodAnnotations(annotations map[string]string) CreateOption

func WithPodLabels(labels map[string]string) CreateOption

func WithSandboxReadyTimeout(d time.Duration) CreateOption

func WithShutdownAfter(d time.Duration) CreateOption

func WithVolumeClaimTemplates(templates []sandboxv1beta1.PersistentVolumeClaimTemplate) CreateOption

type DirectStrategy struct {
    URL string
}

func (s *DirectStrategy) Close() error

func (s *DirectStrategy) Connect(_ context.Context) (string, error)

type ExecutionResult struct {
    Stdout   string `json:"stdout"`
    Stderr   string `json:"stderr"`
    ExitCode int    `json:"exit_code"`
}

type FileEntry struct {
    Name    string
    Size    int64
    Type    FileType
    ModTime time.Time
    // Mode holds octal permission bits (e.g. "0644"). Only populated by
    // the sandboxd runtime; empty on legacy.
    Mode string
}

type FileType string

const (
    FileTypeFile      FileType = "file"
    FileTypeDirectory FileType = "directory"
)

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

func (f *Files) Delete(ctx context.Context, path string, recursive bool, opts ...CallOption) error

func (f *Files) Exists(ctx context.Context, path string, opts ...CallOption) (bool, error)

func (f *Files) List(ctx context.Context, path string, opts ...CallOption) ([]FileEntry, error)

func (f *Files) Read(ctx context.Context, path string, opts ...CallOption) ([]byte, error)

func (f *Files) ReadTo(ctx context.Context, path string, destination io.Writer, opts ...CallOption) (int64, error)

func (f *Files) Write(ctx context.Context, path string, content []byte, opts ...CallOption) error

func (f *Files) WriteReader(ctx context.Context, path string, content io.Reader, opts ...CallOption) error

type HTTPError struct {
    StatusCode int
    Body       string
    Operation  string
}

func (e *HTTPError) Error() string

type Handle interface {
    Open(ctx context.Context) error
    Close(ctx context.Context) error
    Disconnect(ctx context.Context) error
    IsReady() bool

    Run(ctx context.Context, command string, opts ...CallOption) (*ExecutionResult, error)
    Write(ctx context.Context, path string, content []byte, opts ...CallOption) error
    Read(ctx context.Context, path string, opts ...CallOption) ([]byte, error)
    List(ctx context.Context, path string, opts ...CallOption) ([]FileEntry, error)
    Exists(ctx context.Context, path string, opts ...CallOption) (bool, error)
}

type Health struct {
    Status string `json:"status"`
    // UptimeSeconds is how long sandboxd has been running.
    UptimeSeconds int64 `json:"uptime_seconds"`
}

type Info interface {
    ClaimName() string
    SandboxName() string
    PodName() string
    PodIP() string
    Annotations() map[string]string
}

type K8sHelper struct {
    AgentsClient     agentsv1beta1.AgentsV1beta1Interface
    ExtensionsClient extensionsv1beta1.ExtensionsV1beta1Interface
    DynamicClient    dynamic.Interface
    CoreClient       corev1client.CoreV1Interface
    DiscoveryClient  discoveryv1client.DiscoveryV1Interface
    RestConfig       *rest.Config

    Log logr.Logger
}

func NewK8sHelper(restConfig *rest.Config, log logr.Logger) (*K8sHelper, error)

func (h *K8sHelper) WaitForSandboxReady(ctx context.Context, sandboxName, namespace string) error

type Key struct {
    Namespace string
    ClaimName string
}

type ListOption func(*listOptions)

func WithLabelSelector(selector string) ListOption

type Metadata struct {
    // Env holds the environment variables sandboxd exposes: only names
    // matching its --metadata-env-prefix, minus anything that looks like a
    // credential. It is never nil.
    Env map[string]string `json:"env"`
}

type Options struct {
    // WarmPoolName is the name of the SandboxWarmPool to use.
    // Required in Options before calling Open() to provision a new sandbox.
    // Optional on Client-level Options; pass the pool name per-sandbox to
    // CreateSandbox instead.
    // Must be a valid Kubernetes DNS subdomain (lowercase, [a-z0-9.-]).
    WarmPoolName string

    // ClaimName is an optional deterministic name for the SandboxClaim.
    // When empty, Kubernetes generates a unique name with prefix "sandbox-claim-".
    // When set and a SandboxClaim with this name already exists in Namespace,
    // Open fails with ErrClaimFailed unless AdoptExisting is also set.
    // A named claim is caller-owned: a failed Open and
    // Client.EnableAutoCleanup leave it in place; Close still deletes it.
    // Must be a valid Kubernetes DNS subdomain (lowercase, [a-z0-9.-]).
    // NewClient rejects it; use WithClaimName with Client.CreateSandbox.
    ClaimName string

    // AdoptExisting makes Open attach to an existing SandboxClaim named
    // ClaimName when creating it returns HTTP 409 Conflict, instead of
    // failing. The existing claim must reference the same WarmPoolName and
    // must not be terminating, and Open fails if it is replaced or starts
    // terminating before its sandbox name resolves. Creation options are not
    // reapplied to an adopted claim.
    // Requires ClaimName. NewClient rejects it; use WithAdoptExisting with
    // Client.CreateSandbox.
    AdoptExisting bool

    // Runtime selects the in-sandbox runtime API. Default: RuntimeLegacyPython.
    // RuntimeSandboxd talks to the sandbox pod rather than the sandbox-router,
    // so GatewayName is not supported with it. APIURL remains available as an
    // advanced/testing escape hatch for the REST endpoint only: Run needs the
    // gRPC endpoint and returns ErrUnsupportedByRuntime with it.
    Runtime Runtime

    // Connectivity selects the transport. Default: ConnectivityPortForward.
    //
    // The in-cluster values conflict with both GatewayName and APIURL, and
    // require that this process runs inside the same cluster as the sandbox
    // pods.
    Connectivity Connectivity

    // SandboxdRESTPort is the pod port of sandboxd's Filesystem & Runtime
    // REST API. Only used with RuntimeSandboxd. Default: 8080.
    SandboxdRESTPort int

    // SandboxdGRPCPort is the pod port of sandboxd's gRPC ProcessService.
    // Only used with RuntimeSandboxd. Default: 9090.
    SandboxdGRPCPort int

    // Namespace where the SandboxClaim will be created. Default: "default".
    // Must be a valid Kubernetes DNS label (lowercase, [a-z0-9-]).
    Namespace string

    // GatewayName enables Gateway mode. The client watches this Gateway resource
    // for an external IP, then routes through the sandbox-router.
    // Must be a valid Kubernetes DNS subdomain (lowercase, [a-z0-9.-]).
    GatewayName string

    // GatewayNamespace is where the Gateway lives. Default: "default".
    // Must be a valid Kubernetes DNS label (lowercase, [a-z0-9-]).
    GatewayNamespace string

    // GatewayScheme is the URL scheme used when constructing the base URL
    // from the Gateway's address. Default: "http".
    GatewayScheme string

    // APIURL enables Direct URL mode. The client connects directly to this URL,
    // bypassing gateway discovery. Takes precedence over GatewayName.
    APIURL string

    // ServerPort is the port the sandbox runtime listens on. Default: 8888.
    ServerPort int

    // Env is the list of environment variables to inject into the SandboxClaim.
    // Setting Env forces a cold start from the warm pool template.
    Env []extv1beta1.EnvVar

    // Labels are added to every SandboxClaim this client creates, so they can
    // be selected later (see WithLabelSelector). The SDK's own created-by label
    // always wins over a colliding key.
    Labels map[string]string

    // ShutdownAfter expires every SandboxClaim this client creates that long
    // after creation, so a crashed client cannot leak sandboxes. The claim
    // gets spec.lifecycle.shutdownTime and the Delete shutdown policy; the
    // deadline is rounded up to a whole second. Zero (the default) means no expiry.
    ShutdownAfter time.Duration

    // PodLabels are propagated to the backing Sandbox Pod via
    // spec.additionalPodMetadata.labels (unlike Labels, which are placed on the
    // SandboxClaim object itself). Label keys must carry a domain prefix from
    // the controller's label-domain allowlist (default: sandbox.users.io).
    PodLabels map[string]string

    // PodAnnotations are propagated to the backing Sandbox Pod via
    // spec.additionalPodMetadata.annotations.
    PodAnnotations map[string]string

    // VolumeClaimTemplates is a list of persistent volume claim templates to
    // create for the sandbox via spec.volumeClaimTemplates. Setting
    // VolumeClaimTemplates forces a cold start because warm pool pods do not
    // have these volumes.
    VolumeClaimTemplates []sandboxv1beta1.PersistentVolumeClaimTemplate

    // SandboxReadyTimeout is how long to wait for the sandbox to become ready. Default: 180s.
    SandboxReadyTimeout time.Duration

    // GatewayReadyTimeout is how long to wait for the gateway IP. Default: 180s.
    GatewayReadyTimeout time.Duration

    // PortForwardReadyTimeout is how long to wait for port-forward to be established. Default: 30s.
    PortForwardReadyTimeout time.Duration

    // CleanupTimeout is how long to wait for claim deletion during both Open
    // rollback and Close. Uses a detached context so cleanup succeeds even if
    // the caller's context is already cancelled. Default: 30s.
    CleanupTimeout time.Duration

    // RequestTimeout is the total timeout for a single SDK method call
    // (e.g., Run, Read, Write), encompassing all retry attempts and backoff
    // sleeps. Applied only when the caller's context has no deadline.
    // Default: 180s.
    RequestTimeout time.Duration

    // PerAttemptTimeout bounds the time to receive response headers per
    // HTTP attempt. Stopped on success so body reads use RequestTimeout.
    // Default: 60s.
    PerAttemptTimeout time.Duration

    // MaxDownloadSize is the maximum response body size for Read() and ReadTo().
    // Run() uses a fixed 16 MB decode limit; List() and Exists() use a
    // fixed 8 MB internal limit. Default: 256 MB.
    MaxDownloadSize int64

    // MaxUploadSize is the maximum content size for Write() and WriteReader().
    // Write rejects oversized content before network I/O; WriteReader enforces
    // the limit while streaming. Default: 256 MB.
    MaxUploadSize int64

    // Logger for structured logging. Defaults to stderr at INFO level.
    // Provide a custom logr.Logger for full control, or set Quiet to
    // suppress output.
    Logger logr.Logger

    // Quiet suppresses the default stderr logger. Has no effect when a
    // custom Logger is provided (non-zero-value).
    Quiet bool

    // K8sHelper provides pre-constructed Kubernetes clients. If nil, a new
    // K8sHelper is created from RestConfig. Use this to share clients
    // across multiple Sandbox instances.
    K8sHelper *K8sHelper

    // RestConfig overrides the Kubernetes REST config. If nil, the client first
    // tries in-cluster config (for pods), then falls back to the default
    // kubeconfig (~/.kube/config or KUBECONFIG env). Ignored when K8sHelper is set.
    RestConfig *rest.Config

    // HTTPTransport overrides the HTTP transport for sandbox operations.
    // If nil, a default transport with sensible timeouts is created.
    // Use this for custom TLS, proxies, or other transport-level settings.
    HTTPTransport http.RoundTripper

    // TraceServiceName is the OpenTelemetry service name used for the tracer's
    // instrumentation scope and the resource's service.name attribute.
    // Default: "sandbox-client".
    TraceServiceName string

    // TracerProvider sets the OpenTelemetry TracerProvider for span creation.
    // If nil, falls back to otel.GetTracerProvider (noop by default).
    TracerProvider trace.TracerProvider

    // DisablePodIPRouting suppresses the X-Sandbox-Pod-IP header even when a
    // pod IP is available. Use in environments with strict network policies,
    // service meshes, or secure overlays where direct pod-to-pod IP routing is
    // restricted but service-based DNS routing works correctly.
    // Note: this only affects router-based transports that send X-Sandbox-* headers.
    // Default: false (header is sent when router headers are enabled and a pod IP is present).
    DisablePodIPRouting bool
}

type ProcessEvent struct {
    Type ProcessEventType
    // Data is populated only for stdout/stderr and remains valid after Recv.
    Data []byte
    // ExitCode is populated only for exit events. A nonzero code is not an error.
    ExitCode int
}

type ProcessEventType string

const (
    ProcessEventStdout ProcessEventType = "stdout"
    ProcessEventStderr ProcessEventType = "stderr"
    ProcessEventExit   ProcessEventType = "exit"
)

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

func (h *ProcessHandle) Close() error

func (h *ProcessHandle) ProcessID() int32

func (h *ProcessHandle) Recv() (*ProcessEvent, error)

func (h *ProcessHandle) SendSignal(ctx context.Context, signal ProcessSignal) error

type ProcessSignal string

const (
    SignalSIGINT  ProcessSignal = "SIGINT"
    SignalSIGTERM ProcessSignal = "SIGTERM"
    SignalSIGKILL ProcessSignal = "SIGKILL"
)

type Runtime string

const (
    // RuntimeLegacyPython is the python-runtime HTTP API (POST /upload,
    // GET /download|list|exists/{path}, POST /execute on port 8888),
    // reached through the sandbox-router unless Connectivity selects a
    // direct pod dial. Default.
    RuntimeLegacyPython Runtime = "legacy-python"
    // RuntimeSandboxd is the sandboxd hybrid API defined by KEP-539.2:
    // REST filesystem (/v1/files/...) on port 8080 plus gRPC
    // ProcessService on port 9090. The SDK reaches the sandbox pod directly
    // or over a port-forward (default), see Connectivity.
    RuntimeSandboxd Runtime = "sandboxd"
)

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

func New(_ context.Context, opts Options) (*Sandbox, error)

func (s *Sandbox) Annotations() map[string]string

func (s *Sandbox) ClaimName() string

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

func (s *Sandbox) Commands() *Commands

func (s *Sandbox) Delete(ctx context.Context, path string, recursive bool, opts ...CallOption) error

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

func (s *Sandbox) Exists(ctx context.Context, path string, opts ...CallOption) (bool, error)

func (s *Sandbox) Files() *Files

func (s *Sandbox) Health(ctx context.Context, opts ...CallOption) (*Health, error)

func (s *Sandbox) IsReady() bool

func (s *Sandbox) List(ctx context.Context, path string, opts ...CallOption) ([]FileEntry, error)

func (s *Sandbox) Metadata(ctx context.Context, opts ...CallOption) (*Metadata, error)

func (s *Sandbox) Open(ctx context.Context) (retErr error)

func (s *Sandbox) PodIP() string

func (s *Sandbox) PodName() string

func (s *Sandbox) Read(ctx context.Context, path string, opts ...CallOption) ([]byte, error)

func (s *Sandbox) ReadTo(ctx context.Context, path string, destination io.Writer, opts ...CallOption) (int64, error)

func (s *Sandbox) Run(ctx context.Context, command string, opts ...CallOption) (*ExecutionResult, error)

func (s *Sandbox) SandboxName() string

func (s *Sandbox) ServiceFQDN() string

func (s *Sandbox) Write(ctx context.Context, path string, content []byte, opts ...CallOption) error

func (s *Sandbox) WriteReader(ctx context.Context, path string, content io.Reader, opts ...CallOption) error