Skip to main content

​
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

​
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
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:

​
Python SDK

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

​
Installation

pip install opensandbox

​
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

​
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

​
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

​
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

  • 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
  • Verify Docker is installed: docker --version
  • Ensure Docker daemon is running: docker ps
  • Check Docker socket permissions: ls -la /var/run/docker.sock
  • Verify kubeconfig path is correct in ~/.sandbox.toml
  • Test kubectl access: kubectl get nodes
  • Ensure the opensandbox namespace exists: kubectl get namespace opensandbox

Build docs developers (and LLMs) love

Get started for freeTalk to us