Isolate AI code execution with Agent Sandbox

Autopilot Standard

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

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector
Verify that billing is enabled for your Google Cloud project.
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

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 REPOSITORY_NAME="python-sandbox-repo"
export PYTHON_SANDBOX_IMG="${GKE_LOCATION}-docker.pkg.dev/${PROJECT_ID}/${REPOSITORY_NAME}/sandbox-runtime:latest"
export AGENT_SANDBOX_VERSION="v0.1.0"

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.
REPOSITORY_NAME: the name of the Artifact Registry repository where the container images for a sample Python app will be stored—for example, python-sandbox-repo.
PYTHON_SANDBOX_IMG: a unique identifier for the Python sandbox container image that you will build and push.
AGENT_SANDBOX_VERSION: the version of the Agent Sandbox controller to be deployed to your cluster.

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. This cluster provides the Kubernetes environment where you will deploy and run the Agent Sandbox controller and the sample sandboxed app.

You can create either an Autopilot or a Standard cluster:

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, run the following command:

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

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 Deployment

After you apply the manifests, check that the Agent Sandbox controller Pod is running correctly.

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 can deploy a sample web server app that provides a secure sandbox environment for executing shell commands.

To do this, you first need to build the app's container image and store it in a private Artifact Registry repository that your cluster can access.

After the image is available, you use a two-step process to deploy it. First, you define a SandboxTemplate, which acts as a reusable blueprint for the sandbox environment. Then, you create a SandboxClaim, which is a request that instructs the Agent Sandbox controller to pull your container image and run it as a new Pod based on the template. Finally, you test the running app to confirm that it's working correctly.

Create an Artifact Registry repository

The following steps show you how to create a private Artifact Registry repository to store your container image and how to configure Docker to access it.

Create the Artifact Registry repository to store the container image for the Python sandbox app:

gcloud artifacts repositories create $REPOSITORY_NAME \
    --repository-format=docker \
    --location=$GKE_LOCATION

Authenticate your Docker client with Artifact Registry. This action lets you securely push images to your private repository and pull images from it by using your Google Cloud credentials:
```
gcloud auth configure-docker "${GKE_LOCATION}-docker.pkg.dev"
```

Build and push the sample Python app

Next, you need to download the sample code from the Agent Sandbox repository. This code builds a container image containing a basic Python web server.

This web server is designed to demonstrate the core functionality of the Agent Sandbox: it exposes an /execute endpoint that accepts shell commands as a JSON payload. When you send a command to this endpoint, the server executes it within the secure sandbox environment and returns the output.

The following steps show you how to clone the repository, build the container image, and push it to your private Artifact Registry repository:

Clone the agent-sandbox repository from GitHub. This repository contains the code for the Python app:
```
git clone https://github.com/kubernetes-sigs/agent-sandbox.git
```
Navigate to the directory that contains the Dockerfile and source code for the Python app:
```
cd agent-sandbox/examples/python-runtime-sandbox
```
Build the container image for the app by using Docker. The -t flag tags the image with the name defined in the PYTHON_SANDBOX_IMG environment variable at the beginning of this document:
```
docker build -t $PYTHON_SANDBOX_IMG .
```
Push the container image to your private Artifact Registry repository so that your GKE cluster can access it:
```
docker push $PYTHON_SANDBOX_IMG
```

Create a `SandboxTemplate`

You now define the configuration for your sandbox by creating a SandboxTemplate resource. This template acts as a reusable blueprint that the Agent Sandbox controller uses to create consistent, pre-configured sandbox environments. Creating a SandboxTemplate resource lets you define the sandbox once and create multiple instances of it later.

In Cloud Shell, create a file named sandbox-template.yaml with the following content. This manifest defines a SandboxTemplate resource that serves as a reusable blueprint for creating sandboxes. The SandboxTemplate and SandboxClaim must be in the same namespace:

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
  name: python-runtime-template
  namespace: default
spec:
  podTemplate:
    metadata:
      labels:
        # The selector in the wait command looks for this label.
        sandbox: python-sandbox-example
    spec:
      # Optional, must have gVisor enabled node
      # runtimeClassName: gvisor
      containers:
      - name: python-runtime
        image: IMAGE_PLACEHOLDER
        ports:
        - containerPort: 8888
        readinessProbe:
          httpGet:
            path: "/"
            port: 8888
          initialDelaySeconds: 0
          periodSeconds: 1
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
            ephemeral-storage: "512Mi"
      restartPolicy: "OnFailure"

Update the manifest with the image path to your Python app:

sed -i "s|IMAGE_PLACEHOLDER|${PYTHON_SANDBOX_IMG}|g" sandbox-template.yaml

Apply the SandboxTemplate manifest:
```
kubectl apply -f sandbox-template.yaml
```

Create a sandbox by making a `SandboxClaim`

Now that you have a reusable blueprint, you create a running sandbox by applying a SandboxClaim resource to your cluster. This claim references the SandboxTemplate and instructs the Agent Sandbox controller to create a Sandbox resource and its corresponding Pod based on the template's configuration:

Create a file named sandbox-claim.yaml with the following content. The SandboxClaim resource requests a new sandbox based on the python-runtime-template. Note that you can create multiple SandboxClaims; however each SandboxClaim name must be unique from other running SandboxClaims:
```
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxClaim
metadata:
  name: python-sandbox-example
  namespace: default
spec:
  sandboxTemplateRef:
    name: python-runtime-template
```
To trigger the creation of a Sandbox resource based on the template, apply the SandboxClaim manifest:
```
kubectl apply -f sandbox-claim.yaml
```

Verify that the Sandbox resource is ready:

kubectl wait --for=condition=Ready sandbox/python-sandbox-example --namespace default --timeout=120s

You should see output similar to the following:

sandbox.agents.x-k8s.io/python-sandbox-example condition met

Run the kubectl get sandbox command to view details about the sandbox:
```
kubectl get sandbox
```

Verify that the sandboxed Pod is ready to accept traffic before you proceed:

kubectl wait --for=condition=ready pod --selector=sandbox=python-sandbox-example --namespace default --timeout=120s

You should see output similar to the following:

pod/python-sandbox-example condition met

Test the sandbox

Now that your sample app is running inside its secure sandbox, you can test it to confirm it's working correctly. The following steps show you how to securely connect to the sandbox Pod from your Cloud Shell environment using the kubectl port-forward command. You then use the tester.py script, which is included in the repository you cloned, to send a test command to the app's /execute endpoint and verify that it returns a successful response.

Set up port-forwarding to the Pod. Port-forwarding lets you communicate from your local Cloud Shell environment to the web server app running inside the sandbox:
```
POD_NAME="python-sandbox-example"
kubectl port-forward "pod/${POD_NAME}" 8888:8888 &
PF_PID=$!
trap "kill $PF_PID" EXIT
sleep 3
```
Install the requests library required by the test script:
```
pip3 install requests
```

Run the tester.py script, which is in the agent-sandbox/examples/python-runtime-sandbox directory, to verify the sandbox endpoints:

python3 tester.py 127.0.0.1 8888

The tester.py script performs two key tests: a health check to ensure the app is responsive, and a command execution test that sends the echo 'hello world' shell command to the sandbox.

The output is similar to the following:

    $ python3 tester.py 127.0.0.1 8888
--- Testing Health Check endpoint ---
Sending GET request to http://127.0.0.1:8888/
Handling connection for 8888
Health check successful!
Response JSON: {'status': 'ok', 'message': 'Sandbox Runtime is active.'}

--- Testing Execute endpoint ---
Sending POST request to http://127.0.0.1:8888/execute with payload: {'command': "echo 'hello world'"}
Handling connection for 8888
Execute command successful!
Response JSON: {'stdout': 'hello world\n', 'stderr': '', 'exit_code': 0}

Congratulations! You have successfully deployed a secure, sandboxed environment on your GKE cluster. You can now send any shell command to the /execute endpoint of this app, and Agent Sandbox runs it within a secure barrier that protects your cluster's nodes and other workloads from the untrusted code. Agent Sandbox helps provide a safe and reliable way for an AI agent or any automated workflow to execute tasks.

Delete the sandbox

When you are finished testing, you should dispose of the sandbox to release its compute resources:

Delete the SandboxClaim resource you created:
```
kubectl delete -f sandbox-claim.yaml
```
This action instructs the controller to terminate the running Pod and delete the Sandbox resource.
Verify that the resources are removed by running the following command:
```
kubectl get sandbox,pod -n default
```
After a moment, you should see a No resources found message which confirms that the sandbox environment has been successfully cleaned up.

Clean up resources

To avoid incurring charges to your Google Cloud account, you should delete the resources that you created throughout this document. The following steps show you how to delete the GKE cluster, the Artifact Registry repository and the container image it contains.

Delete the GKE cluster:

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

Delete the container image that you pushed to Artifact Registry:

gcloud artifacts docker images delete $PYTHON_SANDBOX_IMG --delete-tags --quiet

Delete the Artifact Registry repository:

gcloud artifacts repositories delete $REPOSITORY_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.