alibaba/OpenSandbox

OpenSandbox

---

Document | 文档

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.

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

1
2

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 server startup no longer requires it.

1 2 3 4 5

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

Copy

2. Start the Sandbox Server

1
2
3
4

opensandbox-server

# Show help
opensandbox-server -h

3. Create a Code Interpreter and Execute Commands

Install the Code Interpreter SDK

1

uv pip install opensandbox-code-interpreter

Create a sandbox and execute commands

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

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.
• 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 - 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

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

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