Raw capture — raw/opensandbox.md

url: https://github.com/alibaba/OpenSandbox date_fetched: 2026-07-05 backfilled: true

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.

Python:

pip install opensandboxJava/Kotlin (Gradle Kotlin DSL):

dependencies {
    implementation("com.alibaba.opensandbox:sandbox:{latest_version}")
}

Java/Kotlin (Maven):

<dependency>
    <groupId>com.alibaba.opensandbox</groupId>
    <artifactId>sandbox</artifactId>
    <version>{latest_version}</version>
</dependency>

JavaScript/TypeScript:

npm install @alibaba-group/opensandboxC#/.NET:

dotnet add package Alibaba.OpenSandboxGo:

go get github.com/alibaba/OpenSandbox/sdks/sandbox/goOpenSandbox also provides osb, a terminal CLI for the common sandbox workflow: create sandboxes, run commands, move files, inspect diagnostics, and manage runtime egress policy.

Install:

pip install opensandbox-cli
# or
uv tool install opensandbox-cli

Quick start:

osb config init
osb config set connection.domain localhost:8080
osb config set connection.protocol http
osb config set connection.api_key <your-api-key>
osb sandbox create --image python:3.12 --timeout 30m -o json
osb command run <sandbox-id> -o raw -- python -c "print(1 + 1)"

See the CLI README for the full command reference.

The OpenSandbox MCP server exposes sandbox creation, command execution, and text file operations to MCP-capable clients such as Claude Code and Cursor.

Install and run:

pip install opensandbox-mcp
opensandbox-mcp --domain localhost:8080 --protocol http

Minimal stdio config:

{
  "mcpServers": {
    "opensandbox": {
      "command": "opensandbox-mcp",
      "args": ["--domain", "localhost:8080", "--protocol", "http"]
    }
  }
}

See the MCP README for client-specific setup.

Requirements:

uvx opensandbox-server init-config ~/.sandbox.toml --example docker
uvx opensandbox-server
# Show help
# uvx opensandbox-server -h

Install the Code Interpreter SDK

uv pip install opensandbox-code-interpreterCreate a sandbox and execute commands and codes.

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.1.0",
        entrypoint=["/opt/code-interpreter/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())

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

For more details, please refer to the examples documentation.

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
cli/ OpenSandbox command-line interface
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/ Runnable example code
docs/examples/ Example documentation 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 Architecture.

This project is open source under the Apache 2.0 License.

See ROADMAP.md for the current project roadmap, planning scope, and how roadmap items are managed.