OpenSandbox

---

Documentation | 中文文档

OpenSandbox is a general-purpose sandbox platform for AI applications, offering multi-language SDKs, unified sandbox APIs, and Docker/Kubernetes runtimes for scenarios like Coding Agents, GUI Agents, Agent Evaluation, AI Code Execution, and RL Training.

Features

• Multi-language SDKs: Provides sandbox SDKs in Python, Java/Kotlin, JavaScript/TypeScript, C#/.NET, Go (Roadmap), and more.
• Sandbox Protocol: Defines sandbox lifecycle management APIs and sandbox execution APIs so you can extend custom sandbox runtimes.
• Sandbox Runtime: Built-in lifecycle management supporting Docker and high-performance Kubernetes runtime, enabling both local runs and large-scale distributed scheduling.
• Sandbox Environments: Built-in Command, Filesystem, and Code Interpreter implementations. Examples cover Coding Agents (e.g., Claude Code), browser automation (Chrome, Playwright), and desktop environments (VNC, VS Code).
• Network Policy: Unified Ingress Gateway with multiple routing strategies plus per-sandbox egress controls.
• Strong Isolation: Supports secure container runtimes like gVisor, Kata Containers, and Firecracker microVM for enhanced isolation between sandbox workloads and the host. See Secure Container Runtime Guide for details.

Examples

Basic Sandbox Operations

Requirements:

• Docker (required for local execution)
• Python 3.10+ (recommended for examples and local runtime)

1. Install and Configure the Sandbox Server

uv pip install opensandbox-server
opensandbox-server init-config ~/.sandbox.toml --example docker

If you prefer working from source, you can still clone the repo for development, but you no longer need to clone this repository just to start the server.

git clone https://github.com/alibaba/OpenSandbox.git
cd OpenSandbox/server
uv sync
cp example.config.toml ~/.sandbox.toml # Copy configuration file
uv run python -m src.main # Start the service

2. Start the Sandbox Server

opensandbox-server

# Show help
opensandbox-server -h

3. Create a Code Interpreter and Execute Commands

Install the Code Interpreter SDK

uv pip install opensandbox-code-interpreter

Create a sandbox and execute commands

import asyncio
from datetime import timedelta

from code_interpreter import CodeInterpreter, SupportedLanguage
from opensandbox import Sandbox
from opensandbox.models import WriteEntry

async def main() -> None:
    # 1. Create a sandbox
    sandbox = await Sandbox.create(
        "opensandbox/code-interpreter:v1.0.1",
        entrypoint=["/opt/opensandbox/code-interpreter.sh"],
        env={"PYTHON_VERSION": "3.11"},
        timeout=timedelta(minutes=10),
    )

    async with sandbox:

        # 2. Execute a shell command
        execution = await sandbox.commands.run("echo 'Hello OpenSandbox!'")
        print(execution.logs.stdout[0].text)

        # 3. Write a file
        await sandbox.files.write_files([
            WriteEntry(path="/tmp/hello.txt", data="Hello World", mode=644)
        ])

        # 4. Read a file
        content = await sandbox.files.read_file("/tmp/hello.txt")
        print(f"Content: {content}") # Content: Hello World

        # 5. Create a code interpreter
        interpreter = await CodeInterpreter.create(sandbox)

        # 6. Execute Python code (single-run, pass language directly)
        result = await interpreter.codes.run(
              """
                  import sys
                  print(sys.version)
                  result = 2 + 2
                  result
              """,
              language=SupportedLanguage.PYTHON,
        )

        print(result.result[0].text) # 4
        print(result.logs.stdout[0].text) # 3.11.14

    # 7. Cleanup the sandbox
    await sandbox.kill()

if __name__ == "__main__":
    asyncio.run(main())

More Examples

OpenSandbox provides examples covering SDK usage, agent integrations, browser automation, and training workloads. All example code is located in the examples/ directory.

🎯 Basic Examples

• code-interpreter - End-to-end Code Interpreter SDK workflow in a sandbox.
• aio-sandbox - All-in-One sandbox setup using the OpenSandbox SDK.
• agent-sandbox - Example integration for running OpenSandbox workloads on Kubernetes with kubernetes-sigs/agent-sandbox.

🤖 Coding Agent Integrations

• claude-code - Run Claude Code inside OpenSandbox.
• gemini-cli - Run Google Gemini CLI inside OpenSandbox.
• codex-cli - Run OpenAI Codex CLI inside OpenSandbox.
• kimi-cli - Run Kimi CLI (Moonshot AI) inside OpenSandbox.
• iflow-cli - Run iFLow CLI inside OpenSandbox.
• langgraph - LangGraph state-machine workflow that creates/runs a sandbox job with fallback retry.
• google-adk - Google ADK agent using OpenSandbox tools to write/read files and run commands.
• nullclaw - Launch a Nullclaw Gateway inside a sandbox.
• openclaw - Launch an OpenClaw Gateway inside a sandbox.

🌐 Browser and Desktop Environments

• chrome - Chromium sandbox with VNC and DevTools access for automation and debugging.
• playwright - Playwright + Chromium headless scraping and testing example.
• desktop - Full desktop environment in a sandbox with VNC access.
• vscode - code-server (VS Code Web) running inside a sandbox for remote dev.

🧠 ML and Training

• rl-training - DQN CartPole training in a sandbox with checkpoints and summary output.

For more details, please refer to examples and the README files in each example directory.

Project Structure

Directory	Description
sdks/	Multi-language SDKs (Python, Java/Kotlin, TypeScript/JavaScript, C#/.NET)
specs/	OpenAPI specs and lifecycle specifications
server/	Python FastAPI sandbox lifecycle server
kubernetes/	Kubernetes deployment and examples
components/execd/	Sandbox execution daemon (commands and file operations)
components/ingress/	Sandbox traffic ingress proxy
components/egress/	Sandbox network egress control
sandboxes/	Runtime sandbox implementations
examples/	Integration examples and use cases
oseps/	OpenSandbox Enhancement Proposals
docs/	Architecture and design documentation
tests/	Cross-component E2E tests
scripts/	Development and maintenance scripts

For detailed architecture, see docs/architecture.md.

Documentation

• docs/architecture.md – Overall architecture & design philosophy
• SDK
  • Sandbox base SDK (Java/Kotlin SDK, Python SDK, JavaScript/TypeScript SDK, C#/.NET SDK) - includes sandbox lifecycle, command execution, file operations
  • Code Interpreter SDK (Java/Kotlin SDK, Python SDK, JavaScript/TypeScript SDK, C#/.NET SDK) - code interpreter
• specs/README.md - OpenAPI definitions for sandbox lifecycle API and sandbox execution API
• server/README.md - Sandbox server startup and configuration; supports Docker and Kubernetes runtimes

License

This project is open source under the Apache 2.0 License.

Roadmap [2026.03]

SDK

• Sandbox client connection pool - Client-side sandbox connection pool management, providing pre-provisioned sandboxes to obtain an environment at X ms.
• Go SDK - Go client SDK for sandbox lifecycle management, command execution, and file operations.

Sandbox Runtime

• Persistent volumes - Mountable persistent volumes for sandboxes (see Proposal 0003).
• Local lightweight sandbox - Lightweight sandbox for AI tools running directly on PCs.
• Secure Container - Secure sandbox for AI Agents running inside container.

Deployment

• Guide - Deployment guide for self-hosted Kubernetes cluster.

Contact and Discussion

• Issues: Submit bugs, feature requests, or design discussions through GitHub Issues

Star History