<div align="center">
<img src="site/assets/icons/color_logo.svg" alt="Agent Sandbox logo" width="150" />
<h1>Agent Sandbox</h1>
</div>
<p>
<a href="https://github.com/kubernetes-sigs/agent-sandbox/releases"><img src="https://img.shields.io/github/v/release/kubernetes-sigs/agent-sandbox" alt="GitHub release"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/Apache-2-blue.svg" alt="Apache-2.0 license"></a>
</p>
[Website](https://agent-sandbox.sigs.k8s.io) · [Docs](https://agent-sandbox.sigs.k8s.io/docs/) · [DeepWiki](https://deepwiki.com/kubernetes-sigs/agent-sandbox) · [Getting Started](https://agent-sandbox.sigs.k8s.io/docs/getting_started/) · [Examples](examples/) · [Roadmap](roadmap.md)
**agent-sandbox enables easy management of isolated, stateful, singleton workloads, ideal for use cases like AI agent runtimes and reinforcement learning.**
This project is developing a `Sandbox` Custom Resource Definition (CRD) and controller for Kubernetes, under the umbrella of [SIG Apps](https://github.com/kubernetes/community/tree/master/sig-apps). The goal is to provide a declarative, standardized API for managing workloads that require the characteristics of a long-running, stateful, singleton container with a stable identity, much like a lightweight, single-container VM experience built on Kubernetes primitives.
> [!NOTE]
> **Scope:** Agent Sandbox is a *sandbox orchestrator*. It delegates low-level container isolation to secure "Sandbox Runtimes" (like gVisor or Kata Containers) by managing Pods configured to use these runtimes (via `RuntimeClass`).
## Overview
### Core: Sandbox
The `Sandbox` CRD is the core of agent-sandbox. It provides a declarative API for managing a single, stateful pod with a stable identity and persistent storage. This is useful for workloads that don't fit well into the stateless, replicated model of Deployments or the numbered, stable model of StatefulSets.
Key features of the `Sandbox` CRD include:
* **Stable Identity:** Each Sandbox has a stable hostname and network identity.
* **Persistent Storage:** Sandboxes can be configured with persistent storage that survives restarts.
* **Lifecycle Management:** The Sandbox controller manages the lifecycle of the pod, including creation, scheduled deletion, pausing and resuming.
### Extensions
The `extensions` module provides additional CRDs and controllers that build on the core `Sandbox` API to provide more advanced features.
* `SandboxTemplate`: Provides a way to define reusable templates for creating Sandboxes, making it easier to manage large numbers of similar Sandboxes.
* `SandboxClaim`: Allows users to create Sandboxes from a `SandboxWarmPool`, abstracting away the details of the underlying Sandbox configuration. See [SandboxClaim identity on Pods](https://github.com/kubernetes-sigs/agent-sandbox/blob/main/docs/configuration.md#sandboxclaim-identity-on-pods) for the Claim name and UID metadata exposed to external services.
* `SandboxWarmPool`: Manages a pool of pre-warmed Sandboxes that can be quickly allocated to users, reducing the time it takes to get a new Sandbox up and running.
## Architecture
agent-sandbox follows the Kubernetes controller pattern. Users create a Sandbox custom resource, and the controller manages the underlying runtime resources.
### Architecture Diagram
```mermaid
flowchart LR
User[User]
Claim[SandboxClaim]
Template[SandboxTemplate]
Sandbox[Sandbox]
Pod[Pod]
Runtime[Sandbox Runtime]
WarmPool[SandboxWarmPool]
subgraph Extensions[Extensions]
Claim
Template
WarmPool
end
%% User paths
User -->|creates| Sandbox
User -->|creates| Claim
%% Claim workflow
WarmPool -->|references| Template
Claim -->|adopts| Sandbox
%% Pod handling
Claim -->|adopts sandboxes from| WarmPool
Sandbox -->|creates Pod| Pod
%% Runtime
Pod --> Runtime
%% Warm pool
WarmPool -->|pre-warms sandboxes| Sandbox
```
## Installation
Agent Sandbox requires Kubernetes **1.25 or later** with [CRD CEL validation rules](https://kubernetes.io/blog/2022/09/23/crd-validation-rules-beta/) enabled. On Kubernetes 1.25 through 1.28, keep the `CustomResourceValidationExpressions` feature gate enabled. If the gate is disabled when CRDs are installed, the API server drops the CEL rules. Sandbox name validation and volume claim template immutability are then not enforced.
**Kubernetes 1.29 or later is recommended** because CRD CEL validation is stable and cannot be disabled.
Gateway-based client connections must also meet the Kubernetes version requirements of the installed Gateway API CRDs and controller. The full [Gateway API v1.5.0 CRD bundle](https://github.com/kubernetes-sigs/gateway-api/releases/tag/v1.5.0) requires **Kubernetes 1.31 or later** because of its TLSRoute CEL validation.
Each release is built against the latest Kubernetes libraries and tested with the newest Kubernetes release. Intermediate versions are expected to work but are not regularly tested.
### Standard Install (Core + Extensions)
Recommended for most users:
```sh
# Quick install (latest release):
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/latest/download/sandbox-with-extensions.yaml
# Or pin to a specific version (recommended 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 it directly from source with `kubectl kustomize k8s/`.
### Selective Install
If you prefer to install components separately:
```sh
# Core only:
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/latest/download/sandbox.yaml
# Extensions (opt-in):
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/latest/download/extensions.yaml
# To pin to a specific version, replace "latest/download" with "download/<version>".
```
### Go SDK
To interact with the agent-sandbox programmatically from Go, use the Go SDK:
```sh
go get sigs.k8s.io/agent-sandbox/clients/go/sandbox@latest
```
The Go SDK currently ships from the repository's root Go module, so repository release tags such as `v0.1.0` are also the Go SDK versions.
For detailed installation and usage instructions, please refer to the [Go SDK README](clients/go/README.md).
### Python SDK
To interact with the agent-sandbox programmatically from Python, use the Python SDK:
```sh
pip install k8s-agent-sandbox
```
For detailed installation and usage instructions, please refer to the [Python SDK README](clients/python/agentic-sandbox-client/README.md).
### Sandbox Router (Optional)
The [Sandbox Router](sandbox-router/) is an HTTP reverse proxy that routes traffic from SDKs and external clients to sandbox pods. It is useful for workloads using the Go or Python SDKs, or runtime environments (like Kata Containers and gVisor) where direct pod port-forwarding is unavailable.
For deployment manifests and setup options, see [sandbox-router/deploy/](sandbox-router/deploy/).
### Verify Installation
To check whether agent-sandbox is already installed on your cluster:
```sh
# Check for agent-sandbox CRDs
kubectl get crd sandboxes.agents.x-k8s.io
# Check for the controller deployment
kubectl get deploy agent-sandbox-controller -n agent-sandbox-system
```
If the CRDs and controller deployment are present, agent-sandbox is installed.
### Uninstallation
Before uninstalling, check for any in-use resources to avoid unexpected data loss:
```sh
# Check for existing Sandbox resources across all namespaces
kubectl get sandboxes -A
# Extensions (only if installed):
kubectl get crd sandboxclaims.extensions.agents.x-k8s.io >/dev/null 2>&1 && kubectl get sandboxclaims -A
kubectl get crd sandboxwarmpools.extensions.agents.x-k8s.io >/dev/null 2>&1 && kubectl get sandboxwarmpools -A
kubectl get crd sandboxtemplates.extensions.agents.x-k8s.io >/dev/null 2>&1 && kubectl get sandboxtemplates -A
```
> **Warning**: Deleting the CRDs will **cascade-delete all custom resources** of those types across all namespaces.
Once you have confirmed no resources are in use (or you are prepared to lose them), uninstall by deleting the manifest for the version installed on your cluster:
```sh
# Set the version installed on your cluster (e.g., "v1.0.2"):
export VERSION="v1.0.2"
# Standard Install:
kubectl delete -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/sandbox-with-extensions.yaml
# Or, if you used the Selective Install:
kubectl delete -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/extensions.yaml
kubectl delete -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/sandbox.yaml
```
For Helm-based installations, see the [Helm chart README](helm/README.md#uninstallation).
## Configuration & Performance Tuning
For controller flags, high-throughput benchmark profiles, warm-pool refill shaping, and API Priority and Fairness (APF) insulation, see:
* [Configuration Guide](docs/configuration.md) — full CLI flag reference and deployment examples.
* [Performance Tuning Guide](docs/performance-tuning.md) — benchmark data, burst vs. sustained profiles, multi-pool sharding, and managed control-plane checklist.
* [APF Insulation Guide](docs/apf-insulation.md) — `FlowSchema` and `PriorityLevelConfiguration` manifests to protect claim adoption from bulk refill traffic.
## Getting Started
Once you have installed the controller, you can create a simple Sandbox by applying the following YAML to your cluster:
```yaml
apiVersion: agents.x-k8s.io/v1beta1
kind: Sandbox
metadata:
name: my-sandbox
spec:
podTemplate:
spec:
containers:
- name: my-container
image: <IMAGE>
```
This will create a new Sandbox named `my-sandbox` running the image you specify. You can then access the Sandbox using its stable hostname, `my-sandbox`.
For more complex examples, including how to use the extensions, please see the [examples/](examples/) directory.
## Motivation
Kubernetes excels at managing stateless, replicated applications (Deployments) and stable, numbered sets of stateful pods (StatefulSets). However, there's a growing need for an abstraction to handle use cases such as:
* **Development Environments:** Isolated, persistent, network-accessible cloud environments for developers.
* **AI Agent Runtimes:** Isolated environments for executing untrusted, LLM-generated code.
* **Reinforcement Learning (RL) & Evaluation:** High-throughput, isolated execution sandboxes for training and evaluation loops (e.g., SWE-bench, R2E-Gym, Ray/RLlib) with low-latency warm-pool claims.
* **Notebooks and Research Tools:** Persistent, single-container sessions for tools like Jupyter Notebooks.
* **Stateful Single-Pod Services:** Hosting single-instance applications (e.g., build agents, small databases) needing a stable identity without StatefulSet overhead.
While these can be approximated by combining StatefulSets (size 1), Services, and PersistentVolumeClaims, this approach is cumbersome and lacks specialized lifecycle management like hibernation.
## Desired Sandbox Characteristics
We aim for the Sandbox to be vendor-neutral, supporting various runtimes. Key characteristics include:
* **Strong Isolation:** Supporting different runtimes like gVisor or Kata Containers to provide enhanced security and isolation between the sandbox and the host, including both kernel and network isolation. This is crucial for running untrusted code or multi-tenant scenarios.
* **Deep hibernation:** Saving state to persistent storage and potentially archiving the Sandbox object.
* **Automatic resume:** Resuming a sandbox on network connection.
* **Efficient persistence:** Elastic and rapidly provisioned storage.
* **Memory sharing across sandboxes:** Exploring possibilities to share memory across Sandboxes on the same host, even if they are primarily non-homogeneous. This capability is a feature of the specific runtime, and users should select a runtime that aligns with their security and performance requirements.
* **Rich identity & connectivity:** Exploring dual user/sandbox identities and efficient traffic routing without per-sandbox Services.
* **Programmable:** Encouraging applications and agents to programmatically consume the Sandbox API.
## Roadmap
The current Roadmap can be found at [roadmap.md](roadmap.md).
## Security
For information on the security model, trust boundaries, and mitigations of Agent Sandbox, please refer to the [Threat Model](docs/security/threat_model.md).
## Community, Discussion, Contribution, and Support
This is a community-driven effort, and we welcome collaboration!
**Note on PR Velocity:** To maintain high velocity and keep our queues clean, this project uses stale PR management (30-day auto-stale and 15-day auto-close for inactive PRs) and allows maintainers to fast-track or take over approved community PRs. Please read our [Contributing Guidelines](CONTRIBUTING.md) for our full code review and PR policies.
### AI-Assisted Code Reviews (Experimental)
To help improve our review velocity, we are currently experimenting with AI-assisted code reviews using CodeRabbit as our automated first-pass reviewer. Here is the workflow:
1. CodeRabbit will automatically review open PRs (skipping draft PRs and PRs without a signed CLA).
* **⚠️ Important Contribution Note (CLA Requirement):** If you receive a code suggestion from CodeRabbit in your PR, please don't directly apply suggestions via the GitHub UI. It will set the AI bot as co-author and break the Kubernetes CLA requirements. For more information, read our [Contributing Guidelines](CONTRIBUTING.md).
1. **Interacting with CodeRabbit:** CodeRabbit provides high-level summaries and walkthroughs, and acts as an automated gatekeeper that approves the PR once all issues are resolved. You can interact with it by commenting `@coderabbitai` on your PR (e.g., `@coderabbitai review` to request an incremental re-review, or `@coderabbitai full review` to re-evaluate the entire PR from scratch).
1. After automated review comments are addressed or marked resolved, maintainers will review the PR and provide final approval.
We actively welcome your feedback on the quality, relevance, and helpfulness of these automated reviews! As we iterate on this process, we also plan to evaluate and test different AI review tools to find the best fit for our project's workflow.
### Contact Us
Learn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/).
You can reach the maintainers of this project at:
- [#agent-sandbox Slack channel](https://kubernetes.slack.com/messages/agent-sandbox)
- If it's your first time joining the Kubernetes Slack, visit https://slack.k8s.io/ to get an invitation.
- Log in to [Kubernetes Slack](https://kubernetes.slack.com/) first before joining the channel.
- [#sig-apps Slack channel](https://kubernetes.slack.com/messages/sig-apps) for general sig-apps discussions
- [SIG Apps Mailing List](https://groups.google.com/a/kubernetes.io/g/sig-apps)
Please feel free to open issues, suggest features, and contribute code!
### Code of conduct
Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md).
[owners]: https://git.k8s.io/community/contributors/guide/owners.md
[Creative Commons 4.0]: https://git.k8s.io/website/LICENSE