Installation

This guide covers installation for the OpenSandbox server and all available SDKs.

System Requirements

Server Requirements

Python: 3.10 or higher
Package Manager: uv (recommended) or pip
Runtime Backend:
- Docker Engine 20.10+ (for Docker runtime)
- Kubernetes 1.21+ (for Kubernetes runtime)
Operating System: Linux, macOS, or Windows with WSL2

SDK Requirements

SDK-specific requirements are listed in each section below.

OpenSandbox Server

The OpenSandbox server is a FastAPI-based service that manages the lifecycle of containerized sandboxes.

Installation

uv pip install opensandbox-server

pip install opensandbox-server

# Clone the repository
git clone https://github.com/alibaba/OpenSandbox.git
cd OpenSandbox/server

# Install dependencies
uv sync

# Copy configuration
cp example.config.toml ~/.sandbox.toml

# Run the server
uv run python -m src.main

Configuration

The server uses a TOML configuration file to select and configure the underlying runtime.

Initialize Configuration

Generate a configuration file with example presets:

opensandbox-server init-config ~/.sandbox.toml --example docker

opensandbox-server init-config ~/.sandbox.toml --example k8s

# Generate a full schema-driven skeleton without defaults
opensandbox-server init-config ~/.sandbox.toml

Use --force to overwrite an existing configuration file.

Configuration Examples

Docker Runtime with Host Networking

~/.sandbox.toml

[server]
host = "0.0.0.0"
port = 8080
log_level = "INFO"
api_key = "your-secret-api-key-change-this"

[runtime]
type = "docker"
execd_image = "opensandbox/execd:v1.0.6"

[docker]
network_mode = "host"  # Containers share host network

Docker Runtime with Bridge Networking

~/.sandbox.toml

[server]
host = "0.0.0.0"
port = 8080
log_level = "INFO"
api_key = "your-secret-api-key-change-this"

[runtime]
type = "docker"
execd_image = "opensandbox/execd:v1.0.6"

[docker]
network_mode = "bridge"  # Isolated container networking

Kubernetes Runtime

~/.sandbox.toml

[runtime]
type = "kubernetes"
execd_image = "opensandbox/execd:v1.0.5"

[kubernetes]
kubeconfig_path = "~/.kube/config"
namespace = "opensandbox"
workload_provider = "batchsandbox"  # or "agent-sandbox"
informer_enabled = true
informer_resync_seconds = 300
informer_watch_timeout_seconds = 60

Security Hardening

~/.sandbox.toml

[docker]
# Drop dangerous capabilities and block privilege escalation
drop_capabilities = [
  "AUDIT_WRITE", "MKNOD", "NET_ADMIN", "NET_RAW", 
  "SYS_ADMIN", "SYS_MODULE", "SYS_PTRACE", "SYS_TIME", "SYS_TTY_CONFIG"
]
no_new_privileges = true
apparmor_profile = ""  # e.g. "docker-default" when AppArmor is available
pids_limit = 512       # set to null to disable
seccomp_profile = ""   # path or profile name; empty uses Docker default

Network Policy with Egress Sidecar

~/.sandbox.toml

[runtime]
type = "docker"
execd_image = "opensandbox/execd:v1.0.6"

[egress]
image = "opensandbox/egress:v1.0.1"  # Required when using networkPolicy

Starting the Server

Once configured, start the server:

opensandbox-server

# Or specify a custom config file
opensandbox-server --config /path/to/config.toml

# Show help
opensandbox-server -h

Verify the server is running:

curl http://localhost:8080/health

Expected response:

{"status": "healthy"}

API Documentation

Once running, interactive API documentation is available at:

Swagger UI: http://localhost:8080/docs
ReDoc: http://localhost:8080/redoc

Python SDK

The Python SDK provides async and sync APIs for interacting with OpenSandbox.

Installation

pip install opensandbox

uv add opensandbox

# Install with code interpreter support
pip install opensandbox opensandbox-code-interpreter

Requirements

Python 3.10+
httpx (installed automatically)

Quick Verification

import asyncio
from opensandbox import Sandbox
from opensandbox.config import ConnectionConfig

async def main():
    config = ConnectionConfig(
        domain="localhost:8080",
    )
    
    sandbox = await Sandbox.create(
        "ubuntu",
        connection_config=config
    )
    
    async with sandbox:
        execution = await sandbox.commands.run("echo 'Hello OpenSandbox!'")
        print(execution.logs.stdout[0].text)
        await sandbox.kill()

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

Java/Kotlin SDK

The Java/Kotlin SDK provides sandbox lifecycle management, command execution, and file operations.

Installation

Maven

pom.xml

<dependency>
    <groupId>io.github.alibaba.opensandbox</groupId>
    <artifactId>opensandbox-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle (Kotlin DSL)

build.gradle.kts

dependencies {
    implementation("io.github.alibaba.opensandbox:opensandbox-sdk:1.0.0")
}

Gradle (Groovy)

build.gradle

dependencies {
    implementation 'io.github.alibaba.opensandbox:opensandbox-sdk:1.0.0'
}

Requirements

Java 11+
Kotlin 1.8+ (for Kotlin projects)

Build from Source

cd sdks/sandbox/kotlin
./gradlew build

JavaScript/TypeScript SDK

The JavaScript/TypeScript SDK provides full-featured sandbox interaction for Node.js and browser environments.

Installation

npm install @alibaba-group/opensandbox

yarn add @alibaba-group/opensandbox

pnpm add @alibaba-group/opensandbox

Requirements

Node.js 16+
TypeScript 4.5+ (for TypeScript projects)

Quick Verification

import { Sandbox, ConnectionConfig } from '@alibaba-group/opensandbox';

const config = new ConnectionConfig({
  domain: 'localhost:8080',
});

const sandbox = await Sandbox.create('ubuntu', config);
const execution = await sandbox.commands.run("echo 'Hello OpenSandbox!'");
console.log(execution.logs.stdout[0].text);
await sandbox.kill();

C#/.NET SDK

The C#/.NET SDK provides sandbox management for .NET applications.

Installation

dotnet add package OpenSandbox.Sdk

Install-Package OpenSandbox.Sdk

<PackageReference Include="OpenSandbox.Sdk" Version="1.0.0" />

Requirements

.NET 6.0+

Quick Verification

using OpenSandbox;
using OpenSandbox.Config;

var config = new ConnectionConfig
{
    Domain = "localhost:8080"
};

var sandbox = await Sandbox.CreateAsync("ubuntu", config);
var execution = await sandbox.Commands.RunAsync("echo 'Hello OpenSandbox!'");
Console.WriteLine(execution.Logs.Stdout[0].Text);
await sandbox.KillAsync();

Code Interpreter SDKs

For advanced code execution capabilities, install the Code Interpreter SDKs:

pip install opensandbox-code-interpreter

// Maven
<dependency>
    <groupId>io.github.alibaba.opensandbox</groupId>
    <artifactId>code-interpreter-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

// Gradle
implementation("io.github.alibaba.opensandbox:code-interpreter-sdk:1.0.0")

npm install @alibaba-group/opensandbox-code-interpreter

dotnet add package OpenSandbox.CodeInterpreter

Docker Images

OpenSandbox provides pre-built Docker images for common use cases:

opensandbox/execd:v1.0.6 - Execution daemon
opensandbox/code-interpreter:v1.0.1 - Code interpreter environment
opensandbox/egress:v1.0.1 - Egress control sidecar

Pull images before use:

docker pull opensandbox/execd:v1.0.6
docker pull opensandbox/code-interpreter:v1.0.1

Next Steps

Quickstart

Follow the quickstart guide to create your first sandbox

Configuration

Learn about advanced configuration options

Python SDK Guide

Explore Python SDK features in depth

Examples

Browse integration examples and use cases

Troubleshooting

Package installation fails

Ensure you’re using Python 3.10+ or the appropriate runtime version
Try upgrading pip: pip install --upgrade pip
For uv issues, ensure it’s up to date: pip install --upgrade uv

Docker runtime not found

Verify Docker is installed: docker --version
Ensure Docker daemon is running: docker ps
Check Docker socket permissions: ls -la /var/run/docker.sock

Kubernetes connection fails

Verify kubeconfig path is correct in ~/.sandbox.toml
Test kubectl access: kubectl get nodes
Ensure the opensandbox namespace exists: kubectl get namespace opensandbox

​Installation

​System Requirements

​Server Requirements

​SDK Requirements

​OpenSandbox Server

​Installation

​Configuration

​Initialize Configuration

​Configuration Examples

​Starting the Server

​API Documentation

​Python SDK

​Installation

​Requirements

​Quick Verification

​Java/Kotlin SDK

​Installation

​Maven

​Gradle (Kotlin DSL)

​Gradle (Groovy)

​Requirements

​Build from Source

​JavaScript/TypeScript SDK

​Installation

​Requirements

​Quick Verification

​C#/.NET SDK

​Installation

​Requirements

​Quick Verification

​Code Interpreter SDKs

​Docker Images

​Next Steps

Quickstart

Configuration

Python SDK Guide

Examples

​Troubleshooting

Installation

System Requirements

Server Requirements

SDK Requirements

OpenSandbox Server

Installation

Configuration

Initialize Configuration

Configuration Examples

Starting the Server

API Documentation

Python SDK

Installation

Requirements

Quick Verification

Java/Kotlin SDK

Installation

Maven

Gradle (Kotlin DSL)

Gradle (Groovy)

Requirements

Build from Source

JavaScript/TypeScript SDK

Installation

Requirements

Quick Verification

C#/.NET SDK

Installation

Requirements

Quick Verification

Code Interpreter SDKs

Docker Images

Next Steps

Troubleshooting