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")
    ErrPortForwardDied  = errors.New("port-forward connection lost")
    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 cannot perform (e.g. Delete on the legacy python-runtime).
    ErrUnsupportedByRuntime = errors.New("operation not supported by the sandbox runtime")
)

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

type CallOption func(*callOptions)

func WithMaxAttempts(n int) CallOption

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

func WithTimeout(d time.Duration) 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) (*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) ([]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))

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

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

type Key struct {
    Namespace string
    ClaimName string
}

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

    // Runtime selects the in-sandbox runtime API. Default: RuntimeLegacyPython.
    // RuntimeSandboxd connects via a pod port-forward, so GatewayName is not
    // supported with it. APIURL remains available as an advanced/testing
    // escape hatch for the REST endpoint.
    Runtime Runtime

    // 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

    // 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().
    // 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 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. 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 connects over a pod port-forward
    // to the sandbox pod.
    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) IsReady() bool

func (s *Sandbox) List(ctx context.Context, path string, opts ...CallOption) ([]FileEntry, 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) Run(ctx context.Context, command string, opts ...CallOption) (*ExecutionResult, error)

func (s *Sandbox) SandboxName() 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