This repository contains a demonstration of managing isolated environments (sandboxes) on Google Kubernetes Engine (GKE) using the GKE Agent Sandbox feature.

It consists of a Main Application (orchestrator with UI) and a Demo Application designed to run inside the isolated sandboxes.

• main-app/: The control plane application (FastAPI) and UI.
• demo-app/: The lightweight application (FastAPI) that runs inside the sandboxes.
• infra/: Kubernetes manifests for SandboxTemplate, SandboxWarmPool, Gateway, HTTPRoute, and HealthCheckPolicy.
• build_infra.sh: Script to provision the GKE cluster and apply manifests.
• deploy.sh: Script to build and push Docker images to Artifact Registry.

• Python 3.13 (used for local development and testing)
• Docker (for building images)
• Google Cloud SDK (gcloud) authenticated to your Google Cloud project.
• kubectl and envsubst installed locally.

The application supports a Mock Mode that allows you to test the UI and API logic without a real GKE cluster.

Create a virtual environment and install dependencies:

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

# Install requirements for both apps
pip install --index-url https://pypi.org/simple -r main-app/requirements.txt
pip install --index-url https://pypi.org/simple -r demo-app/requirements.txt

1. Create a .env file in the root directory (based on .env.example):

   MODE=MOCK
   GATEWAY_NAME=external-http-gateway
   CLUSTER_NAME=YOUR_CLUSTER_NAME
   REGION=YOUR_REGION
   PROJECT_NAME=YOUR_PROJECT_ID
   # For Workload Identity (recommended for GKE deployment):
   GOOGLE_GENAI_USE_VERTEXAI=TRUE
   # For API key fallback (required for local/mock mode):
   # GEMINI_API_KEY=YOUR_GEMINI_API_KEY
   # GOOGLE_GENAI_USE_VERTEXAI=FALSE

2. Run the application:

   uvicorn main-app.main:app --reload

3. Open http://127.0.0.1:8000 in your browser to view the UI. You can create, message, and delete mock sandboxes.

You can also run the Demo App directly to verify its endpoints:

# Set required env vars
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI="FALSE"

# Run the app on the standard sandbox port
uvicorn demo-app.main:app --host 127.0.0.1 --port 8888 --reload

Test with curl:

curl -X POST http://127.0.0.1:8888/message -H "Content-Type: application/json" -d '{"message": "Hello"}'
curl http://127.0.0.1:8888/quote

To deploy to a real cluster, we build images first and then provision the infrastructure.

Ensure your .env file has the correct values:

• MODE=REAL
• PROJECT_NAME: Your real GCP Project ID.
• CLUSTER_NAME: Your STANDARD GKE cluster name.
• REGION: The region where you want to deploy (e.g., us-west1).
• GOOGLE_GENAI_USE_VERTEXAI: Set to TRUE (recommended) or FALSE.

This example supports two authentication modes for calling Gemini from sandbox pods:

Option 1: Workload Identity Federation (recommended)

Set GOOGLE_GENAI_USE_VERTEXAI=TRUE in your .env file. The build_infra.sh script will:

• Create a dedicated Kubernetes Service Account (sandbox-ai-sa)
• Grant it roles/aiplatform.user via a direct IAM principal binding
• Configure the sandbox template to use this KSA

Sandbox pods authenticate to Vertex AI automatically via the GKE metadata server — no API keys or secrets needed.

Option 2: Gemini API Key (fallback)

Set GOOGLE_GENAI_USE_VERTEXAI=FALSE and provide GEMINI_API_KEY in your .env file. The script will create a Kubernetes Secret and mount it into sandbox pods. Use this option when WIF is not available (e.g., non-GKE clusters or testing without a GCP project).

1. Build and Push Application Images: Run the deployment script to create the Artifact Registry repo and push demo-app and main-app images:

   ./deploy.sh

2. Build and Push Sandbox Router Image: Run the helper script to clone the upstream repository (one level above root), build the router image, and push it to your registry:

   ./deploy_sandbox_router.sh

Run the infrastructure script. It will create a GKE Standard cluster with a gVisor node pool, enable the Agent Sandbox feature, and apply the templates using envsubst to inject your environment variables. Note that build_infra.sh has been updated to load environment variables more robustly.

./build_infra.sh

To access the Main Application UI or interact with the Gateway, you need to find the external IP address:

# For GKE Gateway
kubectl get gateway external-http-gateway

# For standard Service (to access front end UI)
kubectl get svc main-app-svc -n main-app-ns

Look for the ADDRESS or EXTERNAL-IP field in the output.

If you want to flush all active sandboxes and reset the environment (for example, after deploying a new container image) without deleting the entire GKE cluster, run the cleanup script:

./clean_sandboxes.sh

What this script does:

• Deletes all active SandboxClaims from the cluster.
• Flushes the warmpool pre-allocated pods.
• Automatically triggers a rolling restart of the main-app-deployment to cleanly synchronize its in-memory state and clear any transient data.

To avoid recurring charges, delete the GKE cluster when you are done:

gcloud container clusters delete agent-sandbox-cluster --region us-west1 --quiet

• Support Autopilot cluster as a cluster you can use when running on GKE.