kubernetes-sigs / agent-sandbox

Agent Sandbox 
Website · Docs · DeepWiki · Getting Started · Examples · Roadmap
**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. 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.
* `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
 [code] 
## Installation
### Standard Install (Core + Extensions)
Recommended for most users:
 [code] 
You can also render it directly from source with `kubectl kustomize k8s/`.
### Selective Install
If you prefer to install components separately:
 [code] 
### Go SDK
To interact with the agent-sandbox programmatically from Go, use the Go SDK:
 [code] 
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.
### Python