Repolode
Submit
kubernetes-sigs

kubernetes-sigs/agent-sandbox

A Kubernetes controller and CRD for managing isolated, stateful, single-pod sandboxes, aimed at AI agent runtimes and RL workloads.

View on GitHubWebsite
Stars
4,534
Forks
607
Open issues
177
Last commit
yesterday

What is it?

agent-sandbox adds a Sandbox custom resource and controller to Kubernetes for running a long-lived, single-container workload with a stable hostname, network identity, and optional persistent storage. It fills a gap between Deployments, which are stateless and replicated, and StatefulSets, which manage numbered sets of pods. The project is developed under SIG Apps.

The optional extensions module adds SandboxTemplate for reusable sandbox definitions, SandboxWarmPool for keeping pre-warmed sandboxes ready to allocate, and SandboxClaim for requesting a sandbox from a pool without handling its full configuration. Sandbox pods can be configured to run under runtimes such as gVisor or Kata Containers through RuntimeClass, so the controller orchestrates while the runtime provides isolation.

The project also ships Go and Python SDKs and a Sandbox Router, an HTTP reverse proxy that forwards traffic from clients to sandbox pods. Installation is through kubectl manifests or Helm.

Key features

  • 01Sandbox CRD provides a single stateful pod with a stable hostname and network identity.
  • 02Persistent storage can survive pod restarts.
  • 03Lifecycle management covers creation, scheduled deletion, pausing and resuming.
  • 04SandboxWarmPool keeps pre-warmed sandboxes ready for quick allocation.
  • 05SandboxClaim requests sandboxes from a pool without managing their full configuration.
  • 06Works with gVisor or Kata Containers via RuntimeClass.
  • 07Go and Python SDKs are available.

Use cases

  • Running LLM-generated or untrusted code in isolated environments for AI agents.
  • Providing fast-start sandboxes for reinforcement learning and evaluation loops.
  • Hosting persistent cloud development environments or Jupyter-style sessions.
  • Running single-instance services that need a stable identity without StatefulSet overhead.

Quick start

  1. 1

    Install the core and extensions with kubectl (latest release)

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

    Verify the Sandbox CRD is installed

    kubectl get crd sandboxes.agents.x-k8s.io
  3. 3

    Apply a Sandbox manifest with your container image

Things to know

  • Requires a Kubernetes cluster with the agent-sandbox controller installed.
  • Sandbox isolation depends on a separate runtime such as gVisor or Kata Containers.

In collections

Sandboxes for AI agentsOpen-source AI agent frameworks & appsReinforcement learning frameworks & training environments

Topics

#kubernetes#ai-agent#sandbox#reinforcement-learning#controller#crd#isolation#gvisor#agent#ai

FAQ

What is agent-sandbox?
A Kubernetes controller and CRD for managing isolated, stateful, single-pod sandboxes, aimed at AI agent runtimes and RL workloads. agent-sandbox adds a Sandbox custom resource and controller to Kubernetes for running a long-lived, single-container workload with a stable hostname, network identity, and optional persistent storage. It fills a gap between Deployments, which are stateless and replicated, and StatefulSets, which manage numbered sets of pods. The project is developed under SIG Apps.
Is agent-sandbox free to use? What license does it have?
agent-sandbox is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is agent-sandbox still maintained?
Actively maintained. The last commit to agent-sandbox was on Nov 6, 2026.
What can I use agent-sandbox for?
Running LLM-generated or untrusted code in isolated environments for AI agents. Providing fast-start sandboxes for reinforcement learning and evaluation loops. Hosting persistent cloud development environments or Jupyter-style sessions. Running single-instance services that need a stable identity without StatefulSet overhead.
How do I install agent-sandbox?
Install the core and extensions with kubectl (latest release): kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/latest/download/sandbox-with-extensions.yaml Verify the Sandbox CRD is installed: kubectl get crd sandboxes.agents.x-k8s.io Apply a Sandbox manifest with your container image
Where can I get agent-sandbox?
The source code and installation instructions are on GitHub: https://github.com/kubernetes-sigs/agent-sandbox

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects