kubernetes-sigs/agent-sandbox: a Sandbox CRD for singleton, stateful agent runtimes

The gap agent-sandbox targets: one pod, one identity, persistent state

Deployments assume replicas are interchangeable. StatefulSets give each replica a stable ordinal name and its own volume, but they are built around N members of a set, with the controller managing ordered rollout across that set. Neither model matches a workload that is a single container which should keep the same hostname for its whole life, hold data across restarts, and be paused or resumed on demand. That is the shape agent-sandbox names in its own description: isolated, stateful, singleton workloads, with AI agent runtimes and reinforcement learning given as the motivating cases.

The project is a Sandbox Custom Resource Definition plus a controller, developed under the umbrella of SIG Apps. The README frames the goal as a declarative, standardized API for workloads that need the characteristics of a long-running, stateful, singleton container with a stable identity, described as a lightweight, single-container VM experience built on Kubernetes primitives. The audience is therefore platform teams running Kubernetes who want agent sessions to look like ordinary cluster objects rather than bespoke processes on a VM.

How the Sandbox controller and the extensions module fit together

The architecture follows the standard Kubernetes controller pattern. A user creates a Sandbox custom resource; the controller creates and manages the underlying Pod, and the Pod is configured to run under a Sandbox Runtime through RuntimeClass. The README is explicit about the boundary: agent-sandbox is a sandbox orchestrator and delegates low-level container isolation to secure Sandbox Runtimes such as gVisor or Kata Containers. This is the most consequential design decision in the project, and it is a trade-off rather than a feature. You get a uniform API across runtimes, but you get nothing until a runtime exists on your nodes.

The core CRD covers three things: a stable hostname and network identity, persistent storage that survives restarts, and lifecycle management including creation, scheduled deletion, pausing and resuming. The extensions module layers three more CRDs on top. SandboxTemplate defines reusable templates so many similar Sandboxes can share a definition. SandboxWarmPool keeps a pool of pre-warmed Sandboxes. SandboxClaim lets a user request a Sandbox from that pool, adopting one rather than describing the underlying configuration. In the diagram in the README, the warm pool references a template, pre-warms Sandboxes, and a claim adopts sandboxes from the pool. The point of the claim path is allocation latency: a pre-warmed Sandbox is already running when the claim arrives.

Installing agent-sandbox with kubectl apply and creating a first Sandbox

The README recommends the combined manifest for most users and for GitOps engines such as Argo CD, Config Sync and kustomize, because it is a single collision-free asset with the controller declared once and extensions enabled. Set VERSION to a real release tag from the releases page, then apply it.

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

If you would rather install the pieces separately, the README documents a core-only manifest and an opt-in extensions manifest at the same release path, sandbox.yaml and extensions.yaml respectively. The same page notes that you can render the manifests from source with kubectl kustomize k8s/ instead of downloading a release asset. After applying, verify that the installation landed.

kubectl get crd sandboxes.agents.x-k8s.io
kubectl get deploy agent-sandbox-controller -n agent-sandbox-system

Those two commands are the README's own check: if the CRD and the controller deployment are present, agent-sandbox is installed. The controller namespace is agent-sandbox-system. For programmatic use there are two SDKs. The Go SDK installs from the repository's root Go module, so release tags are also SDK versions.

go get sigs.k8s.io/agent-sandbox/clients/go/sandbox@latest

The Python client lives under clients/python/agentic-sandbox-client and the README points to its own README for installation and usage rather than repeating the steps. The examples directory is where the concrete manifests live; it lists entries such as hello-world-sandbox, jupyterlab, chrome-sandbox, firecracker-sandbox, kata-aks-sandbox and agent-sandbox-rl. Start with hello-world-sandbox before wiring an agent into it.

What the README does not settle: runtimes, rollback and the deletion path

Because isolation is delegated, the project cannot make a workload safe on its own. If your cluster has no gVisor or Kata Containers RuntimeClass installed and configured, a Sandbox is a pod with a stable name and a volume, and the security properties people associate with the word sandbox do not follow from the CRD. The README does not document rollback between versions, so a version downgrade path is not something you can plan from the repository's front page. Treat the release assets as forward-only until you have read the release notes for the version in question.

The uninstall path deserves attention before you install anything. The README warns that deleting the CRDs cascade-deletes all custom resources of those types across all namespaces. It suggests checking for in-use resources first, including the extension types only if their CRDs exist.

kubectl get sandboxes -A
kubectl get crd sandboxclaims.extensions.agents.x-k8s.io >/dev/null 2>&1 && kubectl get sandboxclaims -A

Uninstalling means deleting the same manifest you applied. There is no separate drain or scale-to-zero step documented, so the check above is the safety net the project offers. Persistent storage attached to a Sandbox is a second question the README leaves open: it says storage survives restarts, but it does not describe what happens to the underlying volume when the Sandbox object itself is deleted.

agent-sandbox against plain StatefulSets and against full VM sandboxes

The nearest built-in alternative is a StatefulSet with one replica and a volumeClaimTemplate. That gives you stable naming and storage, and it is already in every Kubernetes distribution. The difference is intent and surface area: a StatefulSet still models membership in a set, its controller is built for ordered rollout across ordinals, and there is no first-class pause, resume or scheduled deletion on the object. agent-sandbox narrows the API to exactly one workload and adds those lifecycle verbs, plus the template, warm pool and claim layer for handing pre-warmed instances to users. If you never need those, the StatefulSet is less machinery.

A different alternative is a dedicated sandbox platform or a VM-per-session service, which bundles isolation and lifecycle in one product. agent-sandbox takes the opposite position: it stays inside the Kubernetes API and expects you to bring the runtime. That is a real difference in operational ownership. With the bundled approach you adopt a new control plane; with agent-sandbox you extend the one you already run, at the cost of assembling the runtime layer yourself. The examples list reflects this, with entries for Cilium egress policies, network policy composition, and multiple runtime-specific setups, which is where much of the real work sits.

Maintenance, versioning and the Apache-2.0 licence

The repository is not archived and the last push was on 2026-09-10. Recent releases are v1.0.1 on 2026-09-03, v1.0.0 on 2026-08-28 and v0.5.6 on 2026-08-20, so the major version is recent and the API should be treated as young. The Go module declares go 1.26.0 with toolchain go1.26.4, and the Dockerfile builds with golang:1.27.1 and produces a distroless static-debian13:nonroot image. If you build from source rather than consuming release manifests, your Go toolchain and image base need to keep pace with those declarations.

The project is licensed Apache-2.0, which is the same licence as Kubernetes itself and is permissive by design. That matters for redistribution and for embedding the SDKs in your own products, but it says nothing about the licence of the Sandbox Runtime you pair it with. gVisor and Kata Containers are separate projects with their own terms, and the README does not discuss them. This is not legal advice; check the licence of each component you deploy.

Upgrade cost is dominated by the CRDs rather than the controller image. The Makefile runs code generation for API docs and Go SDK docs, which tells you the API surface is generated and can shift between versions. The README recommends the combined manifest partly because it avoids declaring the controller twice, which is the failure mode to watch for if you install core and extensions with separate kubectl apply commands and later switch to the combined asset.

Frequently asked questions about agent-sandbox

The questions below come from search data about this project. Each answer is limited to what the repository states.

Editorial conclusion

Adopt agent-sandbox if you already run Kubernetes and need a single, stateful pod per agent with a stable hostname and persistent storage, and you have a Sandbox Runtime such as gVisor or Kata Containers available through RuntimeClass. Do not adopt it if you need a stateless replicated service (a Deployment fits better) or if you expect the project itself to provide container isolation, since the README states isolation is delegated to the runtime. Before rolling it out, verify that the Sandbox CRDs and the agent-sandbox-controller deployment are present, that your chosen RuntimeClass is installed on the nodes, and that you have a plan for the cascade deletion that occurs when the CRDs are removed.

Frequently asked questions

Official sources

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