Skip to content
This repository was archived by the owner on May 9, 2026. It is now read-only.
BranchesTags

Repository files navigation

OpenSandbox logo

OpenSandbox

alibaba%2FOpenSandbox | Trendshift

GitHub starsAsk DeepWikilicensePyPI versionnpm versionCNCF LandscapeDingTalkE2E StatusE2E Status

Documentation | 中文文档

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.

OpenSandbox is now listed in the CNCF Landscape.

Features

  • Multi-language SDKs: Provides sandbox SDKs in Python, Java/Kotlin, JavaScript/TypeScript, C#/.NET, Go.
  • 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.
  • 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.

SDKs

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 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 Code Interpreter and Execute Commands/Codes

Install the Code Interpreter SDK

uv pip install opensandbox-code-interpreter

Create a sandbox and execute commands and codes.

importasynciofromdatetimeimporttimedeltafromcode_interpreterimportCodeInterpreter, SupportedLanguagefromopensandboximportSandboxfromopensandbox.modelsimportWriteEntryasyncdefmain() ->None:
# 1. Create a sandboxsandbox=awaitSandbox.create(
"opensandbox/code-interpreter:v1.0.2",
entrypoint=["/opt/opensandbox/code-interpreter.sh"],
env={"PYTHON_VERSION": "3.11"},
timeout=timedelta(minutes=10),
)
asyncwithsandbox:
# 2. Execute a shell commandexecution=awaitsandbox.commands.run("echo 'Hello OpenSandbox!'")
print(execution.logs.stdout[0].text)
# 3. Write a fileawaitsandbox.files.write_files([
WriteEntry(path="/tmp/hello.txt", data="Hello World", mode=644)
])
# 4. Read a filecontent=awaitsandbox.files.read_file("/tmp/hello.txt")
print(f"Content: {content}") # Content: Hello World# 5. Create a code interpreterinterpreter=awaitCodeInterpreter.create(sandbox)
# 6. Execute Python code (single-run, pass language directly)result=awaitinterpreter.codes.run(
""" import sys print(sys.version) result = 2 + 2 result """,
language=SupportedLanguage.PYTHON,
)
print(result.result[0].text) # 4print(result.logs.stdout[0].text) # 3.11.14# 7. Cleanup the sandboxawaitsandbox.kill()
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

🤖 Coding Agent Integrations

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

🧠 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

DirectoryDescription
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/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 [2026.03]

SDK

  • Sandbox client connection pool - Client-side sandbox connection pool management, providing pre-provisioned sandboxes to obtain an environment at X ms. Implemented for Kotlin SandboxPool and documented in the Kotlin SDK README. Related PRs: #301, #393, #617.
  • Go SDK - Go client SDK for sandbox lifecycle management, command execution, and file operations. See the Go SDK README. Related PRs: #597, #683, #707.

Sandbox Runtime

Deployment

Contact and Discussion

Star History

Star History Chart

About

Moved VSCode Remote project to >>> https://github.com/WaterPistolAI/THON

open-sandbox.ai

Resources

Readme
License

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

2 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages