OpenSandbox

OpenSandbox

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.

Stars: 1033

Visit
 screenshot

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. It provides features such as multi-language SDKs, sandbox protocol, sandbox runtime, sandbox environments, and network policy. Users can perform basic sandbox operations like installing and configuring the sandbox server, starting the sandbox server, creating a code interpreter, and executing commands. The platform also offers examples for coding agent integrations, browser and desktop environments, and ML and training tasks.

README:

OpenSandbox logo

OpenSandbox

GitHub stars Ask DeepWiki license PyPI version npm version E2E Status


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

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

# opensandbox-server -h # Show help

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

πŸ€– 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

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

Star History Chart

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for OpenSandbox

Similar Open Source Tools

For similar tasks

For similar jobs