agent-sandbox: Manage Isolated Stateful Workloads on Kubernetes

Overview

Agent Sandbox is a Kubernetes project for managing isolated, stateful workloads that run as single pods with stable identities. Its Sandbox custom resource and controller address workloads that do not fit neatly into stateless Deployments or the numbered replicas of StatefulSets.

The project orchestrates sandbox workloads rather than providing low-level container isolation itself. It can configure pods to use sandbox runtimes through Kubernetes RuntimeClass, and its optional extensions add reusable templates, claims, and warm pools.

Key Features

• Declarative Sandbox resources for managing a single workload pod.
• Stable hostname and network identity for each sandbox.
• Optional persistent storage that can survive restarts.
• Controller-managed lifecycle, including scheduled deletion, pausing, and resuming.
• Optional SandboxTemplate resources for reusable configurations.
• Optional SandboxClaim and SandboxWarmPool resources to allocate pre-warmed sandboxes.
• Go and Python SDKs for programmatic access, plus an optional HTTP Sandbox Router.
• Runtime integration through Kubernetes RuntimeClass, with runtimes such as gVisor or Kata Containers identified in the README.

Use Cases

• AI agent teams can provide isolated environments for running LLM-generated code, especially when workloads need persistent state and stable access.
• Reinforcement-learning and evaluation platform developers can use warm pools to reduce the setup delay when allocating sandboxes in repeated execution loops.
• Development-platform operators can offer persistent, network-accessible environments that behave like individual workspaces.
• Notebook and research-tool operators can manage single-container sessions that need a stable identity across restarts.
• Teams running singleton services, such as build agents or small databases, can use a dedicated workload abstraction instead of combining a size-one StatefulSet with supporting resources.

Project Facts

• Language: Go
• License: Apache-2.0
• Stars: 4.1k
• Forks: 541
• Topics: agent, ai, kubernetes, rl, sandbox
• Archived: false

Getting Started

Install the core controller and extensions on a Kubernetes cluster:

kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/latest/download/sandbox-with-extensions.yaml

For version-pinned installs, core-only installation, SDK setup, and usage details, see the repository README and Getting Started guide.

Alternatives

• agent-sandbox: It exposes sandbox lifecycle operations through a REST API and MCP server, while agent-sandbox provides Kubernetes APIs and controllers for stateful workloads.
• OpenSandbox: It offers a shared API for isolated code, command, and browser environments, rather than Kubernetes-native controllers for stable, persistent workloads.

Considerations

• Agent Sandbox is an orchestrator, not a sandbox runtime. Isolation depends on the runtime and pod configuration selected by the operator.
• It requires a Kubernetes cluster where its controller and custom resource definitions can be installed.
• Extensions are optional and add their own custom resources and controllers; install them only if templates, claims, or warm pools are needed.
• Deleting the custom resource definitions cascade-deletes resources of those types, so review existing sandboxes and extension resources before uninstalling.
• The project describes deep hibernation and other advanced sandbox characteristics as goals or areas being explored, so do not assume every desired capability is currently available.