Agent Sandbox

Python SDK Quickstart

Agent Sandbox is a quick and easy way to start secure containers that will let agents run, execute code, call tools and interact with data. Using the SDK users can easily interact with the sandboxes without using Kubernetes primitives.

Prerequisites

• A running Kubernetes cluster with the Agent Sandbox Controller installed.

• The Sandbox Router deployed in your cluster.

• A SandboxWarmPool named python-sandbox-pool applied to your cluster, backed by a template using the python-runtime-sandbox image. From the repository root:

  export SANDBOX_NAMESPACE=default SANDBOX_TEMPLATE_NAME=python-sandbox-template SANDBOX_WARMPOOL_NAME=python-sandbox-pool
  envsubst < clients/python/agentic-sandbox-client/python-sandbox-template.yaml | kubectl apply -f -
  envsubst < clients/python/agentic-sandbox-client/python-sandbox-warmpool.yaml | sed 's/replicas: 0/replicas: 1/' | kubectl apply -f -
  

• The Python SDK installed: pip install k8s-agent-sandbox.

Connection Modes

SandboxClient() with no arguments defaults to Tunnel mode (SandboxLocalTunnelConnectionConfig), which opens a kubectl port-forward tunnel to the Router Service — no public IP required, works on KinD and Minikube.

The SDK supports four modes:

Usage

Start with a simple run command:

from k8s_agent_sandbox import SandboxClient

client = SandboxClient()

sandbox = client.create_sandbox(
    warmpool="python-sandbox-pool",
    namespace="default",
)
try:
    result = sandbox.commands.run("echo 'Hello from Agent Sandbox!'")
    print(result.stdout)
    # Hello from Agent Sandbox!
finally:
    sandbox.terminate()

Or write a file into the sandbox filesystem, then read it:

sandbox = client.create_sandbox(
    warmpool="python-sandbox-pool",
    namespace="default",
)
try:
    sandbox.files.write(
        "hello.py",
        'print("Hello, World! Greetings from inside the sandbox.")\n',
    )
    result = sandbox.commands.run("python3 hello.py")
    print(result.stdout)
    # Hello, World! Greetings from inside the sandbox.
finally:
    sandbox.terminate()

References

• Python SDK documentation — full API reference and connection modes.
• Using Agent Sandbox as a Tool in ADK — integrate sandboxes into an AI agent.