Agent Sandbox
github.com/kubernetes-sigs/agent-sandbox- Category
- Developer Tools
- Rank
- No. 307Tools index
- Pricing
- Open Source
- Type
- TOOL
- Use case
- Deployment & Operations
- Interfaces
- API
- Builder
- @gakonst
- GitHub
- 4.4k stars
- Latest release
- v1.0.7
- Date
About
A Kubernetes controller for managing isolated, stateful, singleton workloads designed for AI agent runtimes. Provides a declarative API for creating lightweight, single-container VM-like experiences with stable identities and persistent storage.
What it does
This project adds a custom resource to Kubernetes that keeps one pod running with a fixed hostname and durable disk, instead of the usual pattern of scaling a swappable fleet. A companion controller watches that resource and recreates the pod if it dies, while extension controllers let teams pre-warm a pool of ready environments and hand them out to callers on demand. The intended use is running an agent's untrusted code or a long research session that needs the same address and files across restarts.
Why it's ranked here
This lives inside the official Kubernetes SIG Apps effort, so it inherits the review and merge discipline of the wider Kubernetes project rather than being a solo experiment. The code targets real operational failure modes: watch stream starvation under bursty writes, API server throttling during large pool refills, and metadata write volume at scale, each with a documented flag to address it. Apache licensed, with Go and Python client libraries and a dedicated routing proxy, it reads as infrastructure built for production agent workloads rather than a demo.
What's good
The warm pool extension is the standout: a controller can pre-create a batch of ready environments and hand them out on claim, with pacing controls so refill does not overwhelm the API server. Defaults lean toward safety, service account tokens are off unless asked for, and the informer cache can be scoped to just the objects the controller created, cutting memory use on busy clusters. The router component binds every listener before declaring itself ready, avoiding a startup window where traffic arrives at a socket that is not yet listening.
Tradeoffs
Isolation is not actually implemented here: the controller only configures pods to use a separate runtime like gVisor or Kata Containers, so the security boundary depends entirely on a component this project does not ship. Running it means operating a full Kubernetes cluster, a controller, and optionally a reverse proxy and a per-sandbox execution daemon, which is considerably more infrastructure than a single VM or container for a lone developer. The large set of concurrency and pacing flags exists because the defaults struggle at high claim rates, so getting good throughput needs deliberate tuning, not just installing the manifest.
How to use it well
This fits a team that already runs Kubernetes and needs many short-lived, isolated execution environments handed out quickly, such as an evaluation harness or a fleet of coding agents. Reach for the warm pool and claim extensions when handout latency matters, and pick the SDK, Go or Python, that matches your calling service. It is the wrong tool for a single developer who wants one throwaway sandbox on a laptop, or for anyone who needs isolation guarantees without also picking and configuring a real sandboxing runtime.
Technical notes+
The controller entry point in cmd/agent-sandbox-controller/main.go exposes the tuning surface as flags (worker counts per controller, kube-api-qps/burst, api-connections, cache-label-selectors, sandbox-write-behind-window), and controllers/sandbox_controller.go backs the caching flag with a PodCacheTransform that strips managedFields, finalizers, and most of the pod spec from cached Pod objects before they are stored, plus ownership checks (checkOwnership, sandboxOwnedPods) and a WriteBehindWindow field that coalesces recoverable metadata patches. go.mod confirms the module builds on controller-runtime, client-go, Prometheus's client_golang, and OpenTelemetry's otel/sdk, with testify and goleak for tests. The Dockerfile does a multi-stage build, compiling a static Go binary and copying it onto a distroless nonroot base image. sandbox-router/server/server.go runs four HTTP listeners (plain proxy, TLS proxy, metrics, health) that are all bound synchronously before probes.MarkReady is called, and shut down concurrently under one shared timeout. packages/sandboxd/pkg/server/server.go implements the sandboxd daemon as a gRPC ProcessService plus a REST filesystem service sharing one process registry, with ShutdownProcesses sending SIGTERM followed by SIGKILL after a fixed grace period.
Observed
- License
- Apache-2.0.
- Language
- Written in Go; also publishes a separate Go SDK package and a separate Python SDK package.
- Deployment
- Installed onto a cluster via Kubernetes manifests (kubectl apply) or a Helm chart; the controller binary ships in a distroless, nonroot container image.
- Interfaces
- Provides multiple interaction surfaces: the Sandbox custom resource and controller, a Go client library, a Python client library, and an optional HTTP reverse proxy (Sandbox Router) for SDK traffic.
- Architecture
- A separate daemon (sandboxd) exposes a gRPC process-execution API alongside a REST filesystem and health API, run as its own component rather than inside the controller.
- Isolation model
- Isolation strength is delegated to a pluggable Kubernetes RuntimeClass (for example gVisor or Kata Containers); the project's own code manages Pod lifecycle, not the sandbox boundary itself.
- Configuration surface
- The controller's command-line surface includes explicit knobs for API connection sharding, client-side rate limiting, and cache scoping, reflecting a design meant to be tuned per cluster rather than run only with defaults.
Read from README.md, go.mod, Dockerfile, Makefile, cmd/agent-sandbox-controller/main.go, controllers/sandbox_controller.go, docs/api.md, docs/development.md, docs/configuration.md, sandbox-router/server/server.go, packages/sandboxd/pkg/server/server.go.
What it can do
Create isolated sandbox environments for AI agents
Sandbox CRD configuration → Isolated Kubernetes workload with stable identity
Manage stateful singleton workloads
Workload specifications and configuration → Running singleton container with guaranteed single instance
Provision persistent storage for sandboxes
Storage requirements and configuration → Persistent volumes attached to sandbox workloads
Maintain stable identities across container restarts
Container restart events → Consistent sandbox identity and network configuration
Deploy single-container VM-like experiences
Container image and runtime specifications → Lightweight VM-equivalent environment in Kubernetes
Control sandbox lifecycle through declarative API
YAML/JSON sandbox definitions → Created, updated, or deleted sandbox resources
Intel on Agent Sandbox
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.