# Agent Sandbox: Managing Isolated, Stateful Workloads on Kubernetes This repository profile is provided by osrepos.com, an open source repository discovery platform. Source: osrepos.com Repository profile: https://osrepos.com/repo/kubernetes-sigs-agent-sandbox Generated for open source discovery and AI-assisted research. Agent Sandbox introduces a Sandbox Custom Resource Definition (CRD) and controller for Kubernetes, designed to simplify the management of isolated, stateful, singleton workloads. It provides a declarative API for use cases such as AI agent runtimes, development environments, and persistent single-container sessions. This project aims to offer a lightweight, single-container VM experience built on Kubernetes primitives. GitHub: https://github.com/kubernetes-sigs/agent-sandbox OSRepos URL: https://osrepos.com/repo/kubernetes-sigs-agent-sandbox ## Summary Agent Sandbox introduces a Sandbox Custom Resource Definition (CRD) and controller for Kubernetes, designed to simplify the management of isolated, stateful, singleton workloads. It provides a declarative API for use cases such as AI agent runtimes, development environments, and persistent single-container sessions. This project aims to offer a lightweight, single-container VM experience built on Kubernetes primitives. ## Topics - kubernetes - ai-agents - workload-management - crd - go - container-orchestration - stateful-workloads - isolation ## Repository Information Last analyzed by OSRepos: Sat Aug 08 2026 13:36:53 GMT+0100 (Western European Summer Time) Detail views: 1 GitHub clicks: 0 ## Safety Notice OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything. ## Content ### Introduction Agent Sandbox is a Kubernetes project that introduces a `Sandbox` Custom Resource Definition (CRD) and controller, designed to simplify the management of isolated, stateful, singleton workloads. It provides a declarative, standardized API for applications requiring the characteristics of a long-running, stateful, single-container environment, much like a lightweight, single-container VM experience built on Kubernetes primitives. This makes it ideal for use cases such as AI agent runtimes, development environments, and persistent single-container sessions. The core of Agent Sandbox is the `Sandbox` CRD, which offers: * **Stable Identity**: Each Sandbox maintains a stable hostname and network identity. * **Persistent Storage**: Sandboxes can be configured with persistent storage that survives restarts. * **Lifecycle Management**: The controller manages the pod's lifecycle, including creation, scheduled deletion, pausing, and resuming. Beyond the core, Agent Sandbox provides extensions like `SandboxTemplate` for reusable configurations, `SandboxClaim` for abstracting Sandbox allocation from a warm pool, and `SandboxWarmPool` for managing pre-warmed Sandboxes, enhancing scalability and user experience. ### Installation To install Agent Sandbox, including its core components and extensions, you can use the standard installation method. This approach is recommended for most users and GitOps engines like Argo CD, Config Sync, or kustomize. First, set the `VERSION` environment variable to a specific release tag from the [Agent Sandbox releases page](https://github.com/kubernetes-sigs/agent-sandbox/releases "Agent Sandbox Releases" target="_blank"): sh export VERSION="vX.Y.Z" Then, apply the combined manifest: sh kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/sandbox-with-extensions.yaml You can also render the manifest directly from source using `kubectl kustomize k8s/`. For selective installations of core or extensions separately, refer to the official documentation. ### Examples Once the controller is installed, you can create a simple Sandbox by applying a YAML manifest to your cluster. This example demonstrates how to deploy a basic Sandbox running a specified container image: yaml apiVersion: agents.x-k8s.io/v1beta1 kind: Sandbox metadata: name: my-sandbox spec: podTemplate: spec: containers: - name: my-container image: Replace `` with your desired container image. This will create a new Sandbox named `my-sandbox`. You can then access this Sandbox using its stable hostname, `my-sandbox`. For more complex scenarios and examples utilizing the extensions, consult the project's `examples/` directories. ### Why use it Kubernetes is highly effective for managing stateless, replicated applications via Deployments and stable, numbered sets of stateful pods using StatefulSets. However, there's a growing demand for an abstraction that specifically addresses use cases requiring isolated, persistent, and single-instance environments. Agent Sandbox fills this gap by providing a tailored solution for: * **Development Environments**: Offering isolated, persistent, and network-accessible cloud environments for developers. * **AI Agent Runtimes**: Creating secure, isolated environments for executing untrusted, LLM-generated code. * **Notebooks and Research Tools**: Providing persistent, single-container sessions for tools like Jupyter Notebooks. * **Stateful Single-Pod Services**: Hosting single-instance applications, such as build agents or small databases, that need a stable identity without the overhead of a full StatefulSet. Agent Sandbox aims for vendor-neutrality and supports various runtimes, offering key characteristics such as: * **Strong Isolation**: Supporting runtimes like gVisor or Kata Containers for enhanced security and isolation. * **Deep Hibernation**: The ability to save state to persistent storage and potentially archive the Sandbox object. * **Automatic Resume**: Resuming a sandbox automatically upon network connection. * **Efficient Persistence**: Providing elastic and rapidly provisioned storage. * **Programmable API**: Encouraging applications and agents to programmatically consume the Sandbox API. ### Links * **Website**: [https://agent-sandbox.sigs.k8s.io](https://agent-sandbox.sigs.k8s.io "Agent Sandbox Website" target="_blank") * **Documentation**: [https://agent-sandbox.sigs.k8s.io/docs/](https://agent-sandbox.sigs.k8s.io/docs/ "Agent Sandbox Documentation" target="_blank") * **GitHub Repository**: [https://github.com/kubernetes-sigs/agent-sandbox](https://github.com/kubernetes-sigs/agent-sandbox "Agent Sandbox GitHub Repository" target="_blank")