OpenSandbox: Building Production-Grade Isolation for AI Agents That Actually Execute Code

Hook

Your AI coding agent just wrote a Python script that trains a model, spawns a web server, and downloads a dataset. Where does it run? If your answer is 'just docker run,' you're about to learn why that doesn't scale past your laptop.

Context

The explosion of LLM-powered coding agents like Claude Code, Cursor, and GitHub Copilot Workspace created an infrastructure problem nobody saw coming: these agents don't just generate code snippets, they execute arbitrary programs, install packages, spawn servers, and manipulate filesystems. The traditional sandbox options fell short. AWS Lambda times out after 15 minutes and loses all state. Docker Compose works locally but has no production deployment story. Kubernetes provides scale but requires writing custom controllers for pod lifecycle, network isolation, and persistent storage. E2B and Modal emerged as managed solutions, but at SaaS pricing and vendor lock-in.

OpenSandbox enters this gap as self-hosted infrastructure specifically designed for the interaction patterns of AI agents. Unlike general-purpose container orchestration, it optimizes for what agents actually do: execute hundreds of small commands in rapid succession, maintain REPL-like state across interactions, need stable webhook URLs for callbacks, and require filesystem persistence for multi-step workflows. It's not trying to be Kubernetes — it's using Kubernetes (and Docker) as runtime targets while abstracting the complexity through multi-language SDKs and a FastAPI control plane.

Technical Insight

OpenSandbox's architecture revolves around a surprisingly simple design: an execd daemon runs inside every sandbox container, exposing gRPC endpoints for command execution and file operations. This eliminates the per-operation overhead of docker exec or SSH connections, critical when an agent makes 300+ filesystem calls while exploring a codebase.

Here's how you create and interact with a sandbox using the Python SDK:

from opensandbox import Sandbox

# Works identically against local Docker or K8s cluster
sandbox = Sandbox(
    runtime="kubernetes",  # or "docker" for local dev
    image="python:3.11",
    keep_alive=True,       # persistent REPL-like session
    persistent_volume={"mount_path": "/workspace", "size": "10Gi"}
)

with sandbox:
    # Install dependencies once, state persists
    sandbox.exec("pip install pandas numpy")
    
    # Write code, execute, inspect results
    sandbox.write_file("/workspace/analysis.py", agent_generated_code)
    result = sandbox.exec("python /workspace/analysis.py")
    
    # Filesystem survives across interactions
    csv_data = sandbox.read_file("/workspace/output.csv")

The magic happens in the runtime abstraction layer. When you switch from runtime="docker" to runtime="kubernetes", the SDK makes identical API calls to the FastAPI server, which delegates to different backend adapters. The Docker adapter calls the Docker Engine API directly. The Kubernetes adapter creates agent-sandbox CRDs — a Kubernetes SIG project that manages pod lifecycle with proper security contexts and resource limits.

Network isolation demonstrates the design's sophistication. Each sandbox gets two network components: an ingress gateway providing a stable public URL (so agents can run web servers and receive webhooks), and per-sandbox egress controls implemented via Kubernetes NetworkPolicies. This solves a real security problem: an agent training on your proprietary codebase shouldn't be able to POST that data to an attacker's server if a prompt injection convinces it to.

# Ingress: stable URL for agent's web server
sandbox = Sandbox(
    ingress={"enabled": True, "port": 8000}
)
with sandbox:
    sandbox.exec("python -m http.server 8000 &")
    public_url = sandbox.get_ingress_url()  # https://sandbox-abc123.yourdomain.com
    
# Egress: whitelist external services
sandbox = Sandbox(
    egress={"allow": ["pypi.org", "huggingface.co"]}
)

The Code Interpreter SDK sits atop these primitives, mimicking Jupyter's kernel protocol for stateful REPL sessions. Instead of restarting Python for every code block (expensive when agents load 500MB ML models), it maintains interpreter state:

from opensandbox.code_interpreter import CodeInterpreter

interpreter = CodeInterpreter(language="python")

interpreter.execute("import pandas as pd")
interpreter.execute("df = pd.read_csv('data.csv')")  # state persists
result = interpreter.execute("df.describe()")  # df still in memory

Persistent storage uses environment-specific backends: Docker named volumes locally, Kubernetes PVCs in clusters, and OSSFS (Alibaba's object storage FUSE driver) for cloud deployments. This matters because agents doing data science need datasets to survive sandbox restarts, unlike ephemeral web request handlers.

The production Kubernetes runtime leverages agent-sandbox's security features: gVisor for syscall filtering, resource quotas to prevent runaway agents, and pod presets for injecting secrets without exposing them to SDK clients. It's the difference between 'runs in Docker' and 'runs 1000 concurrent agent sessions with proper multi-tenancy.'

Gotcha

OpenSandbox's Kubernetes runtime requires cluster-admin permissions to install agent-sandbox CRDs, making it unsuitable for platforms where sandbox users don't control infrastructure. If you're building a SaaS product where customers bring their own agents, you can't ask them for cluster admin access. The Docker runtime avoids this but loses all production-scale benefits.

Security boundaries are concerning for adversarial workloads. While egress NetworkPolicies block obvious data exfiltration, they're bypassable via DNS tunneling or encoding data in allowed HTTP requests. The documentation provides no threat model for prompt injection attacks where a malicious user tricks an LLM into crafting container escape exploits. gVisor and Kata support exist but add operational complexity the quickstart glosses over. If you're running untrusted agents at scale, expect to hire a security engineer to harden this properly.

Observability is bare-bones. Sandbox logs are stored in-memory and disappear when containers terminate. There's no built-in cost tracking (critical when agents spin up GPU instances), no distributed tracing for multi-sandbox workflows, and no metrics on execution time or resource usage. You'll need to integrate Prometheus and your own logging pipeline, which undermines the 'batteries included' promise.

Verdict

Use if: You're running LLM coding agents at production scale (100+ concurrent sessions), already operate Kubernetes clusters, and need the Docker local-dev to K8s production path without rewriting code. The persistent storage semantics and network isolation justify the operational overhead when agents are core to your product, not a side feature. Skip if: You're prototyping agent features and can tolerate E2B's SaaS pricing for faster iteration, need sub-second cold starts (container overhead kills this), or lack in-house Kubernetes expertise. For single-user or low-scale deployments, plain Docker Compose with manual port mapping gives you 80% of the value at 5% of the complexity. This is infrastructure for teams treating agents as first-class workloads, not a weekend hack.