Quick Start

OpenSandbox is a general-purpose sandbox platform for AI applications, offering multi-language SDKs, unified sandbox APIs, and Docker/Kubernetes runtimes.

Prerequisites

• Docker Engine 20.10+ (for local execution)
• Python 3.10+ (for the server and Python SDK)
• uv (recommended) or pip

1. Start the Server

# Generate a starter config
uvx opensandbox-server init-config ~/.sandbox.toml --example docker

# Start the server
uvx opensandbox-server

Verify the server is running:

curl http://127.0.0.1:8080/health
# → {"status": "healthy"}

2. Install an SDK

Python

pip install opensandbox

JavaScript

npm install @alibaba-group/opensandbox

Go

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

C#

dotnet add package Alibaba.OpenSandbox

For Kotlin/Java, see Installation.

3. Create and Use a Sandbox

This example uses the sandbox SDK and a standard Python image. If the server has an API key configured, set OPEN_SANDBOX_API_KEY in your client environment.

import asyncio
from datetime import timedelta

from opensandbox import Sandbox
from opensandbox.config import ConnectionConfig
from opensandbox.models import WriteEntry


async def main() -> None:
    sandbox = await Sandbox.create(
        "python:3.12",
        timeout=timedelta(minutes=10),
        connection_config=ConnectionConfig(
            domain="localhost:8080",
        ),
    )
    try:
        execution = await sandbox.commands.run("python -c 'print(1 + 1)'")
        for output in execution.logs.stdout:
            print(output.text)

        await sandbox.files.write_files([
            WriteEntry(path="/tmp/hello.txt", data="Hello World", mode=644)
        ])
        print(await sandbox.files.read_file("/tmp/hello.txt"))
    finally:
        await sandbox.destroy()


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

destroy() terminates the remote sandbox and closes local SDK resources. Closing the client alone does not terminate the remote sandbox.

4. Try the CLI

pip install opensandbox-cli

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 --argv -- python -c "print(1 + 1)"
osb sandbox kill <sandbox-id> -o json

Next Steps

• Installation — Detailed installation for all SDKs and runtimes
• Configuration — Server configuration reference
• Architecture — How OpenSandbox works under the hood
• Guides — Client Pool, tracing, diagnostics, and security features
• SDK capability matrix — Check support before choosing a language
• Examples — Real-world usage examples