OpenSandbox

---

English | 中文

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: Client SDKs for Python, Java/Kotlin, and JavaScript/TypeScript.
• 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.

Examples

Basic Sandbox Operations

Requirements:

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

1. Clone the Repository

git clone https://github.com/alibaba/OpenSandbox.git
cd OpenSandbox

2. Start the Sandbox Server

cd server
uv sync
cp example.config.toml ~/.sandbox.toml # Copy configuration file
uv run python -m src.main # Start the service

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 rich examples demonstrating sandbox usage in different scenarios. 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 - Run OpenSandbox on Kubernetes via 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.
• 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.

🌐 Browser and Desktop Environments

• chrome - Headless Chromium with VNC and DevTools access for automation/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)
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) - includes sandbox lifecycle, command execution, file operations
  • Code Interpreter SDK (Java\Kotlin SDK, Python SDK, JavaScript/TypeScript 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

SDK

• Go SDK - Go client SDK for sandbox lifecycle management, command execution, and file operations.

Sandbox Runtime

• Persistent storage - Mountable persistent storage for sandboxes (see Proposal 0003).
• Ingress multi-network strategies - Multi-Kubernetes provisioning and multi-network modes for the Ingress Gateway.
• Local lightweight sandbox - Lightweight sandbox for AI tools running directly on PCs.

Deployment

• Kubernetes Helm - Helm charts to deploy all components.

Contact and Discussion

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

Star History