README

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

| 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

bash
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

bash
uv pip install opensandbox


Create a sandbox from an alpine image and execute commands and scripts.

python
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 = aw