OpenSandbox README

The project's README from github.com/opensandbox-group/OpenSandbox. As one markdown file: README.md.

OpenSandbox logo

OpenSandbox

opensandbox-group%2FOpenSandbox | Trendshift

Stars OpenSSF Best Practices CNCF Landscape Discord DingTalk E2E Status Kubernetes nightly build status

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

Official Container Images

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

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

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:

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.

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())

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

🧠 Training and Evaluation

For more details, please refer to the examples documentation.

Project Structure

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

Documentation

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

Star History

Star History Chart

OpenSandbox (opensandbox-group/OpenSandbox)

Searching Database…

15.9K ·GitHub
OpenSandbox
Что это такое?OpenSandbox — универсальная платформа песочниц для ИИ-приложений. Она предоставляет SDK на нескольких языках, единые API для песочниц и среды выполнения на Docker и Kubernetes. Подходит для сценариев: агенты для написания кода, агенты с графическим интерфейсом, оценка агентов, выполнение кода ИИ и обучение с подкреплением (RL).
Это библиотека, которую я импортирую, или сервер, который я запускаю?И то, и другое: сервер жизненного цикла песочниц на Python FastAPI, который можно развернуть локально через Docker или в большом масштабе на Kubernetes, а также SDK для Python, Java/Kotlin, JS/TS, C#/.NET и Go, CLI osb и MCP-сервер. Всё это работает с этим сервером.
Как запустить песочницу?Установите Docker и Python 3.10+, запустите сервер OpenSandbox, затем с помощью SDK Code Interpreter создайте песочницу и выполните в ней команды или код. Тот же порядок работы масштабируется до среды выполнения на Kubernetes для распределённого планирования.
Нужен ли Kubernetes, чтобы попробовать?Нет, для локального запуска песочниц достаточно одного Docker. Kubernetes нужен только для высокопроизводительной распределённой среды выполнения большого масштаба.
Насколько песочницы изолированы от хост-машины?Помимо стандартных контейнеров Docker и Kubernetes, OpenSandbox поддерживает защищённые среды выполнения: gVisor, Kata Containers и микровиртуальные машины Firecracker. Они обеспечивают более надёжную изоляцию между рабочими нагрузками песочниц и хост-машиной.
Как сервис хранит в безопасности API-ключи и секреты внутри песочницы?Credential Vault подставляет учётные данные в исходящие запросы песочницы, не раскрывая настоящие значения секретов коду, который работает внутри рабочей нагрузки.
Какие агенты для написания кода могут подключаться через MCP-сервер?MCP-сервер предоставляет создание песочниц, выполнение команд и операции с файлами клиентам, поддерживающим MCP, например Claude Code и Cursor.
Могу ли я запускать внутри песочницы агентов с графическим интерфейсом или работающих в браузере?Да, готовые примеры включают песочницу Chromium с доступом по VNC и DevTools, автоматизацию браузера Playwright без графического интерфейса и полноценный рабочий стол, доступный по VNC.
Где публикуются официальные образы контейнеров?Образы публикуются в Docker Hub, GitHub Container Registry и Alibaba Cloud Container Registry. Они подписаны Cosign без использования ключей и поставляются с аттестациями происхождения (provenance).
Что делает CLI osb?osb — терминальный CLI OpenSandbox для типичного рабочего процесса с песочницами: создание песочниц, запуск команд, перемещение файлов, просмотр диагностики и управление политиками исходящего трафика среды выполнения.
What are similar projects?daytona, strix, substrate, solari-cookbook, ax, smolvm, astron-rpa, labtether
Which topics is it in?code-execution, microvm, secrets, vnc, fastapi, playwright, reinforcement-learning, sandbox, browser-automation, distributed-systems, kubernetes, sdk
Creator
opensandbox-group
Size
109.2 MB
Stars
15.9K
Updated
CommitOct 18Releaserelease-1.1.1Oct 09
Age
10mo
Commits · 90 Days