Agent Sandbox: Managing Isolated, Stateful Workloads on Kubernetes

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:

export VERSION="vX.Y.Z"

Then, apply the combined manifest:

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:

apiVersion: agents.x-k8s.io/v1beta1
kind: Sandbox
metadata:
  name: my-sandbox
spec:
  podTemplate:
    spec:
      containers:
      - name: my-container
        image: <IMAGE>

Replace <IMAGE> 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.