About Agent Sandbox on GKE

Agent Sandbox on Google Kubernetes Engine (GKE) helps you run isolated agent workloads in dedicated Kubernetes Pods. Isolation is important when AI agents run untrusted, LLM-generated code. For most agent workloads, you should use Agent Substrate on GKE instead, because it can run more agents on the same nodes. Use Agent Sandbox on GKE when each agent needs a dedicated Pod, GPUs or TPUs, a full Kubernetes PodSpec, or a GKE Autopilot cluster. To compare Agent Sandbox on GKE with Agent Substrate on GKE and choose an architecture for your AI agent workloads, see Plan an architecture for AI agent workloads on GKE.

Agent Sandbox is an open source project under Kubernetes SIG Apps. To use Agent Sandbox on GKE, you install the Agent Sandbox controller on your cluster. You're responsible for upgrading the controller. For instructions, see Install Agent Sandbox on GKE.

This document provides a conceptual overview of Agent Sandbox on GKE.

Why use Agent Sandbox on GKE

Agent Sandbox on GKE gives each agent a dedicated, kernel-isolated Pod that you manage with standard Kubernetes APIs. Key benefits include the following:

  • Kernel-level isolation: Isolates untrusted, LLM-generated code from the node's kernel by using GKE Sandbox with gVisor or microVMs. Agent Sandbox on GKE also works with self-managed open source Kata Containers that you install on your nodes instead of GKE Sandbox. For a tutorial about using open source Kata Containers with Agent Sandbox on GKE, see Enabling Kata Containers on GKE.

  • Sub-second provisioning: Provides pre-warmed Pods for your agents, typically in less than one second, instead of waiting for standard Kubernetes Pod scheduling and startup.

  • Cloud-native extensibility: Leverages the power of the Kubernetes paradigm and the managed infrastructure of GKE.

By providing a declarative, standardized API, Agent Sandbox on GKE offers a single-container experience that provides isolation and persistence characteristics similar to a virtual machine (VM), built entirely on Kubernetes primitives.

Common use cases for Agent Sandbox on GKE

Use Agent Sandbox on GKE for workloads that require isolation, persistence, and a stable identity. Example use cases include the following:

  • AI agent runtimes: Run untrusted code in a Pod that uses gVisor or microVMs to isolate the code from the node's kernel.
  • Development environments: Provide developers with persistent, isolated cloud-based coding environments.
  • Notebooks and research tools: Host single-container sessions for interactive tools like Jupyter Notebooks.
  • Stateful single-Pod services: Run applications that need a stable identity and storage without the complexity of a StatefulSet.
  • Programmatic environment management: Use provided client library SDKs, such as the Agent Sandbox Python SDK, to request and manage Sandbox resources directly from your application logic without managing Kubernetes YAML.

How Agent Sandbox on GKE works

Agent Sandbox on GKE uses a custom controller and several Kubernetes Custom Resource Definitions (CRDs) to manage the lifecycle of Sandbox resources.

Core architecture

  • Sandbox custom resource: the primary resource that represents a single, stateful Pod. The resource manages stable hostnames, network identity, and persistent storage. To suspend an idle agent, set the spec.operatingMode field of its Sandbox resource to Suspended. The controller deletes the Pod but keeps the Sandbox resource and its persistent volumes. In-memory data and container file system changes are lost unless you take a Pod snapshot first. To resume the agent, set the field back to Running. Agent Sandbox on GKE doesn't detect idle agents; your application decides when to suspend them.
  • Sandbox Router: a component that provides a stable endpoint and tunnels traffic to the Pods that run your agents, abstracting the underlying networking complexity.
  • Integration with Pod snapshots: Agent Sandbox on GKE integrates with the GKE Pod snapshots feature to suspend and resume workloads by saving and restoring the full state of a container.

Claim model

The claim model is a key feature that separates the user's request for an environment from the specific implementation details, such as where and how the workload is provisioned. Unlike a standard Kubernetes StatefulSet, the claim model lets you request a Sandbox resource without needing to manage the underlying Pod or storage configurations directly.

The claim model uses the SandboxClaim, SandboxWarmPool, and SandboxTemplate custom resources and works as follows:

  1. Users or applications request a Sandbox resource by creating a SandboxClaim resource that references a SandboxWarmPool resource. The warm pool references the SandboxTemplate resource that defines the Pod configuration.
  2. The controller assigns a ready Sandbox resource (and its running Pod) from the warm pool to the claim. If no Sandbox resource in the pool is ready, the controller creates a new Sandbox resource for the claim from the template.

Warm pools

The warm pool feature is designed to minimize startup latency for interactive AI agent scenarios. By using a warm pool, Agent Sandbox on GKE can provide execution environments in less than one second. The feature uses the SandboxWarmPool custom resource and works as follows:

  1. A SandboxWarmPool resource maintains a pool of pre-warmed Sandbox resources with Pods in a ready state.
  2. When a SandboxClaim resource is created, the controller assigns a ready Sandbox resource and its running Pod from the pool instead of waiting for a new Pod to pull images and start.
  3. When combined with Pod snapshots, warm pools can restore Pods from a pre-configured state instead of starting them from scratch.

Network isolation

Agent Sandbox on GKE implements a default deny network policy for the Pods that the controller creates from a SandboxTemplate resource. For each SandboxTemplate resource, the controller creates a NetworkPolicy resource that helps prevent untrusted code inside the Pod from accessing unauthorized internal networks or the GKE control plane. You can define specific network restrictions and allowed egress or ingress rules within your SandboxTemplate resource to control network access for agent workloads.

The controller doesn't create a NetworkPolicy resource for a Sandbox resource that you create directly. To restrict network access for the Pods of these Sandbox resources, create your own NetworkPolicy resource.

Programmatic access with SDKs

AI engineers can consume Agent Sandbox on GKE resources programmatically by using the provided client libraries. For example, the Python SDK provides a high-level interface that creates the underlying SandboxClaim resource for you. The claim references a SandboxWarmPool resource that you create. This interface lets you create and interact with isolated environments directly from your Python-based agent frameworks like LangChain or the Vertex AI Agentic SDK.

Limitations and requirements

Agent Sandbox on GKE has the following limitations and requirements:

  • Cluster version: Agent Sandbox on GKE runs on any supported GKE version. To use Pod snapshots, your cluster must run GKE version 1.35.3-gke.1234000 or later.
  • Infrastructure requirements: Requires the Agent Sandbox controller to be installed and configured on the cluster. Agent Sandbox on GKE doesn't require a specific machine type. For example, the installation guide uses e2-standard-2 nodes. However, Pod snapshots don't support E2 machine types, so if you plan to use Pod snapshots, use another machine series, such as N2.
  • Isolation runtimes: Agent Sandbox on GKE supports gVisor and microVMs as isolation runtimes. Pod snapshots require gVisor and don't work with microVMs. If you don't specify a GKE Sandbox runtime (gVisor or microVMs), your Pods run without kernel isolation, so don't use them to run untrusted code.
  • Hardware accelerators: GPUs and TPUs work only with the gVisor runtime on supported GPU models and TPU versions, and aren't supported with microVMs. In addition, Pod snapshots don't support TPUs.
  • Underlying features availability: Some underlying features, such as GKE Pod snapshots, might be in Preview or have specific regional availability.

What's next