OpenSandbox

---

English | 中文

OpenSandbox is a universal sandbox platform for AI application scenarios, providing multi-language SDKs, unified sandbox protocols, and sandbox runtimes for LLM-related capabilities (command execution, file operations, code execution, browser operations, Agent execution, etc.).

Features

• Multi-language SDKs: Provides sandbox SDKs in Python, Java/Kotlin, JavaScript/TypeScript, Go (Roadmap), and more.
• Sandbox Protocol: Defines sandbox lifecycle management API and sandbox execution API. You can extend your own sandbox runtime through these sandbox protocols.
• Sandbox Runtime: Implements sandbox lifecycle management by default, supports Docker and Kubernetes runtimes, enabling large-scale distributed sandbox scheduling.
• Sandbox Environments: Built-in implementations for Command, Filesystem, Code Interpreter. And provides examples for Coding Agents (Claude Code, etc.), Browser automation (Chrome, Playwright), and Desktop environments (VNC, VS Code).

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:latest",
        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 - Complete Code Interpreter SDK example

  • Run commands and execute Python/Java/Go/TypeScript code inside a sandbox
  • Covers context creation, code execution, and result streaming
  • Supports custom language versions

• aio-sandbox - All-in-One sandbox example

  • Uses OpenSandbox SDK to create an agent-sandbox instance
  • Shows how to connect and use the full AIO sandbox capabilities

🤖 Coding Agent Integrations

OpenSandbox integrates various Coding Agents, including Claude Code, Google Gemini, OpenAI Codex, and more.

• claude-code - Claude Code integration
• gemini-cli - Google Gemini CLI integration
• codex-cli - OpenAI Codex CLI integration
• iflow-cli - iFLow CLI integration
• langgraph - LangGraph integration
• google-adk - Google ADK integration

🌐 Browser and Desktop Environments

• chrome - Chrome headless browser

  • Launches Chromium browser with remote debugging functionality
  • Provides VNC (port 5901) and DevTools (port 9222) access
  • Suitable for scenarios requiring browser automation or debugging

• playwright - Playwright browser automation

  • Uses Playwright + Chromium in headless mode to scrape web content
  • Can extract web page titles, body text, and other information
  • Suitable for web crawling and automated testing

• desktop - VNC desktop environment

  • Launches a complete desktop environment (Xvfb + x11vnc + fluxbox)
  • Remote access to sandbox desktop via VNC client
  • Supports custom VNC password

• vscode - VS Code Web environment

  • Runs code-server (VS Code web version) in a sandbox
  • Access complete VS Code development environment through browser
  • Suitable for remote development and code editing scenarios

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

Project Structure

Directory	Description
server/	Python FastAPI sandbox lifecycle server
components/execd/	Sandbox execution daemon (commands and file operations)
components/ingress/	Sandbox traffic ingress proxy
components/egress/	Sandbox network egress control
sdks/	Multi-language SDKs (Python, Java/Kotlin)
sandboxes/	Sandbox runtime images (e.g., code-interpreter)
kubernetes/	Kubernetes operator and batch sandbox support
specs/	OpenAPI specifications
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 - Contains OpenAPI definitions for sandbox lifecycle API and sandbox execution API
• server/README.md - Contains sandbox server startup and configuration, currently supports Docker Runtime, will support Kubernetes Runtime in the future

License

This project is open source under the Apache 2.0 License.

You can use OpenSandbox for personal or commercial projects in compliance with the license terms.

Roadmap

SDK

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

Server Runtime

• OpenSandbox Kubernetes Runtime - High-performance sandbox scheduling implementation (see kubernetes/)
• kubernetes-sigs/agent-sandbox Support - Integration with kubernetes-sigs/agent-sandbox
• Declarative Network Isolation - Network egress control with allow/deny rules for specific domains (see OSEP-0001)
  • DNS-based egress control (Layer 1)
  • Network-based egress control (Layer 2)

Contact and Discussion

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

We welcome everyone to help build OpenSandbox into a universal sandbox infrastructure for AI scenarios.