Blog
9 min read

Agent Sandbox for Kubernetes: The SIG Apps Project for Running AI Agents on K8s and GKE

Agent Sandbox is a Kubernetes SIG Apps project for isolated, stateful agent pods. How its Sandbox CRD, warm pools, gVisor/Kata isolation and GKE support work.

Agent Sandbox is an open-source Kubernetes project, developed under SIG Apps in the kubernetes-sigs organization, that adds a Sandbox custom resource and controller for running one isolated, stateful pod per agent, user or session. It gives each sandbox a stable identity and optional persistent storage, can suspend and resume it, and adds templates, claims and warm pools for fast allocation. It doesn't isolate anything by itself: strong isolation comes from pointing the pod at a sandboxed runtime such as gVisor or Kata Containers through a RuntimeClass. Google Kubernetes Engine documents it as the way to run agent workloads on GKE.

This article covers what the project is, how its resources fit together, what isolation you actually get, how it runs on GKE, and how mature it is as of November 2026. Facts are from the project repository, its documentation site and Google Cloud's GKE docs.

The problem it solves

Kubernetes has good primitives for two shapes of workload. Deployments run many interchangeable, stateless replicas. StatefulSets run a numbered set of pods with stable names and volumes.

An AI agent's execution environment is neither. You want one pod per session, with its own hostname, its own disk that survives a restart, and a lifecycle tied to the session: create it on demand, pause it when idle, delete it later. You can approximate that with a StatefulSet of size 1, a Service and a PersistentVolumeClaim per agent, but the README calls that approach "cumbersome", and it gives you no notion of suspending or expiring a session.

The project lists the use cases it targets: AI agent runtimes running untrusted LLM-generated code, development environments, reinforcement learning and evaluation loops, notebooks such as Jupyter, and single-instance services like build agents. (If you're still deciding whether you need Kubernetes at all, start with Do You Need Kubernetes? and What Is Kubernetes?.)

The core resource: Sandbox

A Sandbox wraps a pod template and the controller makes sure exactly one pod exists for it. The minimal example from the README:

apiVersion: agents.x-k8s.io/v1beta1
kind: Sandbox
metadata:
  name: my-sandbox
spec:
  podTemplate:
    spec:
      containers:
      - name: my-container
        image: <IMAGE>

A more realistic one, using fields from the v1beta1 API types:

apiVersion: agents.x-k8s.io/v1beta1
kind: Sandbox
metadata:
  name: agent-42
spec:
  service: true                # create a headless Service for a stable DNS name
  operatingMode: Running       # or Suspended
  shutdownTime: "2026-12-01T00:00:00Z"
  shutdownPolicy: Retain       # or Delete
  podTemplate:
    spec:
      runtimeClassName: gvisor
      containers:
      - name: agent
        image: ghcr.io/example/agent-runtime:1.0
        volumeMounts:
        - name: workspace
          mountPath: /workspace
  volumeClaimTemplates:
  - metadata:
      name: workspace
    spec:
      accessModes: ["ReadWriteOnce"]
      resources:
        requests:
          storage: 10Gi

What the fields do, according to the API definitions:

  • volumeClaimTemplates creates a PVC per template, named after the template and the Sandbox, and owned by the Sandbox. The list is immutable after creation. The PVC is kept while the Sandbox is suspended or retained after expiry, and garbage-collected when the Sandbox object is deleted.
  • operatingMode: Suspended terminates the pod but keeps the Sandbox object and its volumes. Setting it back to Running creates a new pod that reattaches the same volumes.
  • shutdownTime is an absolute expiry. When it passes, the pod and Service are torn down. shutdownPolicy: Retain (the default) keeps the Sandbox object with an expired status; Delete removes it.
  • service: in current releases, the controller only creates a new headless Service when this is true.

Note what suspension means. The pod is gone, so anything in memory and anything written to the container's own filesystem (outside a mounted volume) is lost. Only data on the PVC survives. On GKE, Pod snapshots can capture more; see below.

Extensions: templates, warm pools and claims

The core CRD is enough if your platform creates each Sandbox itself. The optional extensions (API group extensions.agents.x-k8s.io, also v1beta1) separate the platform team's configuration from per-user requests and cut startup time.

  • SandboxTemplate: a reusable blueprint, typically owned by an admin. It holds the pod template, volume claim templates and an optional networkPolicy block; when present, the controller creates a NetworkPolicy for each sandbox so sandboxes can't talk to each other.
  • SandboxWarmPool: keeps a number of pre-created Sandboxes from a template ready, so a request doesn't wait for scheduling, image pull and container start.
  • SandboxClaim: what a user or application creates. It points at a warm pool and gets a Sandbox adopted from it, without needing to know the pod details.

From the project's warmpool-quickstart example (trimmed):

apiVersion: extensions.agents.x-k8s.io/v1beta1
kind: SandboxWarmPool
metadata:
  name: sandboxwarmpool-example
  namespace: default
spec:
  replicas: 1
  sandboxTemplateRef:
    name: secure-datascience-template
---
apiVersion: extensions.agents.x-k8s.io/v1beta1
kind: SandboxClaim
metadata:
  name: my-secure-sandbox
  namespace: default
spec:
  warmPoolRef:
    name: sandboxwarmpool-example
  lifecycle:
    shutdownPolicy: Delete

The claim must be in the same namespace as the warm pool. The template controls whether claims may add or override volume claim templates (volumeClaimTemplatesPolicy: Disallowed by default, or Allowed or Overrides).

There are also Go and Python SDKs (pip install k8s-agent-sandbox) and an optional Sandbox Router, an HTTP reverse proxy that routes SDK and client traffic to sandbox pods. The README notes it is useful with runtimes like gVisor and Kata where direct pod port-forwarding isn't available.

Isolation: the part you configure yourself

The README is explicit that Agent Sandbox is a "sandbox orchestrator" that "delegates low-level container isolation" to runtimes such as gVisor or Kata Containers via RuntimeClass. A Sandbox without runtimeClassName is an ordinary container sharing the node's kernel with every other pod there. Google's docs say the same: without a sandboxed runtime, "don't use them to run untrusted code."

Your options:

  • gVisor intercepts the container's system calls in a user-space kernel, so the workload never talks to the host kernel directly. Lower overhead than a VM, with some syscall and I/O compatibility and performance costs.
  • Kata Containers run each pod inside a lightweight virtual machine with its own guest kernel. Stronger hardware-level boundary, more per-pod overhead, and you need nodes that support virtualization. The runtimeClassName you set depends on how Kata is installed in your cluster.

Firecracker vs gVisor vs Containers and Kata Containers go into the trade-offs.

Runtime isolation is one layer. For agents running LLM-generated code you'll also want the template's network policy (default-deny egress except what the agent needs, and no access to the Kubernetes API server), a non-root security context, and no service account token unless the agent needs one. The project publishes a threat model in docs/security/ that is worth reading before you run untrusted code.

Agent Sandbox on GKE

Google documents Agent Sandbox for GKE in a concept page and an install guide. Key points from those docs as of November 2026:

  • You install the open-source controller yourself with the same release manifest (kubectl apply -f .../sandbox-with-extensions.yaml) or Helm, and you're responsible for upgrading it. The guide pins v1.0.6 and says to use the same Python SDK version as the controller. The docs show no gcloud flag that enables it as a managed add-on.
  • Isolation uses GKE Sandbox. On Autopilot, gVisor is available automatically. On Standard you create a node pool with --sandbox=type=gvisor. The example SandboxTemplate sets runtimeClassName: gvisor plus a node selector and toleration for sandbox.gke.io/runtime=gvisor. The concept page also mentions microVM-based GKE Sandbox, and says self-managed Kata works but isn't a Google product, so Google's support doesn't cover it.
  • Pod snapshots let you suspend and resume a sandbox including its memory state. They require gVisor (not microVMs), GKE 1.35.3-gke.1234000 or later, and don't support E2 machine types or TPUs. Some of these features may be in Preview or limited to certain regions.
  • Warm pools: Google says Agent Sandbox on GKE "can provide execution environments in less than one second" by handing out a pre-warmed sandbox.
  • No idle detection: GKE doesn't decide when an agent is idle. Your application has to suspend sandboxes itself.

Agent Sandbox itself runs on any Kubernetes 1.25 or later with CRD CEL validation enabled (1.29+ recommended), so you aren't tied to GKE. The examples directory includes setups for AKS with Kata and EKS as well.

How mature is it?

Be clear-eyed here.

  • Young, but past alpha. v1.0.0 (August 2026) moved the core and extension APIs from v1alpha1 to v1beta1 and removed v1alpha1 support, a breaking change that required migrating stored resources. The latest release when this was written was v1.0.11 on 12 November 2026, roughly one release a week since 1.0.
  • v1beta1 is a beta API. In Kubernetes convention that means the schema can still change between versions. The field comments in the current API types already show deprecated annotations and reasons, which is normal for a project moving this fast. Pin a version, read release notes before upgrading, and test upgrades on a non-production cluster.
  • It's a SIG subproject, not core Kubernetes. It ships as CRDs and a controller you install. It isn't part of a Kubernetes release and isn't covered by Kubernetes' API deprecation policy for built-in APIs.
  • Some headline features are aspirations. The README lists "deep hibernation", "automatic resume" on network connection and "memory sharing across sandboxes" under desired characteristics. Suspend and resume via operatingMode exists today; automatic wake-on-traffic is not something to plan around without checking the current release.

For a platform team that already runs Kubernetes and wants a standard API for per-agent pods, it's a reasonable bet with active development and Google behind the GKE integration. For a small team without a cluster, adopting Kubernetes to get it is a lot of new infrastructure.

Ephemeral or persistent? Agent Sandbox can do both

A lot of agent infrastructure assumes ephemeral sandboxes: create, run a snippet, destroy. We've argued that this fits running untrusted code well and fits building software badly, because development work accumulates state: a cloned repo, installed dependencies, a running database, notes the agent left itself. (The Sandbox Is the Wrong Abstraction for AI Coding Agents.)

Agent Sandbox is interesting because its API covers both ends:

  • Ephemeral: a SandboxClaim from a warm pool with shutdownPolicy: Delete and a near shutdownTime. Good for code interpreters, tool calls and RL rollouts where each run should start clean.
  • Persistent: a Sandbox with a PVC, suspended when idle and resumed later with its disk intact. That's the "disposable runtime, durable project" split: the pod is replaceable, the workspace isn't. The PVC survives suspension and expiry with Retain, but it's deleted with the Sandbox object, so treat "delete Sandbox" as "delete the project" and back up accordingly.

What it doesn't decide for you is which one your workload needs. That's an application decision: does the work have a memory?

EasySpawn takes the persistent side without Kubernetes: each project lives on its own cloud server with Claude Code, Postgres and Redis, and the runtime can be rebuilt without losing the work. See how it works or join the waitlist.

Related: Do You Need Kubernetes? (Probably Not Yet — Here's How to Tell) · What Is Kubernetes? A Beginner's Explanation Without the Jargon · Firecracker vs gVisor vs Containers: Choosing Isolation for Untrusted Code · Kata Containers: Container Ergonomics With VM Isolation

Keep reading