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.

Features

• 🧩 SDKs, CLI, and MCP: Provides multi-language SDKs, the osb CLI, and MCP server integration for sandbox creation, command execution, and file operations. See SDKs, CLI, and MCP.
• 📜 Sandbox Protocol: Defines sandbox lifecycle management APIs and sandbox execution APIs so you can extend custom sandbox runtimes. See API specs.
• 🚀 Sandbox Runtime: Built-in lifecycle management supporting Docker and high-performance Kubernetes runtime, enabling both local runs and large-scale distributed scheduling. See Kubernetes runtime.
• 🖥️ 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. See Ingress Gateway and egress controls.
• 🔑 Credential Vault: Secure credential injection for sandbox outbound requests without exposing real secrets to workloads. See Credential Vault.
• 🏰 Strong Isolation: Supports secure container runtimes like gVisor, Kata Containers, and Firecracker microVM for enhanced isolation between sandbox workloads and the host. See Secure Container Runtime Guide for details.

Official Container Images

OpenSandbox release images are published under the same component name in three official registries:

• Docker Hub: docker.io/opensandbox/<component>
• GitHub Container Registry: ghcr.io/opensandbox-group/opensandbox/<component>
• Alibaba Cloud Container Registry: sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/<component>

Tagged release images are signed keylessly with Cosign and include provenance attestations. Pin production images by digest and follow the release verification guide to verify the image against the OpenSandbox GitHub Actions identity before deployment.

SDKs

Pick your language:

Python

pip install opensandbox

Java/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/opensandbox

C#/.NET

dotnet add package Alibaba.OpenSandbox

Go

go get github.com/alibaba/OpenSandbox/sdks/sandbox/go

CLI

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

MCP

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.

Getting Started

Requirements:

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

Install and Configure the Sandbox Server

uvx opensandbox-server init-config ~/.sandbox.toml --example docker

uvx opensandbox-server

# Show help
# uvx opensandbox-server -h

Create a Sandbox and Execute Commands/Scripts

Install the Sandbox SDK

uv pip install opensandbox

Create a sandbox from an alpine image and execute commands and scripts.

import asyncio

from opensandbox import Sandbox
from opensandbox.models import WriteEntry

async def main() -> None:
    # 1. Create a sandbox from the alpine image
    sandbox = await Sandbox.create("alpine")

    try:
        # 2. Execute a shell command
        execution = await sandbox.commands.run("echo 'Hello OpenSandbox!'")
        print(execution.logs.stdout[0].text)

        # 3. Write a script file
        await sandbox.files.write_files([
            WriteEntry(
                path="/tmp/hello.sh",
                data="echo \"Hello $1\"\necho '2 + 2 =' $((2 + 2))",
                mode=755,
            )
        ])

        # 4. Read the file back
        content = await sandbox.files.read_file("/tmp/hello.sh")
        print(f"Content: {content}")

        # 5. Execute the script
        execution = await sandbox.commands.run("sh /tmp/hello.sh OpenSandbox")
        for log in execution.logs.stdout:
            print(log.text)

    finally:
        # 6. Cleanup the sandbox
        await sandbox.destroy()

if __name__ == "__main__":
    asyncio.run(main())

More Examples

OpenSandbox provides examples covering SDK usage, agent integrations, browser automation, and training workloads. 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 - Example integration for running OpenSandbox workloads on Kubernetes with kubernetes-sigs/agent-sandbox.
• Volumes — Docker PVC / named volumes, Docker OSSFS, Kubernetes PVC: persistent and shared storage patterns.

🤖 Coding Agent Integrations

• Coding CLIs — Claude Code, Gemini CLI, OpenAI Codex CLI, OpenCode, Qwen Code, Kimi CLI: run each 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.
• openclaw - Launch an OpenClaw Gateway inside a sandbox.

🌐 Browser and Desktop Environments

• chrome - Chromium sandbox with VNC and DevTools access for automation and 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.

🧠 Training and Evaluation

• harbor-evaluation - Run a Harbor agent evaluation on OpenSandbox, one sandbox per trial.

For more details, please refer to the examples documentation.

Documentation

• Architecture – Overall architecture & design philosophy
• Credential Vault - Credential Vault credential injection guide
• Release Verification - Release signing and artifact verification
• oseps/README.md – OpenSandbox Enhancement Proposals
• SDK - sandbox lifecycle, command execution, and file operations
  • Java/Kotlin
  • Python
  • JavaScript/TypeScript
  • C#/.NET
  • Go
• cli/README.md - OpenSandbox CLI installation and command reference
• sdks/mcp/sandbox/python/README.md - MCP server installation and client setup
• 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
• ROADMAP.md - Lightweight project roadmap and planning process

License

This project is open source under the Apache 2.0 License.

Roadmap

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

Contact and Discussion

• Issues: Submit bugs, feature requests, or design discussions through GitHub Issues
• Discord: Join the OpenSandbox Discord community
• DingTalk: Join the OpenSandbox technical discussion group