Isolate AI code execution with Agent Sandbox

This document provides instructions for installing and running the Agent Sandbox controller on a Google Kubernetes Engine (GKE) cluster. It also explains how to deploy a sandboxed environment on the cluster in which you can test untrusted shell commands.

The Agent Sandbox controller provides a framework for creating and managing ephemeral runtime environments. This approach lets you define a template for your app's environment and then create instances of it on demand.

Agent Sandbox provides a secure and isolated environment for executing untrusted code, such as code generated by large language models (LLMs). Running this type of code directly in a cluster poses security risks, because untrusted code could potentially access or interfere with other apps or the underlying cluster node itself.

Agent Sandbox mitigates these risks by providing strong process, storage, and network isolation for the code it runs. This isolation is achieved using gVisor, a technology that creates a secure barrier between the application and the cluster node's operating system. Other sandboxing technologies, for example Kata containers, can be used instead; however, the example in this document uses gVisor only.

This document provides instructions for running Agent Sandbox on either a GKE Autopilot cluster or Standard cluster.

Agent Sandbox is an open-source project. For more information about how to contribute to the project or find more in-depth technical details, see the Agent Sandbox open source project.

Costs

Following the steps in this document incurs charges on your Google Cloud account. Costs begin when you create a GKE cluster. These costs include per-cluster charges for GKE, as outlined on the Pricing page, and charges for running Compute Engine VMs.

To avoid unnecessary charges, ensure that you disable GKE or delete the project after you have completed this document.

Before you begin

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Artifact Registry, Google Kubernetes Engine APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  4. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

Define environment variables

To simplify the commands that you run in this document, you can set environment variables in Cloud Shell. In Cloud Shell, define the following useful environment variables by running the following commands:

export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export GKE_LOCATION="us-central1"
export AGENT_SANDBOX_VERSION="v0.1.0"
export NODE_POOL_NAME="agent-sandbox-node-pool"
export MACHINE_TYPE="e2-standard-2"
export PYTHON_CLIENT_VERSION="main"

Here's an explanation of these environment variables:

  • PROJECT_ID: the ID of your current Google Cloud project. Defining this variable helps ensure that all resources, like your GKE cluster, are created in the correct project.
  • CLUSTER_NAME: the name of your GKE cluster—for example, agent-sandbox-cluster.
  • GKE_LOCATION: the Google Cloud region where your GKE cluster and Artifact Registry repository will be created—for example, us-central1. We recommend colocating them because this reduces image pull latency.
  • AGENT_SANDBOX_VERSION: the version of the Agent Sandbox controller to be deployed to your cluster.
  • NODE_POOL_NAME: the name of the node pool that will run sandboxed workloads—for example, agent-sandbox-node-pool.
  • MACHINE_TYPE: the machine type of the nodes in your node pool—for example, e2-standard-2. For details about different machine series and choosing between different options, see the Machine families resource and comparison guide.
  • PYTHON_CLIENT_VERSION: the version of the Agentic Sandbox Python client to install.

Deploy Agent Sandbox

Now that you have your Google Cloud project and Cloud Shell environment set up, you are ready to provision the necessary infrastructure and deploy Agent Sandbox.

Create a GKE cluster

Next, you create a GKE cluster that has gVisor enabled. This cluster provides the Kubernetes environment where you will deploy and run the Agent Sandbox controller and the sample sandboxed app. gVisor provides the sandboxing technology to securely run untrusted code.

You can create either an Autopilot or a Standard cluster. Autopilot enables gVisor automatically, while Standard clusters require you to create a gVisor-enabled node pool manually:

Autopilot

To create an Autopilot cluster using the gcloud CLI, run the following command:

gcloud container clusters create-auto ${CLUSTER_NAME} \
    --location=${GKE_LOCATION} \
    --project=${PROJECT_ID}

Standard

To create Standard cluster using the gcloud CLI, perform these steps:

  1. Create the cluster:

    gcloud container clusters create ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}

  2. Create a separate node pool with gVisor enabled:

    gcloud container node-pools create ${NODE_POOL_NAME} \
  --cluster=${CLUSTER_NAME} \
  --location=${GKE_LOCATION} \
  --machine-type=${MACHINE_TYPE} \
  --image-type=cos_containerd \
  --sandbox type=gvisor

Retrieve the cluster's credentials so that the kubectl CLI can connect to the cluster. This command updates your Kubernetes config file, which is stored by default in the ~/.kube/config directory. This config file contains the credentials that kubectl requires to interact with your GKE cluster:

gcloud container clusters get-credentials ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}

Deploy the Agent Sandbox controller to your cluster

You can deploy the Agent Sandbox controller and its required components by applying the official release manifests to your cluster. These manifests are configuration files that instruct Kubernetes to download all the necessary components that are required to deploy and run the Agent Sandbox controller on your cluster.

Run the following commands to deploy the Agent Sandbox controller to your GKE cluster:

kubectl apply \
-f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/manifest.yaml \
-f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/extensions.yaml

Verify the Agent Sandbox controller

After you apply the manifests, check that the Agent Sandbox controller Pod is running correctly in the agent-sandbox-system namespace:

kubectl get pods -n agent-sandbox-system

Wait for the Pod to show 'Running' in the STATUS column and '1/1' in the READY column. When the Pod is running correctly, the output looks similar to this:

NAME                         READY   STATUS    RESTARTS   AGE
agent-sandbox-controller-0   1/1     Running   0          44d

Now that the Agent Sandbox controller is running, it can automatically create and manage sandboxed environments for any Sandbox resources that you create in your cluster.

Deploy a sandboxed environment

Now that you have the Agent Sandbox controller running in your GKE cluster, you need to deploy the components for the sample sandbox environment. This section shows you how to create the sandbox blueprint (SandboxTemplate), deploy the necessary networking router, and install the Python client you will use to interact with the sandbox.

The recommended way to create and interact with your sandbox is by using the Agentic Sandbox Python client. This client provides an interface that simplifies the entire lifecycle of a sandbox, from creation to cleanup. It's a Python library you can use to programmatically create, use, and delete sandboxes.

The client uses a Sandbox Router as a central entry point for all traffic. In the example described in this document, the client creates a tunnel to this router using the command kubectl port-forward, so that you don't need to expose any public IP addresses. Be aware that making use of kubectl port-forward isn't a secure solution and its use should be limited to development environments.

Create a SandboxTemplate and SandboxWarmPool

You now define the configuration for your sandbox by creating a SandboxTemplate and a SandboxWarmPool resource. The SandboxTemplate acts as a reusable blueprint that the Agent Sandbox controller uses to create consistent, pre-configured sandbox environments. The SandboxWarmPool resource ensures that a specified number of pre-warmed Pods are always running and ready to be claimed. A pre-warmed sandbox is a running Pod that's already initialized. This pre-initialization enables new sandboxes to be created in under a second, and avoids the startup latency of launching a regular sandbox:

  1. In Cloud Shell, create a file named sandbox-template-and-pool.yaml with the following content:

    apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
  name: python-runtime-template
  namespace: default
spec:
  podTemplate:
    metadata:
      labels:
        sandbox: python-sandbox-example
    spec:
      runtimeClassName: gvisor
      containers:
      - name: python-runtime
        image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
        ports:
        - containerPort: 8888
        readinessProbe:
          httpGet:
            path: "/"
            port: 8888
          initialDelaySeconds: 0
          periodSeconds: 1
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
            ephemeral-storage: "512Mi"
      restartPolicy: "OnFailure"
---
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxWarmPool
metadata:
  name: python-sandbox-warmpool
  namespace: default
spec:
  replicas: 2
  sandboxTemplateRef:
    name: python-runtime-template

  2. Apply the SandboxTemplate and SandboxWarmPool manifest:

    kubectl apply -f sandbox-template-and-pool.yaml

Deploy the Sandbox Router

The Python client that you will use to create and interact with sandboxed environments uses a component called the Sandbox Router to communicate with the sandboxes.

For this example, you use the client's developer mode for testing. This mode is intended for local development, and uses the command kubectl port-forward to establish a direct tunnel from your local machine to the Sandbox Router service running in the cluster. This tunneling approach avoids the need for a public IP address or complex ingress setup, and simplifies interacting with sandboxes from your local environment.

Follow these steps to deploy the Sandbox Router:

  1. In Cloud Shell, create a file named sandbox-router.yaml with the following content:

    # A ClusterIP Service to provide a stable endpoint for the router pods.
apiVersion: v1
kind: Service
metadata:
  name: sandbox-router-svc
  namespace: default
spec:
  type: ClusterIP
  selector:
    app: sandbox-router
  ports:
  - name: http
    protocol: TCP
    port: 8080 # The port the service will listen on
    targetPort: 8080 # The port the router container listens on (from the sandbox_router/Dockerfile)
---
# The Deployment to manage and run the router pods.
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sandbox-router-deployment
  namespace: default
spec:
  replicas: 2 # Run at least two replicas for high availability
  selector:
    matchLabels:
      app: sandbox-router
  template:
    metadata:
      labels:
        app: sandbox-router
    spec:
      # Ensure pods are spread across different zones for HA
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: topology.kubernetes.io/zone
          whenUnsatisfiable: ScheduleAnyway
          labelSelector:
            matchLabels:
              app: sandbox-router
      containers:
      - name: router
        image: us-central1-docker.pkg.dev/k8s-staging-images/agent-sandbox/sandbox-router:v20251124-v0.1.0-10-ge26ddb2
        ports:
        - containerPort: 8080
        readinessProbe:
          httpGet:
            path: /healthz
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
        livenessProbe:
          httpGet:
            path: /healthz
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 10
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
          limits:
            cpu: "1000m"
            memory: "1Gi"
      securityContext:
        runAsUser: 1000
        runAsGroup: 1000

  2. Apply the manifest to deploy the router to your cluster:

    kubectl apply -f sandbox-router.yaml

Install the Python client

Now that the in-cluster components like the Sandbox Router are deployed, the final preparatory step is to install the Agentic Sandbox Python client on your local machine. Recall that this client is a Python library that lets you programmatically create, use, and delete sandboxes. You use it in the next section to test the environment:

  1. Create and activate a Python virtual environment:

    python3 -m venv .venv
source .venv/bin/activate

  2. Install the client package from the agent-sandbox repository:

    pip install "git+https://github.com/kubernetes-sigs/agent-sandbox.git@${PYTHON_CLIENT_VERSION}#subdirectory=clients/python/agentic-sandbox-client"

Test the sandbox

With all the setup components in place, you can now create and interact with a sandbox using the Agentic Sandbox Python client.

  1. In your agent-sandbox directory, create a Python script named test_sandbox.py with the following content:

    from agentic_sandbox import SandboxClient

# Automatically tunnels to svc/sandbox-router-svc
with SandboxClient(
    template_name="python-runtime-template",
    namespace="default"
) as sandbox:
    print(sandbox.run("echo 'Hello from the sandboxed environment!'").stdout
)

  2. From your terminal (with the virtual environment still active), run the test script:

    python3 test_sandbox.py

You should see the message "Hello from the sandboxed environment!" which is output from the sandbox.

Congratulations! You have successfully run a shell command inside a secure sandbox. Using the sandbox.run() method, you can execute any shell command, and the Agent Sandbox runs the command within a secure barrier that protects your cluster's nodes and other workloads from untrusted code. This provides a safe and reliable way for an AI agent or any automated workflow to execute tasks.

When you run the script, the SandboxClient handles all the steps for you. It creates the SandboxClaim resource to start the sandbox, waits for the sandbox to be ready, and then uses the sandbox.run() method to execute bash shell commands inside the secure container. The client then captures and prints the stdout from that command. The sandbox is automatically deleted after the program runs.

Clean up resources

To avoid incurring charges to your Google Cloud account, you should delete the GKE cluster that you created:

gcloud container clusters delete $CLUSTER_NAME --location=$GKE_LOCATION --quiet

What's next

  • Learn more about the Agent Sandbox open-source project on GitHub.
  • To understand the underlying technology that provides security isolation for your workloads, see GKE Sandbox.
  • For more information about enhancing security for your clusters and workloads, see GKE security overview.