agent-sandbox

module

v0.0.1 Latest Latest Go to latest Published: May 10, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/scitix/agent-sandbox

Links

Open Source Insights

README ¶

Agent Sandbox

Kubernetes-native Sandbox Engine for AI Agents

Overview

Agent Sandbox is a Kubernetes Operator that manages AI agent sandbox Pod lifecycles using a pre-warmed Pod pool with in-place image upgrades. Instead of scheduling a new Pod for every sandbox request — which incurs 15–60 seconds of cold-start latency — Agent Sandbox pre-warms a pool of idle Pods and reassigns one to an incoming request in under 100ms.

It is purpose-built for workloads where sandbox allocation speed is critical:

Reinforcement learning training pipelines (SWE-bench, Terminal-bench, and custom RL environments)
AI coding agents that need on-demand isolated execution environments
Multi-agent systems requiring dozens or hundreds of sandboxes simultaneously

Key Features

Feature	Description
< 100ms Allocation	Pre-warmed Pod pool eliminates scheduling overhead; sandboxes are ready in milliseconds
In-Place Image Upgrade	Running Pods are updated with a new image without recreation, preserving pool warmth
Cross-Cluster & Multi-Region	ExtProc-based routing dispatches requests transparently across multiple clusters
E2B SDK Compatible	Drop-in replacement for the E2B API — existing E2B clients work without code changes
Optimized for RL Training	Purpose-built for SWE-bench, Terminal-bench, and large-scale RL environment rollouts
Kubernetes Native	Managed via CRDs (`SandboxPool`, `SandboxTemplate`); integrates with RBAC, namespaces, and autoscaling
Any Image, No Rebuild	Bring any container image; no custom base image or agent installation required
Prometheus Metrics	First-class observability with a Prometheus endpoint and pre-built Grafana dashboards

Architecture

Components

Binary	Purpose	Ports
`cmd/sandbox`	Operator + REST API Server	`:8080` (API), `:8090` (E2B-compat), `:8082` (metrics)
`cmd/envoyextproc`	Data-plane ExtProc for cross-cluster routing	`:9002` (gRPC), `:9003` (control-plane)
`cmd/wsproxy`	WebSocket reverse-proxy sidecar for terminal access	`:9003` (WS), `:9004` (sync)

CRDs

SandboxPool (sbp, namespace-scoped) — defines a pre-warmed Pod pool with Replicas, optional autoscaling, and an inline or referenced template
SandboxTemplate (sbt, cluster-scoped) — reusable Pod template with idleImage and runtimes

Performance

Metric	Traditional Kubernetes	Agent Sandbox
Sandbox allocation latency	15–60 s	< 100 ms
Pod churn per request	1 create + 1 delete	0 (pool reuse)
Image pull on every request	Yes (cold start)	No (pre-warmed)
Autoscaling to zero	Supported	Supported
Cross-cluster routing	Manual / external LB	Built-in ExtProc

Quick Start

Prerequisites

Kubernetes 1.26+
kubectl configured against your cluster
helm (optional, for chart-based install)

Use Cases

Reinforcement Learning (SWE-bench / Terminal-bench)

Agent Sandbox is designed to serve as the environment backend for large-scale RL training runs. Thousands of rollout workers can each request a fresh isolated sandbox in milliseconds, dramatically reducing the environment-reset bottleneck:

Cross-Cluster Scheduling

Deploy sandbox pools across multiple clusters or regions. The ExtProc component routes API requests to the appropriate cluster transparently — no changes needed in client code:

Development

Prerequisites

Go 1.25+
make
Docker (for image builds)
controller-gen, oapi-codegen (installed automatically by make)

Build

# Build all binaries
make build

# Build individual binaries
make build-controller   # sandbox operator + API server (linux/amd64)
make build-extproc      # envoy extproc (linux/amd64)
make build-wsproxy      # websocket proxy

Code Generation

make manifests          # Regenerate CRD YAML + RBAC
make generate           # Regenerate DeepCopy methods
make gen-all-api        # openapi.yaml → Go + TypeScript + Python SDK
make sync-crds-to-helm  # Sync CRDs + manager ClusterRole into Helm charts

Test

make test               # Unit tests (no cluster required)
make test-e2e           # E2E tests (requires a real cluster)

Lint

make lint-fix

Contributing

We welcome contributions of all kinds — bug reports, feature requests, documentation improvements, and code. Please read CONTRIBUTING.md before submitting a pull request.

All commits must include a Signed-off-by line (see DCO). Use git commit -s to add it automatically.

License

Apache License 2.0 — see LICENSE for details.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
api
v1alpha1 Package v1alpha1 contains API Schema definitions for the agents v1alpha1 API group.	Package v1alpha1 contains API Schema definitions for the agents v1alpha1 API group.
cmd
envoyextproc command envoyextproc is the Envoy ExternalProcessor companion process for the agent-sandbox data plane.	envoyextproc is the Envoy ExternalProcessor companion process for the agent-sandbox data plane.
envoyextproc/app Package extproc contains the bootstrap logic for the envoyextproc binary (cmd/envoyextproc).	Package extproc contains the bootstrap logic for the envoyextproc binary (cmd/envoyextproc).
sandbox command sandbox is the open-source build of the agentbox operator.	sandbox is the open-source build of the agentbox operator.
sandbox/app Package controller contains the core bootstrap logic for the agentbox operator (cmd/sandbox).	Package controller contains the core bootstrap logic for the agentbox operator (cmd/sandbox).
sandbox/app/extconfig Package extconfig defines the schema and loader for the extension configuration file (--extension-config).	Package extconfig defines the schema and loader for the extension configuration file (--extension-config).
wsproxy command wsproxy is the AgentBox WebSocket proxy sidecar.	wsproxy is the AgentBox WebSocket proxy sidecar.
wsproxy/app Package wsproxy contains the bootstrap logic for the wsproxy sidecar (cmd/wsproxy).	Package wsproxy contains the bootstrap logic for the wsproxy sidecar (cmd/wsproxy).
pkg
api/protocol Package protocol defines the WebSocket sync protocol shared between the Worker (pkg/apiserver) and the ws-proxy (cmd/wsproxy).	Package protocol defines the WebSocket sync protocol shared between the Worker (pkg/apiserver) and the ws-proxy (cmd/wsproxy).
apiserver
apiserver/domain
apiserver/gen Package gen provides primitives to interact with the openapi HTTP API.	Package gen provides primitives to interact with the openapi HTTP API.
apiserver/handlers Package handlers implements the StrictServerInterface generated from the OpenAPI spec.	Package handlers implements the StrictServerInterface generated from the OpenAPI spec.
apiserver/router
apiserver/router/middleware
apiserver/service
controllers/sandboxpool
controllers/sandboxpool/poststarthooks Package poststarthooks executes post-start hook actions on sandbox pods that have just transitioned Starting → Running.	Package poststarthooks executes post-start hook actions on sandbox pods that have just transitioned Starting → Running.
controllers/sandboxtemplate
e2bcompat Package e2bcompat provides an E2B-compatible HTTP API server for AgentBox.	Package e2bcompat provides an E2B-compatible HTTP API server for AgentBox.
e2bcompat/domain Package domain provides E2B-compatible domain conversion utilities.	Package domain provides E2B-compatible domain conversion utilities.
e2bcompat/gen Package e2bgen provides primitives to interact with the openapi HTTP API.	Package e2bgen provides primitives to interact with the openapi HTTP API.
e2bcompat/handlers Package handlers implements the E2B-compatible StrictServerInterface generated by oapi-codegen.	Package handlers implements the E2B-compatible StrictServerInterface generated by oapi-codegen.
e2bcompat/router Package router provides E2B-compatible HTTP route registration.	Package router provides E2B-compatible HTTP route registration.
e2bcompat/router/middleware Package middleware provides E2B-compatible authentication middleware.	Package middleware provides E2B-compatible authentication middleware.
envoy/extproc Package extproc implements an Envoy ExternalProcessor (ExtProc) gRPC server.	Package extproc implements an Envoy ExternalProcessor (ExtProc) gRPC server.
framework Package framework defines the host/extension contract shared by every extension point in AgentBox (SandboxPool lifecycle Plugins, quota Providers, and future Providers such as billing or telemetry).	Package framework defines the host/extension contract shared by every extension point in AgentBox (SandboxPool lifecycle Plugins, quota Providers, and future Providers such as billing or telemetry).
framework/plugins
framework/providers/quota
lifecycle/inplaceupdate
lifecycle/schedule Package schedule implements the per-pool streaming claim scheduler.	Package schedule implements the per-pool streaming claim scheduler.
metrics Package metrics defines and registers all custom Prometheus metrics for AgentBox.	Package metrics defines and registers all custom Prometheus metrics for AgentBox.
proto/sandbox/ctrlplane/v1
store
utils/apikey
utils/cluster
utils/dockerconfig Package dockerconfig builds and parses Kubernetes `.dockerconfigjson` payloads for imagePullSecret Secrets of type kubernetes.io/dockerconfigjson.	Package dockerconfig builds and parses Kubernetes `.dockerconfigjson` payloads for imagePullSecret Secrets of type kubernetes.io/dockerconfigjson.
utils/hostalias Package hostalias provides an in-process /etc/hosts-style resolver driven by the Manager-pushed ClusterConfig.HostAliases list.	Package hostalias provides an in-process /etc/hosts-style resolver driven by the Manager-pushed ClusterConfig.HostAliases list.
utils/httpctx Package httpctx provides shared helpers for extracting authentication context from gin-based HTTP handlers.	Package httpctx provides shared helpers for extracting authentication context from gin-based HTTP handlers.
utils/httplog Package httplog centralizes HTTP request logging for the AgentBox API servers.	Package httplog centralizes HTTP request logging for the AgentBox API servers.
utils/imageresolver
utils/indexer
utils/k8sname Package k8sname provides validation for Kubernetes resource names with a stricter variant of RFC 1123 DNS label rules: names must start with a lowercase letter (not a digit).	Package k8sname provides validation for Kubernetes resource names with a stricter variant of RFC 1123 DNS label rules: names must start with a lowercase letter (not a digit).
utils/resource Package resource provides utilities for computing resource sums across Pod containers.	Package resource provides utilities for computing resource sums across Pod containers.
version Package version holds the build-time version for all AgentBox components.	Package version holds the build-time version for all AgentBox components.
wsproxy/syncmgr Package syncmgr implements the WSProxy sync manager that maintains persistent WebSocket connections to every Worker cluster and pushes API key, SandboxTemplate, and ClusterConfig updates.	Package syncmgr implements the WSProxy sync manager that maintains persistent WebSocket connections to every Worker cluster and pushes API key, SandboxTemplate, and ClusterConfig updates.