agent-sandbox: a Sandbox CRD for singleton, stateful AI agent workloads on Kubernetes
agent-sandbox enables easy management of isolated, stateful, singleton workloads, ideal for use cases like AI agent runtimes and reinforcement learning (RL).
At a glance
- What is it?
- The Kubernetes SIG Apps project defines a Sandbox custom resource for one stateful pod with a stable identity and optional persistent storage, plus extensions for templates, claims and warm pools. It is a sandbox orchestrator, not an isolation layer, and the README is explicit about that boundary.
- Who is it for?
- 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.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
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. The README does not publish pool sizing guidance or a target allocation latency, so treat that as something you would have to measure against your own runtime image.
Installing agent-sandbox and verifying it took
The recommended path is the combined manifest, which the README describes as a single, collision-free asset where the controller is declared once with extensions enabled. It is the path recommended for GitOps engines such as Argo CD, Config Sync and kustomize.
export VERSION="vX.Y.Z" 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. Verification is two commands: kubectl get crd sandboxes.agents.x-k8s.io and kubectl get deploy agent-sandbox-controller -n agent-sandbox-system. The controller namespace is agent-sandbox-system. Note the placeholder: the README tells you to replace vX.Y.Z with a specific tag from the releases page, and the example it gives is v0.1.0, which is older than the v1.0.1 release listed for this repository. Pin the tag you actually intend to run.
Uninstall deletes data, so the README asks you to look first
The uninstall section is unusually blunt. Before removing anything, it asks you to enumerate in-use resources: kubectl get sandboxes -A, and for extensions kubectl get sandboxclaims -A, kubectl get sandboxwarmpools -A and kubectl get sandboxtemplates -A, each guarded by a check that the corresponding CRD exists. The warning states that deleting the CRDs will cascade-delete all custom resources of those types across all namespaces. That is standard Kubernetes CRD behaviour, but it is worth stating plainly because Sandboxes can carry persistent storage that survives restarts. The README does not spell out whether the PVCs behind a Sandbox outlive the Sandbox object, so if your data matters, verify the storage ownership behaviour on a throwaway namespace before you run the delete against a shared manifest. Deleting the same manifest you installed is the documented removal path.
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. The README does not reproduce Python install commands, so the package name and installation method are not confirmable from the material here. 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: v0.5.6, then v1.0.0, then v1.0.1 within roughly two weeks in August and September 2026. Reaching v1.0.0 signals an API stability claim from the maintainers, but the README does not describe a deprecation policy, conversion webhooks or a support window for older CRD versions. 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.
Community notes