Agent Sandbox

Python SDK Reference

This module provides the SandboxClient for interacting with the Agentic Sandbox. It handles lifecycle management (claiming, waiting) and interaction (execution, file I/O) via the Sandbox resource handle.

SandboxClient Objects

class SandboxClient(Generic[T])

A registry-based client for managing Sandbox lifecycles. Tracks all active handles to ensure flat code structure and safe cleanup.

sandbox_class

type: ignore

__init__

def __init__(connection_config: SandboxConnectionConfig | None = None,
             tracer_config: SandboxTracerConfig | None = None,
             cleanup: bool = False)

Initializes the SandboxClient.

Arguments:

• connection_config - Configuration for connecting to the sandboxes. Defaults to SandboxLocalTunnelConnectionConfig() which uses kubectl port-forwarding. Can also be SandboxDirectConnectionConfig or SandboxGatewayConnectionConfig.
• tracer_config - Configuration for OpenTelemetry tracing. Defaults to an empty SandboxTracerConfig (tracing disabled).
• cleanup - If True, registers an atexit hook to automatically delete all tracked sandboxes when the program terminates. Defaults to False.

create_sandbox

def create_sandbox(warmpool: str,
                   namespace: str = "default",
                   sandbox_ready_timeout: int = 180,
                   labels: dict[str, str] | None = None,
                   *,
                   shutdown_after_seconds: int | None = None,
                   volume_claim_templates: list[dict] | None = None,
                   pod_labels: dict[str, str] | None = None,
                   pod_annotations: dict[str, str] | None = None,
                   env: dict[str, str] | None = None) -> T

Provisions new Sandbox claim and returns a Sandbox handle which tracks the underlying infrastructure.

Arguments:

• warmpool - Name of the SandboxWarmPool to use.
• namespace - Kubernetes namespace for the claim.
• sandbox_ready_timeout - Seconds to wait for the sandbox to be ready.
• labels - Optional Kubernetes labels to attach to the claim object (SandboxClaim.metadata.labels).
• shutdown_after_seconds - Optional TTL in seconds. When set, the claim’s spec.lifecycle is populated with a shutdownTime of now + shutdown_after_seconds (UTC) and a shutdownPolicy of "Delete", so the controller auto-deletes the claim on expiry. Must be a positive integer.
• volume_claim_templates - Optional list of volume claim templates to override/merge with the sandbox template.
• pod_labels - Optional labels stamped onto the running Sandbox Pod via spec.additionalPodMetadata.labels. Unlike labels (which land on the claim object), these are readable from inside the sandbox through the Downward API.
• pod_annotations - Optional annotations stamped onto the running Sandbox Pod via spec.additionalPodMetadata.annotations.
• env - Optional environment variables to inject into the SandboxClaim. Setting this populates spec.env and forces a cold start from the warm pool template instead of adopting a pre-warmed pod, which may increase startup latency.

Example:

client = SandboxClient() sandbox = client.create_sandbox(warmpool=“python-sandbox-pool”) sandbox.commands.run(“echo ‘Hello World’”)

get_sandbox

def get_sandbox(claim_name: str,
                namespace: str = "default",
                resolve_timeout: int = 30) -> T

Retrieves an existing sandbox handle given a sandbox claim name. If the handle is closed or missing, it re-attaches to the infrastructure.

Arguments:

• claim_name - Name of the SandboxClaim to attach to.
• namespace - Kubernetes namespace the claim lives in.
• resolve_timeout - Seconds to wait while resolving the sandbox name from the claim status.

Example:

client = SandboxClient() sandbox = client.get_sandbox( … “sandbox-claim-1234abcd”, … ) sandbox.commands.run(“ls -la”)

list_active_sandboxes

def list_active_sandboxes() -> List[Tuple[str, str]]

Returns a list of tuples containing (namespace, claim_name) currently managed by this client.

Example:

client = SandboxClient() client.create_sandbox(“python-sandbox-pool”) print(client.list_active_sandboxes()) [(‘default’, ‘sandbox-claim-1234abcd’)]

list_all_sandboxes

def list_all_sandboxes(namespace: str = "default",
                       label_selector: str | None = None) -> List[str]

Lists all SandboxClaim names currently existing in the Kubernetes cluster for the given namespace.

Arguments:

• namespace - Kubernetes namespace to list claims in.
• label_selector - Optional Kubernetes label selector string (e.g. "app=myapp"). When set, only claims matching the selector are returned.

Example:

client = SandboxClient() print(client.list_all_sandboxes(namespace=“default”)) [‘sandbox-claim-1234abcd’, ‘sandbox-claim-5678efgh’]

delete_sandbox

def delete_sandbox(claim_name: str, namespace: str = "default")

Stops the client side connection and deletes the Kubernetes resources.

Example:

client = SandboxClient() sandbox = client.create_sandbox(“python-sandbox-pool”) client.delete_sandbox(sandbox.claim_name)

delete_all

def delete_all()

Cleanup all tracked sandboxes managed by this client.

Example:

client = SandboxClient() client.create_sandbox(“python-sandbox-pool”) client.create_sandbox(“python-sandbox-pool”) client.delete_all()

get_sandbox_claim_warmpool_name

def get_sandbox_claim_warmpool_name(claim_name: str, namespace: str) -> str

Get warmpool name of a sandbox claim.

k8s_agent_sandbox.models

ExecutionResult Objects

class ExecutionResult(BaseModel)

A structured object for holding the result of a command execution.

stdout

Standard output from the command.

stderr

Standard error from the command.

exit_code

Exit code of the command.

FileEntry Objects

class FileEntry(BaseModel)

Represents a file or directory entry in the sandbox.

Runtime-neutral: the SDK decodes both the legacy python-runtime wire format (mod_time as a float POSIX timestamp) and the sandboxd wire format (modified_at as an RFC 3339 string, plus mode) into this one shape. modified is always a timezone-aware datetime.

name

Name of the file.

size

Size of the file in bytes.

type

Type of the entry (file or directory).

modified

Last modification time (timezone-aware).

mode

Octal permission bits (sandboxd only), e.g. “0644”.

from_legacy

@classmethod
def from_legacy(cls, entry: dict) -> "FileEntry"

Build from the legacy python-runtime listing entry.

from_sandboxd

@classmethod
def from_sandboxd(cls, entry: dict) -> "FileEntry"

Build from a sandboxd DirectoryListing entry.

SandboxClaimEnvVar Objects

class SandboxClaimEnvVar(BaseModel)

Represents an environment variable entry in a SandboxClaim spec.

name

Name of the environment variable.

value

Value of the environment variable.

SandboxDirectConnectionConfig Objects

class SandboxDirectConnectionConfig(BaseModel)

Configuration for connecting directly to a Sandbox URL.

api_url

Direct URL to the router.

server_port

Port the sandbox container listens on.

SandboxGatewayConnectionConfig Objects

class SandboxGatewayConnectionConfig(BaseModel)

Configuration for connecting via Kubernetes Gateway API.

gateway_name

Name of the Gateway resource.

gateway_namespace

Namespace where the Gateway resource resides.

gateway_ready_timeout

Timeout in seconds to wait for Gateway IP.

server_port

Port the sandbox container listens on.

SandboxLocalTunnelConnectionConfig Objects

class SandboxLocalTunnelConnectionConfig(BaseModel)

Configuration for connecting via kubectl port-forward.

port_forward_ready_timeout

Timeout in seconds to wait for port-forward to be ready.

server_port

Port the sandbox container listens on.

router_namespace

Namespace where the Router service resides.

SandboxdPodTunnelConnectionConfig Objects

class SandboxdPodTunnelConnectionConfig(BaseModel)

Configuration for the sandboxd runtime via a direct pod port-forward.

sandboxd (KEP-539.2) exposes two listeners: the Filesystem & Runtime REST API and the gRPC ProcessService. This config port-forwards directly to the sandbox pod, reaching both.

rest_port

sandboxd REST filesystem port on the pod.

grpc_port

sandboxd gRPC ProcessService port on the pod.

port_forward_ready_timeout

Seconds to wait for port-forward readiness.

SandboxInClusterConnectionConfig Objects

class SandboxInClusterConnectionConfig(BaseModel)

Configuration for direct in-cluster connection to the sandbox pod, bypassing the router.

The client first uses the pod IP reported in the Sandbox status. If the pod IP is unavailable, it falls back to the stable Kubernetes DNS endpoint: http://{sandbox_id}.{namespace}.svc.cluster.local:{server_port}

server_port

Port the sandbox container listens on.

SandboxTracerConfig Objects

class SandboxTracerConfig(BaseModel)

Configuration for tracer level information

enable_tracing

Whether to enable OpenTelemetry tracing.

trace_service_name

Service name used for traces.