OpenSandbox

An Agentic AI Foundation (AAIF) Project

---

Run AI agents in sandboxes on your own infrastructure.

OpenSandbox gives AI applications isolated environments to execute code, run commands, manage files, and operate browsers or desktops. Start locally with Docker and deploy on Kubernetes through a unified sandbox API.

Quick Start · Examples · Documentation · Fast Sandbox

Features

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

Examples

Explore examples by what you want your agent to do. Runnable source code lives in examples/.

See the full example catalog for more coding agents, framework integrations, remote development environments, Kubernetes deployment, and storage patterns.

SDKs

Pick your language:

pip install opensandbox

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

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

npm install @alibaba-group/opensandbox

dotnet add package Alibaba.OpenSandbox

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.

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.

Documentation

• Website — Project homepage and documentation site
• Architecture — System design and component responsibilities
• Deployment Guide — Kubernetes installation and operations
• Server Configuration — Runtime and server settings
• SDK Reference — Language guides and capability coverage
• CLI Guide — Installation and command reference
• MCP Integration — Setup for MCP-capable clients
• API Reference — Sandbox lifecycle and execution contracts
• Credential Vault — Outbound credential injection
• Release Verification — Image signing and artifact verification
• Enhancement Proposals — Design proposals and technical direction
• Roadmap — Project priorities and planning

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

About

OpenSandbox is a project of the Agentic AI Foundation (AAIF).

Licensed under the Apache 2.0 License.