OpenSandbox

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

Feature	What it enables	Learn more
Fast Sandbox runtime	Fast, high-density sandboxes on Kubernetes. Firecracker creation: 64 ms P50 (serial) / 125.4 ms P99 (10 concurrent). Firecracker sandboxes support pause/resume with memory and disk state preserved.	Integration · Performance · Pause/resume
Agent working environments	Execute commands, manage files, and run code with built-in APIs. Integration examples show how to run coding agents, browsers, and desktops inside sandboxes.	Examples
Network access control	Route inbound traffic through a unified ingress gateway and control outbound access with per-sandbox egress policies.	Ingress · Egress
Credential Vault	Let agents call external services without exposing real credentials to sandbox workloads.	Credential Vault
Local to cluster	Start with Docker and deploy on Kubernetes through a unified lifecycle API. Resource pools and batch creation support agent evaluation and RL training workloads.	Kubernetes runtime
SDKs, CLI, and MCP	Integrate with Python, Java/Kotlin, TypeScript/JavaScript, C#/.NET, or Go SDKs. Use osb from the terminal or connect agents through MCP.	SDKs · CLI · MCP
Extensible sandbox protocol	Build custom runtime integrations against defined sandbox lifecycle and execution APIs.	API specs

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

Use case	What you can build	Examples
Coding agents	Run coding agents in isolated environments to edit files, execute commands, and complete development tasks.	Claude Code · Codex CLI · DeerFlow
Code execution and data analysis	Execute model-generated code and work with results through the Code Interpreter SDK.	Code Interpreter
Browser and desktop automation	Automate web interactions and testing, or give agents access to a desktop environment.	Playwright · Chrome · Desktop
Agent evaluation	Run evaluations with a separate sandbox for each trial.	Harbor Evaluation

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:

This is the beginning of the README. Read the rest at the original. Read the full README ↗