A general-purpose sandbox platform for AI applications, offering multi-language SDKs, unified sandbox APIs, and Docker/Kubernetes runtimes. Ideal for scenarios like Coding Agents, GUI Agents, Agent Evaluation, AI Code Execution, and RL Training.

Features

Multi-language SDK Support: Python, JavaScript/TypeScript, Java/Kotlin, and Go client SDKs
Unified Sandbox API: Consistent interface for sandbox lifecycle, command execution, and file operations
Multiple Runtime Options: Docker and Kubernetes runtime support
Security Hardening: Built-in security features including capability dropping, privilege escalation prevention, and resource limits
Flexible Configuration: Support for various network modes, resource constraints, and security profiles
Code Interpreter: Pre-built images with Python, Node.js, Java, and Go kernel support

Quick Start

Prerequisites

Docker Engine (required for Docker runtime)
Docker Compose
Sufficient permissions to access Docker socket

Note for macOS users using Colima: You need to set the DOCKER_HOST environment variable before starting OpenSandbox:
export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"

Deployment

Copy the environment file and configure as needed:
```
cp .env.example .env
```
Edit config.toml to set your API key:
```
[server]
api_key = "your-secret-api-key-change-this"
```
IMPORTANT: Change the default API key in production!
Start the service:
```
docker compose up -d
```
Verify the service is running:
```
curl http://localhost:8080/health
```
You should receive a successful health check response.

Configuration

Environment Variables

Key environment variables (see .env.example for full list):

Variable	Description	Default
`OPENSANDBOX_SERVER_VERSION`	OpenSandbox server image version	`v1.0.5`
`OPENSANDBOX_SERVER_PORT_OVERRIDE`	Host port mapping	`8080`
`DOCKER_HOST`	Docker socket path	`unix:///var/run/docker.sock`
`OPENSANDBOX_SERVER_CPU_LIMIT`	CPU cores limit	`2.0`
`OPENSANDBOX_SERVER_MEMORY_LIMIT`	Memory limit	`2G`

Server Configuration

The main configuration is in config.toml. Key sections:

[server]: HTTP server settings (host, port, log level, API key)
[runtime]: Runtime type and execd image configuration
[docker]: Docker-specific settings including network mode and security options

Network Modes

bridge (recommended): Containers have isolated networks, supports multiple sandboxes
host: Containers share host network, only one sandbox instance at a time

Security Features

Capability dropping: Removes dangerous Linux capabilities from containers
Privilege escalation prevention: Blocks privilege escalation inside containers
Process limits: Controls maximum number of processes per sandbox
AppArmor/Seccomp profiles: Optional security profiles (leave empty for Docker defaults)

Usage

Basic Sandbox Creation (Python SDK)

from opensandbox import Sandbox
from datetime import timedelta

# Create a sandbox with code interpreter
sandbox = await Sandbox.create(
    "opensandbox/code-interpreter:v1.0.1",
    entrypoint="/opt/opensandbox/code-interpreter.sh",
    env={"PYTHON_VERSION": "3.11"},
    timeout=timedelta(minutes=10)
)

async with sandbox:
    # Execute Python code
    result = await sandbox.execute(
        "python",
        "-c",
        "print('Hello from OpenSandbox!')"
    )
    print(result.stdout)

API Authentication

All API requests require the X-API-Key header with the key configured in config.toml:

curl -H "X-API-Key: your-secret-api-key-change-this" \
     http://localhost:8080/sandboxes

Pre-built Images

OpenSandbox provides several pre-built sandbox images:

opensandbox/code-interpreter: Multi-language code interpreter (Python, Node.js, Java, Go)
opensandbox/vscode: VS Code Server environment
opensandbox/desktop: Full desktop environment with VNC support
opensandbox/playwright: Browser automation with Playwright
opensandbox/chrome: Chromium browser environment

Ports

Port	Service	Description
8080	OpenSandbox Server	HTTP API server

Data Persistence

opensandbox_data: Server data and state

Health Check

The service includes a built-in health check endpoint at /health:

curl http://localhost:8080/health

Security Considerations

Docker Socket Access

This service requires access to the Docker socket (/var/run/docker.sock) to create and manage sandbox containers. This is a high-privilege operation.

Security implications:

Containers with Docker socket access can potentially control the host system
Only deploy in trusted environments
Consider using Docker-in-Docker or rootless Docker for additional isolation in production

Alternatives:

Use Kubernetes runtime instead of Docker runtime (requires Kubernetes cluster)
Deploy with restricted user permissions and resource quotas

API Key Security

Never use the default API key in production
Store API keys securely (e.g., using Docker secrets, environment variables from secret managers)
Rotate API keys regularly
Limit network exposure (use firewall rules, reverse proxy)

Resource Limits

Always configure appropriate CPU and memory limits to prevent resource exhaustion:

deploy:
  resources:
    limits:
      cpus: '2.0'
      memory: 2G

Troubleshooting

Docker Socket Connection Issues

Error: Failed to initialize Docker service

Solution:

Ensure Docker Desktop/Engine is running
On macOS with Colima: Set DOCKER_HOST=unix://${HOME}/.colima/default/docker.sock
Check Docker socket permissions: ls -l /var/run/docker.sock

Health Check Failing

Error: Health check timeout

Solution:

Check container logs: docker compose logs opensandbox-server
Verify the service started successfully: docker compose ps
Increase start_period in docker-compose.yaml if the service needs more time to initialize

Sandbox Creation Failures

Error: Failed to create sandbox

Solution:

Ensure the execd image is accessible: docker pull opensandbox/execd:v1.0.5
Check available system resources (CPU, memory, disk space)
Review server logs for detailed error messages

License

This project is part of the OpenSandbox suite. See the main LICENSE file for details.

References

Support

For issues and questions: