← Discover MCPs and Agents
O
AgentAI & MLGitHub

OpenSandbox

Secure, Fast, and Extensible Sandbox runtime for AI agents.

Links

Repository

README

From the repo.

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. It gives Coding Agents, GUI Agents, Agent Evaluation, AI Code Execution, and RL Training workloads a secure, scalable place to run — with the same API from a laptop to a large cluster.

Features

  • 🧩 SDKs, CLI, and MCP: Native SDKs for Python, Java/Kotlin, TypeScript, C#/.NET, and Go, plus the osb CLI and an MCP server — one API surface for sandbox creation, command execution, and file operations. See SDKs, CLI, and MCP.
  • 📜 Open Protocol: Sandbox lifecycle and execution APIs are defined as public OpenAPI contracts, so custom runtimes can plug in without changing client code. See API specs.
  • 🚀 Sandbox Runtime and Environments: Docker and Kubernetes runtimes behind the same SDK calls, with built-in Command, Filesystem, and Code Interpreter environments — covering Coding Agents (e.g., Claude Code), browser automation (Chrome, Playwright), and desktop environments (VNC, VS Code). See Kubernetes runtime.
  • ⚡ Hybrid Deployment: Mix long-running, Kubernetes-native container workloads with short-lived microVM sandboxes in one cluster. Pre-warmed, Firecracker-backed pools give constant-time admission and ~80ms startup; FastSandbox pause/resume checkpoints state to the artifact store and releases all compute, resuming on any host. See Fast Sandbox.
  • 🚦 Network Policy and Credential Vault: Unified ingress gateway with multiple routing strategies, per-sandbox egress controls, and secure credential injection that keeps real secrets away from sandbox workloads. See Ingress Gateway, egress controls, and Credential Vault.
  • 🏰 Strong Isolation: Run workloads under gVisor, Kata Containers, or Firecracker microVMs for strong isolation from the host. See the Secure Container Runtime Guide.

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

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

🧠 Training and Evaluation

For more details, please refer to the examples documentation.

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

Collected info

  • ★ 15,451 stars
  • ⎇ 1,417 forks
  • Language: Python
  • Source updated: 9/22/2026