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 SandboxTemplate named python-sandbox-template applied to your cluster. See the Python Runtime Sandbox guide for setup instructions.
• 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 three modes:

Usage

Start with a simple run command:

from k8s_agent_sandbox import SandboxClient

client = SandboxClient()

sandbox = client.create_sandbox(
    template="python-sandbox-template",
    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(
    template="python-sandbox-template",
    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.