agent-sandbox is an open source project under Kubernetes SIG Apps. Its goal is to provide a declarative, standardized management API for container workloads that need to run for a long time, are stateful, single-instance, and have a stable identity, delivering a user experience similar to a lightweight single-container virtual machine.
Purpose and background Kubernetes excels at managing stateless replicated applications (Deployments) and collections of stateful Pods with stable ordinals (StatefulSets), but it lacks a dedicated abstraction for the following scenarios: development environments (isolated, persistent, network-accessible cloud environments); AI agent runtimes (executing untrusted LLM-generated code); reinforcement learning and evaluation (high-throughput, isolated execution sandboxes such as SWE-bench, R2E-Gym, Ray/RLlib, with support for low-latency warm pool declaration); notebooks and research tools (persistent single-container sessions such as Jupyter Notebook); stateful single-Pod services (such as build agents and small databases), etc. Although this can be approximated using a combination of a StatefulSet (with replicas set to 1), a Service, and a PersistentVolumeClaim, that approach is cumbersome and lacks dedicated lifecycle management such as hibernation.
Main capabilities At its core is the Sandbox CRD, which provides a declarative API for a single stateful Pod. Key features include: stable identity—each Sandbox has a stable hostname and network identity; persistent storage—configurable persistent storage that remains after restarts; lifecycle management—the controller manages the Pod's lifecycle, including creation, scheduled deletion, pause, and resume. Extension modules provide more advanced capabilities on top of the core API: SandboxTemplate defines reusable Sandbox templates, making it easier to manage large numbers of similar Sandboxes; SandboxClaim allows users to create Sandboxes from a SandboxWarmPool, hiding the underlying configuration details; SandboxWarmPool manages a pool of pre-warmed Sandboxes that can be allocated quickly to shorten the time for a new Sandbox to become ready. The project is positioned as a sandbox orchestrator, delegating underlying container isolation to secure sandbox runtimes (such as gVisor or Kata Containers), and managing Pods that use these runtimes through RuntimeClass.
Architecture and usage agent-sandbox follows the Kubernetes controller pattern: users create the Sandbox custom resource, and the controller manages the underlying runtime resources. Installation methods include: standard installation (core + extensions, recommended for most users), or rendering directly from source with kubectl kustomize k8s/; selective installation allows installing components separately; for Helm installation, see the Helm chart README. Creating a simple Sandbox only requires applying a piece of YAML to the cluster (specifying the image), after which it can be accessed via the stable hostname my-sandbox; for more complex examples, see the examples/ directory. The programming interface provides a Go SDK (released with the repository root Go module; repository tags such as v0.1.0 are the SDK version, see the Go SDK README for details) and a Python SDK (see the Python SDK README for details). The optional Sandbox Router is an HTTP reverse proxy that routes traffic from SDKs and external clients to sandbox Pods, suitable for runtime environments that use the Go/Python SDK or cannot directly port-forward Pods. To verify the installation, check whether the CRD and controller deployment exist; before uninstalling, check for in-use resources to avoid data loss, and deleting the CRD will cascade-delete custom resources of the corresponding type across all namespaces. For configuration and performance tuning, refer to the Configuration Guide (CLI parameters and deployment examples), Performance Tuning Guide (benchmark data, burst and sustained configurations, multi-pool sharding, managed control plane manifests), and APF Insulation Guide (FlowSchema and PriorityLevelConfiguration manifests).
Use cases Development environments, AI agent runtimes, reinforcement learning and evaluation, notebooks and research tools, stateful single-Pod services. Desired sandbox features include: strong isolation (supports gVisor, Kata Containers, etc., including kernel and network isolation, suitable for untrusted code and multi-tenancy), deep sleep (state saved to persistent storage and possibly archiving the Sandbox object), automatic recovery (restoring the sandbox when network connectivity is available), efficient persistence (elastic, fast-provisioned storage), cross-sandbox memory sharing (under exploration, depending on the specific runtime), rich identity and connectivity (exploring dual user/sandbox identities and noefficient traffic routing requiring per-sandbox Services), programmability (encouraging applications and agents to use the Sandbox API programmatically).
Limitations and notes The project is still under development; see roadmap.md for the roadmap; see the Threat Model for the security model, trust boundaries, and mitigations. The project uses stale PR management (automatically marked stale after 30 days, automatically closed after 15 days of inactivity), and experimentally uses CodeRabbit for AI-assisted code review; submitted suggestions should not be applied directly through the GitHub UI, to avoid breaking Kubernetes CLA requirements. Community channels include the #agent-sandbox and #sig-apps Slack channels and the SIG Apps mailing list; participation is governed by the Kubernetes Code of Conduct.
More details regarding fees, pricing, and platform support are not yet available.
