agent-sandbox enables easy management of isolated, stateful, singleton workloads, ideal for use cases like AI agent runtimes.
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.
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.
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 template, abstracting away the details of the underlying Sandbox configuration.SandboxWarmPool: Manages a pool of pre-warmed Sandbox Pods that can be quickly allocated to users, reducing the time it takes to get a new Sandbox up and running.
- launch k3s cluster and deploy agent-sandbox:
make launch-sandbox - test the sandbox:
make test-sandbox - cleanup:
make cleanup-sandbox