How it Works
Agent Sandbox is a Kubernetes controller and API designed to manage isolated, stateful, singleton workloads such as AI agent sandboxes and development environments. It operates under the Kubernetes Special Interest Group (SIG) Apps and is built to provide a declarative, standardized API for workloads requiring long-running, stateful, singleton containers with stable identities. This approach contrasts with traditional Kubernetes models like Deployments (stateless, replicated) or StatefulSets (stable, numbered sets of stateful pods).
The core of Agent Sandbox is the Sandbox Custom Resource Definition (CRD), which defines a declarative API for managing a single, stateful pod with persistent storage and a stable hostname. This pod is managed by the Sandbox controller, which handles its lifecycle—including creation, scheduled deletion, pausing, and resuming. The controller delegates low-level container isolation to secure runtimes like gVisor or Kata Containers, ensuring strong isolation between the sandbox and the host.
Agent Sandbox follows the Kubernetes controller pattern, where users create a Sandbox custom resource, and the controller manages the underlying runtime resources. This architecture ensures that users can define their desired sandbox configuration, and the controller handles the rest, including pod creation, runtime assignment, and lifecycle management.
The project extends its core functionality through additional CRDs and controllers, such as SandboxTemplate, SandboxClaim, and SandboxWarmPool. These extensions provide advanced features like reusable sandbox templates, pre-warmed sandbox pools for rapid allocation, and abstractions for managing underlying configurations without exposing low-level details to users.
The Sandbox CRD supports key features such as stable identity through a hostname and network identity, persistent storage that survives restarts, and lifecycle management for creation, deletion, pausing, and resuming. These features make Agent Sandbox suitable for workloads that require a lightweight, single-container VM experience built on Kubernetes primitives.
Agent Sandbox integrates with existing Kubernetes tooling, including RBAC, namespaces, network policies, and resource quotas. This ensures compatibility with standard cluster practices while providing specialized functionality for isolated, stateful workloads.
The architecture of Agent Sandbox is modular, allowing users to install either the core components or the full suite of extensions. The project also provides a Sandbox Router, an optional HTTP reverse proxy that routes traffic to sandbox pods, useful for workloads using the Go or Python SDKs or runtimes where direct pod port-forwarding is unavailable.
Verification of installation involves checking for the presence of CRDs and the controller deployment in the cluster. Uninstallation requires careful checks for in-use resources to avoid data loss, followed by the deletion of the installed manifests. Configuration options are available for advanced tuning of scale and concurrency, such as API QPS and worker counts.
Agent Sandbox is designed to be runtime-agnostic, supporting various isolation technologies like gVisor and Kata Containers. This flexibility allows users to select the isolation method that best fits their security, performance, and workload requirements. The project emphasizes interoperability, ensuring that the execution layer is decoupled from the underlying isolation technology.
The SandboxWarmPool extension pre-warms a pool of pods, enabling rapid allocation of sandboxes for interactive workloads and high-throughput agent pipelines. This reduces latency by eliminating the need to wait for cold pod scheduling and startup. Additionally, Agent Sandbox supports hibernation, where sandboxes can be paused to free compute resources while preserving state for seamless resumption upon network activity.
The project’s motivation stems from the need to manage workloads that do not fit neatly into the stateless or stateful models of Deployments and StatefulSets. These workloads include development environments, AI agent runtimes, reinforcement learning setups, notebooks, and stateful single-pod services. Agent Sandbox addresses these needs by providing a specialized abstraction that simplifies the management of such workloads while maintaining compatibility with Kubernetes primitives.
Agent Sandbox’s design goals include strong isolation, deep hibernation, automatic resume, efficient persistence, and memory sharing across sandboxes. These characteristics are achieved through the use of secure runtimes, persistent storage, and lifecycle management features. The project also aims to be vendor-neutral, supporting various runtimes and ensuring that users can choose the isolation method that best suits their requirements.
Use Cases
Agent Sandbox is particularly well-suited for managing isolated, stateful, singleton workloads that require a stable identity and persistent storage. One of its primary use cases is in AI agent runtimes, where it provides a secure and isolated execution layer for deploying autonomous AI agents that generate and run untrusted code at scale.
For AI agents, Agent Sandbox enables the execution of untrusted code in fully isolated environments, making it ideal for code interpreters, analytics tools, and on-demand computation. Autonomous agents can write, debug, and refactor code within secure sandboxes equipped with full development tooling. This isolation is crucial for high-risk applications such as stateful code interpretation, agentic web browsing, and complex data analysis tasks.
Another significant use case is in reinforcement learning (RL) and evaluation environments. Agent Sandbox supports high-throughput, isolated execution sandboxes for training and evaluation loops, such as those used in SWE-bench, R2E-Gym, and Ray/RLlib. The SandboxWarmPool extension ensures low-latency provisioning of sandboxes, which is essential for maintaining performance in RL workflows.
It provides isolated, persistent, and network-accessible cloud environments for developers, allowing them to maintain a stable workspace across sessions. This is particularly useful for teams working on complex projects where consistency and isolation are critical.
Agent Sandbox is also applicable to notebooks and research tools, offering persistent, single-container sessions for tools like Jupyter Notebooks. Researchers can maintain their work across sessions without needing to reinstall packages or reconfigure environments. Additionally, Agent Sandbox can host single-instance applications such as build agents or small databases that require a stable identity without the overhead of StatefulSets.
In CI/CD pipelines, Agent Sandbox can be integrated for isolated testing, validation, and automated workflows. This ensures that each stage of the pipeline operates in a controlled, isolated environment, reducing the risk of contamination or interference between stages. The ability to pause and resume sandboxes also allows for efficient resource management during idle periods.
For always-on agent environments, Agent Sandbox can be combined with tools like OpenClaw to provide persistent, long-running workloads. This setup is ideal for applications requiring continuous operation, such as monitoring agents or background services that need to maintain state over extended periods.
Agent Sandbox’s support for gVisor and Kata Containers enhances its security capabilities. gVisor provides kernel-level sandboxing by intercepting system calls, while Kata Containers offer VM-grade isolation with a dedicated kernel per sandbox. These isolation methods are particularly valuable for executing untrusted or LLM-generated code in multi-tenant clusters, ensuring that the host system remains protected from potential threats.
The project’s interoperability is a core feature, with a standardized Kubernetes API that decouples the execution layer from the underlying isolation technology. This abstraction allows users to select the isolation method that best aligns with their security, performance, and workload needs, ensuring flexibility and adaptability across different environments.
Key Features & Capabilities
The Sandbox CRD is the foundation of Agent Sandbox, providing a declarative API for managing a single, stateful pod with a stable hostname and persistent storage. This pod is designed to have a stable identity, which is essential for workloads requiring consistent network access and persistent state across restarts.
Persistent storage is a key feature of Agent Sandbox, allowing sandboxes to retain data and configurations even after restarts. This is particularly useful for workloads that require long-term state, such as development environments or AI agent runtimes. The persistent storage can be configured to survive restarts, ensuring that the sandbox remains functional and accessible across sessions.
The controller handles the entire lifecycle of the sandbox, including creation, scheduled deletion, pausing, and resuming. This ensures that sandboxes can be managed efficiently, with the ability to pause them during idle periods to free compute resources while preserving their state for future use.
The SandboxTemplate extension allows users to define reusable templates for creating sandboxes. This feature simplifies the management of large numbers of similar sandboxes, as users can apply a predefined template rather than configuring each sandbox individually.
SandboxClaim provides an abstraction layer for creating sandboxes from a SandboxWarmPool. This extension manages a pool of pre-warmed sandboxes, which can be quickly allocated to users upon request. This reduces the latency associated with provisioning new sandboxes, making it ideal for interactive workloads and high-throughput agent pipelines.
SandboxWarmPool is designed to pre-warm a pool of sandboxes, ensuring that they are ready for immediate use when requested. This feature is particularly beneficial for workloads requiring low-latency provisioning, such as reinforcement learning environments or interactive development sessions. By maintaining a pool of ready-to-use sandboxes, Agent Sandbox minimizes the time required to allocate new resources.
Agent Sandbox supports multiple isolation runtimes, including gVisor and Kata Containers. gVisor provides kernel-level isolation by intercepting system calls, while Kata Containers offer VM-grade isolation with a dedicated kernel per sandbox. This flexibility allows users to choose the isolation method that best fits their security and performance requirements.
The Sandbox Router is an optional component that acts as an HTTP reverse proxy, routing traffic from SDKs and external clients to sandbox pods. This is particularly useful for workloads using the Go or Python SDKs or runtimes where direct pod port-forwarding is unavailable. The router ensures that traffic is efficiently directed to the appropriate sandbox, improving accessibility and performance.
Agent Sandbox provides high-level client libraries in Go and Python, enabling programmatic management of sandboxes from applications and agents. These SDKs allow users to create, query, and manage sandboxes programmatically, integrating seamlessly with existing workflows and tools.
The project’s recent releases have introduced several enhancements, including Kubernetes lifecycle event reporting for sandboxes, streaming file download capabilities across SDKs, and support for asynchronous operations in the Python SDK.
This is particularly important for multi-tenant environments where isolation and security are paramount.
Agent Sandbox integrates with standard Kubernetes tooling, including RBAC, namespaces, network policies, and resource quotas. This ensures compatibility with existing cluster practices while providing specialized functionality for isolated, stateful workloads. The project’s design emphasizes interoperability and extensibility, allowing users to customize and adapt it to their specific needs.