agent-sandbox: a Sandbox CRD for singleton, stateful AI agent workloads on Kubernetes

The gap agent-sandbox targets between Deployments and StatefulSets

The README frames the problem directly: the Sandbox CRD exists for workloads that "don't fit well into the stateless, replicated model of Deployments or the numbered, stable model of StatefulSets." An AI agent runtime is the example given. It wants one container, a stable hostname and network identity, storage that survives a restart, and a lifecycle that can be paused or scheduled for deletion rather than scaled up and down by a replica count. StatefulSets give you ordinal identity across N replicas and a controller that assumes a set. A Sandbox is the singleton case made explicit as its own API object. The intended audience is platform engineers running agent runtimes or reinforcement learning environments who want that singleton to be a first-class Kubernetes resource rather than a hand-rolled Pod plus Service plus PVC bundle. The project sits under SIG Apps, which matters for adopters who care whether an API has a home in the Kubernetes org rather than a single vendor's repository.

What the Sandbox controller actually manages

According to the README, the Sandbox controller handles creation of the underlying Pod, scheduled deletion, pausing and resuming. Persistent storage is configurable and survives restarts. The architecture diagram shows the flow: a user creates a Sandbox, the Sandbox creates a Pod, and that Pod is pointed at a sandbox runtime. The isolation itself is not implemented here. The project describes itself as a "sandbox orchestrator" that "delegates low-level container isolation to secure 'Sandbox Runtimes' (like gVisor or Kata Containers) by managing Pods configured to use these runtimes (via RuntimeClass)." That single sentence is the most important design fact in the repository. If you install agent-sandbox on a cluster with no gVisor or Kata RuntimeClass configured, you get lifecycle management and stable identity, not a hardened boundary. The controller pattern is the standard Kubernetes one: custom resource in, runtime resources out, reconciliation loop in between.

SandboxTemplate, SandboxClaim and SandboxWarmPool

The extensions module adds three CRDs on top of the core Sandbox API. SandboxTemplate defines reusable templates so that many similar Sandboxes do not each carry a full spec. SandboxWarmPool manages a pool of pre-warmed Sandboxes, and its stated purpose is reducing the time to get a new Sandbox running. SandboxClaim lets a user request a Sandbox out of a warm pool, abstracting the underlying configuration away. The diagram shows the relationship: the warm pool references a template, the warm pool pre-warms Sandboxes, and a claim adopts sandboxes from the warm pool. This is a familiar pattern for anyone who has worked with pre-provisioned capacity. The trade-off is resource cost: a warm pool holds Sandboxes that are running before anyone asks for them, so the latency win is paid for in idle capacity. Treat pool sizing and allocation latency as something you would have to measure against your own runtime image.

Installing agent-sandbox and verifying it took

The recommended path for most users is the combined sandbox-with-extensions.yaml manifest, and the README recommends pinning a specific version for production and GitOps.

export VERSION="v1.0.2" kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/sandbox-with-extensions.yaml

You can also render from source with kubectl kustomize k8s/. If you want components separately, the release assets sandbox.yaml (core) and extensions.yaml (opt-in) are applied the same way. To check for an existing install, the README starts with kubectl get crd sandboxes.agents.x-k8s.io. Note the example: the README pins v1.0.2, which is older than the v1.0.9 release now listed for this repository. Pin the tag you actually intend to run.

Uninstall deletes data, so the README asks you to look first

Deleting a CRD cascade-deletes all custom resources of that type across all namespaces. That is standard Kubernetes CRD behaviour, but it is worth stating plainly because Sandboxes can carry persistent storage that survives restarts. If your data matters, verify the storage ownership behaviour on a throwaway namespace before you run the delete against a shared manifest.

The Go and Python SDKs ship from the repository root

For programmatic access there is a Go SDK, fetched with go get sigs.k8s.io/agent-sandbox/clients/go/sandbox@latest. The README notes a detail that trips people up: the Go SDK ships from the repository's root Go module, so repository release tags such as v0.1.0 are also the SDK versions. That means the SDK version and the controller version are not independently versioned, and upgrading one implies the other. A Python SDK is also referenced, with its own README under clients/python/agentic-sandbox-client. If you are writing a control plane in Go, the SDK is the natural entry point. If you are writing one in Python, read that subdirectory README before assuming parity with the Go client.

Where agent-sandbox is the wrong tool

The clearest failure mode is a category error about isolation. Because the project delegates to RuntimeClass, a cluster without a configured sandbox runtime gets a controller that manages Pods without the isolation the name suggests. The README's own note is the source for this, and it is the first thing to check before adopting. The second case is scale-out. A Sandbox is a singleton by design. If you need five replicas behind a Service with rolling updates, a Deployment is the right object, and using SandboxTemplate plus SandboxClaim to emulate that would mean reimplementing scheduling and rollout that Kubernetes already gives you. The third case is short-lived, stateless jobs. The value here is stable identity and persistent storage across restarts; a task that finishes in seconds and holds no state pays for lifecycle machinery it never uses. The fourth is multi-tenancy by namespace alone. The project does not claim to provide tenant isolation beyond what the runtime and your cluster policy supply.

How this differs from running gVisor or Kata directly

The obvious alternative is to skip the CRD and manage Pods yourself, either with a RuntimeClass set on a plain Pod spec or with a StatefulSet of one replica. The difference is in what you own. With a raw Pod plus RuntimeClass, you get isolation but you write the reconciliation yourself: recreating the Pod after eviction, wiring the PVC, handling pause and resume, and cleaning up on a schedule. A single-replica StatefulSet gets you stable identity and storage, and it is a reasonable substitute if that is all you need, but its controller is built around the replica-set model and the README positions Sandbox as the answer for workloads that do not fit it. The extensions are where the gap widens, because SandboxTemplate, SandboxClaim and SandboxWarmPool have no direct equivalent in the Pod or StatefulSet APIs. Pre-warmed capacity handed to a claimant is a pattern you would otherwise assemble from scratch. The cost of the CRD route is a second controller in your cluster and a dependency on its release cadence.

Upgrade cost, release cadence and the Apache-2.0 terms

The repository shows a fast cadence: v1.0.7, v1.0.8 and v1.0.9 shipped a week apart in October 2026. Reaching v1.0.0 signals an API stability claim from the maintainers. Upgrading means applying a newer manifest over the existing one, and because CRDs are cluster-scoped, an upgrade is a cluster-wide operation rather than a namespaced rollout. The licence is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant; it also requires that you preserve notices and state changes. That is a summary of the licence identifier the repository declares, not legal advice. If you redistribute a modified controller, read the LICENSE file and your own counsel's guidance rather than this article. The Go SDK versioning coupling described above is the practical upgrade cost to plan for: a controller bump and a client bump land together.

Editorial conclusion

Adopt agent-sandbox if you already run Kubernetes and need one long-lived, stateful pod per agent or RL environment, and you have a RuntimeClass such as gVisor or Kata Containers available for the isolation layer. Do not adopt it if you expect it to provide that isolation itself, or if your workload is a replicated stateless service better served by a Deployment. Before installing, confirm which release tag you are pinning, check that the sandbox-with-extensions.yaml asset exists for that tag, and run kubectl get crd sandboxes.agents.x-k8s.io to see whether a previous install is already present.

Frequently asked questions

Official sources

1. kubernetes-sigs/agent-sandbox on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases