Kubernetes Agent Sandbox - The Sandbox CRD Explained
A Kubernetes-native primitive for agent workloads. Sandbox, SandboxTemplate, SandboxClaim and SandboxWarmPool, plus the runtimes that isolate them.
Why a Pod Was Not Enough
Kubernetes workload types were designed for long-lived services, and an agent sandbox is almost the opposite of one
Every existing Kubernetes workload type encodes an assumption about lifetime. A Deployment assumes a fungible replica set that should be kept running and replaced when it dies. A StatefulSet assumes ordered, stable identities that persist across restarts. A Job assumes a batch task that runs to completion and is then garbage collected. Each of those is a reasonable model for a service or a pipeline. None of them is a good model for an AI agent's execution environment.
An agent sandbox has an awkward combination of properties. It is short-lived, often measured in minutes. It is created on demand, at a rate driven by developer or agent activity rather than by a deployment rollout. It is stateful for its lifetime, because the agent has a working directory it expects to persist across the many tool calls of a session, and it wants a stable address so a controller can talk to it. It runs code that was generated rather than reviewed, so it must be strongly isolated. And because sessions start constantly, cold start time is a product-level concern rather than an operational detail.
Teams have been assembling this from parts for a while: a StatefulSet per session, a bespoke controller, a home-grown pool of idle pods, a RuntimeClass wired in by hand. The Kubernetes SIG project agent-sandbox is an attempt to standardize that assembly into a small set of custom resources. It sits on the isolation ladder above a plain container and below a dedicated microVM, and it is the newer, standardized expression of the patterns described on sandbox environments.
What a Service Workload Assumes
- Long lifetime, measured in days or weeks
- Created by a rollout, not by user demand
- Replicas are interchangeable
- Startup latency amortized over the lifetime
- Runs code that passed review and CI
What an Agent Sandbox Assumes
- Short lifetime, often minutes
- Created on demand at high rate
- Each one belongs to a specific session
- Startup latency is felt on every task
- Runs generated, unreviewed code
The Four Resources
Sandbox, SandboxTemplate, SandboxClaim and SandboxWarmPool, and how they compose
Sandbox
The core resource. The project documentation describes it as a "Declarative API for a single, stateful pod with a stable hostname and optional persistent storage." That sentence is the whole design: one pod, not a replica set; stable identity so a controller can address the session reliably; storage that survives the many tool calls within a session. This is the object an orchestrator creates when it wants one agent to have somewhere to run.
SandboxTemplate
A reusable runtime configuration. The platform team defines the image, the resource limits, the runtime class, the mounts, and the policies once; consumers reference the template by name. The documented purpose is to let teams provision sandboxes consistently without exposing the underlying complexity, which in practice means application teams stop hand-writing pod specs and the platform team keeps a single place to change the security posture.
SandboxClaim
The user-facing request. A claim asks for a sandbox from a template, and the controller satisfies it either by creating one or by handing over a pre-warmed instance from a pool. The pattern will be familiar to anyone who has used a PersistentVolumeClaim: the consumer expresses what it needs, the platform decides how that need is met, and the two are decoupled so pooling can be introduced without changing any caller.
SandboxWarmPool
The documentation describes it as "Pre-warmed pod pools for near-instant sandbox allocation." It exists because cold start dominates short tasks: pulling an image and initializing a workspace can easily exceed the runtime of the task itself. Warm capacity is billed continuously whether or not anything claims it, so pool depth is a direct budget decision, discussed further under agent fleets.
How They Compose
Platform team defines once
SandboxTemplate (image, limits, runtimeClass, policy)
|
+-- SandboxWarmPool (keeps N ready instances of that template)
|
Agent orchestrator asks per session
SandboxClaim (please give me one of those)
|
\-- Sandbox (a single stateful pod, stable hostname, storage)The important property is that the claim does not care whether it was satisfied from a warm pool or by a cold creation. You can add pooling, remove it, or change its depth without touching the orchestrator, which is exactly the seam you want when you are still learning what your arrival rate looks like.
A Minimal Sandbox
The smallest useful manifest is a pod template wrapped in the Sandbox kind. The project's README examples use the agents.x-k8s.io/v1beta1 API group and version, and the documentation includes a migration guide covering the move from v1alpha1 to v1beta1. Confirm the group version against the release you install rather than copying it from any article, including this one.
apiVersion: agents.x-k8s.io/v1beta1
kind: Sandbox
metadata:
name: agent-session-4f21
namespace: agent-sandboxes
spec:
podTemplate:
spec:
runtimeClassName: gvisor
containers:
- name: workspace
image: registry.internal/agent-workspace:2026-07
resources:
requests:
cpu: "2"
memory: 4Gi
limits:
cpu: "4"
memory: 8GiThe template and claim pair below shows the shape of the platform-team split. Treat the field names as illustrative of the pattern rather than as a copy-paste manifest: verify them against the CRDs shipped with the version you deploy, because the API is still moving.
# Defined once by the platform team
apiVersion: agents.x-k8s.io/v1beta1
kind: SandboxTemplate
metadata:
name: coding-agent-standard
namespace: agent-sandboxes
spec:
podTemplate:
spec:
runtimeClassName: gvisor
automountServiceAccountToken: false
containers:
- name: workspace
image: registry.internal/agent-workspace:2026-07
resources:
limits:
cpu: "4"
memory: 8Gi
---
# Requested per session by the orchestrator
apiVersion: agents.x-k8s.io/v1beta1
kind: SandboxClaim
metadata:
name: claim-4f21
namespace: agent-sandboxes
labels:
team: team-payments
costCenter: eng-platform
spec:
sandboxTemplateName: coding-agent-standardTwo habits are worth building in from the start. Put sandboxes in their own namespace so quotas, network policy, and RBAC apply to the whole class of workload at once. And label every claim with the team and cost center that triggered it, because attribution applied at creation is the only kind that survives to the bill.
Runtimes and Isolation Strength
The CRD gives you a declarative object. The runtime class is what decides how strong the boundary actually is.
A Sandbox is still a pod, and a default pod shares the node's kernel. The project's design notes describe supporting different runtimes such as gVisor or Kata Containers to provide enhanced security, and the documentation lists standard OCI containers, gVisor for kernel-level sandboxing, and Kata Containers for VM-grade isolation. Which one you get is a function of the runtimeClassName on the pod template, not of the Sandbox kind itself. Creating a Sandbox with no runtime class buys you the ergonomics without the isolation.
This is the single most important thing to get right on the page. The declarative API and the isolation boundary are separate decisions that happen to be expressed in the same manifest, and it is entirely possible to adopt the CRD, feel more secure, and be running exactly the same shared-kernel containers you were running before.
Runtime Choices Under the Sandbox CRD
| Runtime | Mechanism | Isolation strength | Main cost | Blast radius |
|---|---|---|---|---|
| Standard OCI (runc) | Namespaces and cgroups | Baseline | None beyond the pod | The node's shared kernel |
| gVisor | User-space kernel intercepting syscalls | Strong syscall boundary | Syscall compatibility gaps, I/O overhead | The gVisor sentry, not the host kernel directly |
| Kata Containers | Lightweight VM per pod, own guest kernel | VM-grade | Requires KVM-capable nodes, slower start | One virtual machine |
Runtime characteristics are covered in depth on microVM isolation. Availability of a given runtime class depends on your node pools and your Kubernetes distribution, so confirm before designing around one.
The Runtime Is Necessary but Not Sufficient
A hardened runtime constrains what code inside the sandbox can do to the node. It does nothing about what that code can reach over the network, what secrets are mounted into it, or what a service account token lets it do to the cluster API. Network policy, egress allowlists, disabled service account token automounting, and dedicated node pools are all separate decisions you still have to make. Northflank's explainer puts the general limitation well: "Agent sandbox provides the isolation primitive and the declarative API, but not the surrounding production infrastructure your platform needs."
Snapshots and Warm Start
Attacking cold start from both ends: keep capacity ready, and restore initialized state instead of rebuilding it
Cold start is the defining performance problem for agent sandboxes, because the work being done is often short enough that setup dominates. Pulling an image, mounting storage, installing dependencies, and warming a language server can take longer than the change the agent was asked to make. Warm pools address part of this by keeping capacity provisioned in advance, but a pool member is only warm in the sense of being scheduled and running: it has not read your repository or installed your dependencies.
Snapshots attack the other half. Google Kubernetes Engine documents Pod snapshots for Agent Sandbox, which save and restore the state of a running sandbox, enabling pre-warmed snapshots, pause and resume for long-running agents, and reproducibility by capturing an initialized state. The restored sandbox comes back with dependencies installed and caches populated, which is a categorically different starting point from a freshly scheduled pod.
Pause and Resume
A long-running agent that is blocked, waiting on a human, or waiting on an external system does not need to hold compute. Snapshotting it and restoring later converts held capacity into stored state, which is generally the cheaper of the two.
Reproducible Starting Points
A snapshot taken after setup gives every session an identical, known-good baseline. That removes a whole class of "it failed because the install was flaky" outcomes, which matters because failed attempts are billed exactly like successful ones.
Constraints Apply
GKE documents that Pod snapshots require "GKE version 1.35.3-gke.1234000 or later" and states plainly that "Pod snapshots don't support E2 machine types," with further limitations on GPU machine types. Check the node pool before designing around snapshots.
Snapshot Support Is Still Landing
GKE's own guide describes its installation path as provisional: the tutorial "uses a manual installation method to deploy the Agent Sandbox components directly from the open-source GitHub repository," and calls that "a temporary workaround until the snapshot features are fully available in the GKE Agent Sandbox add-on." Read that as a feature in motion. It is worth prototyping against and worth being careful about committing a platform roadmap to.
Maturity: Read This Before You Depend On It
What the project claims about itself, and what it does not
The agent-sandbox repository does not carry an explicit maturity label such as alpha, beta, or stable, and it makes no statement about production readiness or stability guarantees. It describes itself as a community-driven effort. The strongest available signal about API stability is the API version itself: the README examples use agents.x-k8s.io/v1beta1, and the documentation includes a migration guide for moving from v1alpha1 to v1beta1. Third-party explainers written earlier still show v1alpha1 manifests, which is a useful reminder of how recently that changed.
The honest summary is that this is a young standardization effort with a documented breaking API change already behind it, backed by a Kubernetes SIG and with at least one managed platform building on it. That is a genuinely promising position, and it is not the same thing as a stable API you should hard-code into a platform. Anyone stating otherwise is filling in a claim the project has not made.
Reasonable Today
- Prototyping an agent execution platform
- Replacing a home-grown pod controller
- Adopting the resource model as a design vocabulary
- Internal, single-tenant workloads
Approach With Care
- Externally facing multi-tenant platforms
- Anything with a compliance attestation attached
- Manifests generated by tools you cannot re-run
- Roadmaps that assume snapshot GA dates
Practical Hedges
- Pin the controller version explicitly
- Generate manifests, do not hand-maintain them
- Keep a fallback path to plain pods
- Re-read the CRDs on every upgrade
Related
Neighbouring rungs on the ladder, and the cluster work around them
Git Worktrees
The bottom rung: separate directories with no isolation at all.
Agent Fleets
What warm pools and concurrency caps actually cost to run.
MicroVM Isolation
Firecracker, Cloud Hypervisor, Kata, and gVisor in depth.
Sandbox Environments
The patterns this CRD standardizes, and the vendors offering them.
Kubernetes Development
Running development workloads on Kubernetes generally.
Ephemeral Environments
Short-lived environments created and torn down per task.
Multi-Cluster
Spreading sandbox capacity across clusters and regions.
Capacity Planning
Sizing warm pools and node pools against real arrival rates.
Sources
Upstream documentation and vendor references cited here.