Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/opensandbox-group/OpenSandbox/llms.txt

Use this file to discover all available pages before exploring further.

OpenSandbox is a general-purpose sandbox platform built for AI applications. Its architecture is deliberately layered so that each concern — developer-facing ergonomics, stable API contracts, lifecycle orchestration, runtime provisioning, in-sandbox execution, and network security — lives behind a clear boundary. The result is a system where SDKs depend only on public contracts, the server owns lifecycle orchestration without knowing runtime specifics, and runtime providers own platform-specific resource creation without leaking into the API. This document describes the six practical surfaces that make up OpenSandbox and how a request flows through them.

​
Six Architectural Surfaces

1. Client Surface

Language SDKs, the osb CLI, and the MCP server — the developer-facing entry points for all sandbox operations.

2. Protocol Surface

OpenAPI contracts under specs/ that define stable, runtime-neutral interfaces for lifecycle, execution, and egress.

3. Lifecycle Control Plane

The FastAPI server that authenticates requests, validates config, persists metadata, and delegates to a runtime service.

4. Runtime Backends

Docker for local and single-host deployments; Kubernetes via BatchSandbox and agent-sandbox for scaled, pooled workloads.

5. Sandbox Data Plane

The user workload container plus the injected execd daemon, optional code interpreter, volumes, and egress sidecar.

6. Network and Security Plane

Endpoint resolution, server proxying, Kubernetes ingress gateway, egress policy enforcement, and secure container runtimes.

​
Request Flow: SDK to Sandbox

The following diagram shows how a typical sandbox creation request flows from a client SDK through the server and runtime to a running sandbox. 
┌──────────────────────────────────────────────────────────────────┐
│  CLIENT SURFACE                                                  │
│  SDK (Python / JS / Go / Java / C#)  |  osb CLI  |  MCP Server  │
└──────────────────────────┬───────────────────────────────────────┘
                           │ POST /v1/sandboxes
                           ▼
┌──────────────────────────────────────────────────────────────────┐
│  LIFECYCLE CONTROL PLANE                                         │
│  FastAPI Server                                                  │
│  • Validates API key (OPEN-SANDBOX-API-KEY header)               │
│  • Validates request schema against OpenAPI spec                 │
│  • Persists server-managed metadata (SQLite / [store])           │
│  • Selects runtime service: Docker or Kubernetes                 │
└──────────────────────────┬───────────────────────────────────────┘
                           │
              ┌────────────┴────────────┐
              ▼                         ▼
┌─────────────────────┐   ┌────────────────────────────────────────┐
│  DOCKER RUNTIME     │   │  KUBERNETES RUNTIME                    │
│  DockerSandboxSvc   │   │  KubernetesSandboxSvc                  │
│  • Pull image        │   │  • Create BatchSandbox or agent-sandbox│
│  • Stage execd       │   │  • Stage execd via init container      │
│  • Map ports         │   │  • Resolve ingress endpoints           │
│  • Start container   │   │  • Attach egress/volume/network config │
└──────────┬──────────┘   └────────────────────┬───────────────────┘
           │                                   │
           └──────────────┬────────────────────┘
                          ▼
┌──────────────────────────────────────────────────────────────────┐
│  SANDBOX DATA PLANE (per sandbox)                                │
│                                                                  │
│  ┌────────────────┐   ┌────────────────┐   ┌──────────────────┐ │
│  │  User Container│   │  execd daemon  │   │  Egress Sidecar  │ │
│  │  (user image + │   │  port 44772    │   │  FQDN policy +   │ │
│  │   entrypoint)  │   │  HTTP/SSE/WS   │   │  DNS proxy +     │ │
│  └────────────────┘   │  Shell/Files/  │   │  nftables        │ │
│                       │  Code/PTY/     │   └──────────────────┘ │
│                       │  Metrics       │                         │
│                       └────────────────┘                         │
└──────────────────────────────────────────────────────────────────┘
                          ▲
                          │
┌──────────────────────────────────────────────────────────────────┐
│  NETWORK AND SECURITY PLANE                                      │
│  • Ingress gateway (K8s header/URI routing)                      │
│  • Server proxy (/sandboxes/{id}/proxy/{port})                   │
│  • Egress FQDN allowlist + deny.always enforcement               │
│  • Secure runtime (gVisor / Kata / Firecracker via RuntimeClass) │
└──────────────────────────────────────────────────────────────────┘

​
1. Client Surface

The client surface is the developer-facing entry point for OpenSandbox. All tools at this layer depend only on the OpenAPI contracts in specs/ — they do not embed runtime-specific logic. Language SDKs wrap lifecycle and in-sandbox operations behind idiomatic APIs:
  • Python: sdks/sandbox/python
  • JavaScript/TypeScript: sdks/sandbox/javascript
  • Go: sdks/sandbox/go
  • Java/Kotlin: sdks/sandbox/kotlin
  • C#/.NET: sdks/sandbox/csharp
Common SDK capabilities include create/list/inspect/pause/resume/delete, endpoint resolution, command execution with streamed output, file and directory management, metrics reading, and egress policy inspection. Code Interpreter SDKs build on the sandbox SDKs and execd code execution APIs. They manage Jupyter kernel contexts and expose language-oriented helpers for Python, Java, Node.js, Go, and TypeScript. The osb CLI (cli/) provides terminal access to every sandbox operation:
  • osb sandbox — lifecycle and endpoint management
  • osb command — execution, background logs, and shell sessions
  • osb file — file and directory operations
  • osb egress — runtime egress policy inspection and mutation
The MCP server (sdks/mcp/sandbox/python) exposes focused sandbox lifecycle, command, and text-file tools to MCP-capable clients such as Claude Code and Cursor.

​
2. Protocol Surface

OpenSandbox treats specs/ as the public contract source of truth. SDKs generate clients from these specs; handwritten adapters cover ergonomics, streaming, and error mapping.
Spec fileDescription
specs/sandbox-lifecycle.ymlSandbox create, list, get, pause, resume, delete, snapshot, endpoint resolution
specs/diagnostic-api.ymlSandbox logs, events, and operator diagnostic descriptors
specs/execd-api.yamlIn-sandbox execution: commands, files, code, PTY, sessions, metrics
specs/egress-api.yamlRuntime egress policy inspection and mutation (GET/POST/PATCH/DELETE /policy)
The lifecycle spec lives under the server’s /v1 base path. The execd and egress specs are served by the respective in-sandbox daemons, not by the central server.

​
3. Lifecycle Control Plane

The FastAPI server (server/) is the hub of the system. It owns request validation, API-key authentication, server configuration, lifecycle orchestration, endpoint formatting, diagnostics, and server-managed persistence. Runtime selection is a single config field: 
[runtime]
type = "docker"   # or "kubernetes"
Both DockerSandboxService and KubernetesSandboxService satisfy the same SandboxService interface, so API routes stay thin and runtime-specific details stay behind the service boundary. Persistence defaults to SQLite at ~/.opensandbox/opensandbox.db (configurable via [store]). Snapshot metadata is the primary persisted server resource. See Server Deployment for the full configuration reference and startup guide.

​
4. Runtime Backends

​
Docker

The Docker runtime is the local and single-host backend. It manages containers, expiration timers, labels, volumes, ports, optional sidecars, and OCI snapshots by talking directly to the Docker daemon. The execd binary is staged from [runtime].execd_image into the sandbox at container start time. See Docker Deployment for the full Docker runtime guide.

​
Kubernetes

The Kubernetes runtime delegates actual workload creation to a workload provider:
  • batchsandbox (default) — backed by the OpenSandbox controller and BatchSandbox CRD. Supports resource pools, batch delivery, task orchestration, and OCI snapshot pause/resume.
  • agent-sandbox — a provider for kubernetes-sigs/agent-sandbox.
The Kubernetes server path handles template merging, per-request pull secrets, resource limit translation, volume and egress configuration, ingress gateway endpoint resolution, and pause/resume delegation. See Kubernetes Deployment for the full Kubernetes guide including Helm installation.

​
5. Sandbox Data Plane

Each sandbox is a user workload container with OpenSandbox control processes injected around it. execd is a Go/Gin daemon that runs inside the sandbox and exposes the execution API on port 44772. It handles shell command execution with SSE streaming, background commands, PTY sessions over WebSocket, file and directory operations, Jupyter-backed code execution, and local CPU/memory metrics. See Components for details. Code interpreter runtime: when a code-interpreter image is used, execd talks to Jupyter over HTTP/WebSocket and translates kernel messages into OpenSandbox streaming events. Volumes follow a runtime-neutral model:
  • host — host bind mount
  • pvc — Docker named volume or Kubernetes PVC
  • ossfs — Alibaba Cloud OSS mount
Egress sidecar enforces outbound network policy from the sandbox network namespace. In Docker, it runs as a separate container in the same network namespace. In Kubernetes, it is appended to the pod spec.

​
6. Network and Security Plane

Endpoint resolution returns the reachable address for a sandbox port. Depending on runtime and config, this may be a Docker host/bridge mapped endpoint, a Kubernetes ingress gateway endpoint, or a server-proxied URL under /sandboxes/{id}/proxy/{port}. Ingress gateway (components/ingress/) is a Kubernetes-oriented HTTP/WebSocket reverse proxy that routes traffic to sandbox ports via header mode or URI mode. See Network Architecture for routing details. Egress policy is enforced per-sandbox by the egress sidecar via FQDN allowlist, deny.always platform overlays, and optional nftables IP-level enforcement. See Network Architecture for isolation design. Secure container runtimes (gVisor, Kata Containers, Firecracker) add kernel-level isolation through the [secure_runtime] config and Kubernetes RuntimeClass. See the Secure Container guide for the compatibility matrix.

​
Design Principles

Protocol First

Public behavior starts from OpenAPI specs in specs/. SDKs and generated clients align to those contracts.

Control Plane vs Data Plane

The server orchestrates and validates. Provisioning belongs in runtime services. In-sandbox operations belong in execd and egress sidecars.

Runtime-Neutral API

The lifecycle API uses shared concepts (resource limits, volumes, endpoints, network policy). Docker and Kubernetes materialize them differently without breaking the API contract.

Secure Defaults

API-key authentication, resource limits, capability drops, egress controls, and secure runtimes are all opt-in from a minimal base. Less restrictive modes require explicit configuration.

Build docs developers (and LLMs) love

Get started for freeTalk to us