Docker Runtime Setup

The Docker runtime is the production-ready backend for OpenSandbox Server, providing containerized sandbox environments with flexible networking options and comprehensive security controls.

Prerequisites

Before deploying with Docker runtime, ensure you have:

Docker Engine 20.10+ installed and running
Python 3.10+ for the OpenSandbox server
uv package manager (recommended) or pip
Operating System: Linux, macOS, or Windows with WSL2

Installation

Install OpenSandbox Server

Install the server package from PyPI:

uv pip install opensandbox-server

For source development, clone the repository and run uv sync inside server/.

Initialize Configuration

Generate a Docker configuration file:

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

This creates a basic Docker runtime configuration at ~/.sandbox.toml.

Configure Runtime Settings

Edit ~/.sandbox.toml to customize your deployment. See Configuration Options below.

Start the Server

Launch the server with your configuration:

opensandbox-server

The server will start at http://0.0.0.0:8080 by default.

Verify Health

Check that the server is running:

curl http://localhost:8080/health

Expected response:

{"status": "healthy"}

Configuration Options

Basic Docker Configuration

Minimal configuration for Docker runtime:

[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"

Network Modes

Docker runtime supports two networking modes:

Host Mode

Containers share the host network stack for maximum performance:

[docker]
network_mode = "host"  # Only one sandbox instance at a time

Characteristics:

Direct port access without NAT
Best performance
Only one sandbox per port
Endpoint format: http://{domain}/{sandbox_id}/{port}

Bridge Mode

Isolated container networking with HTTP routing:

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

Characteristics:

Network isolation between containers
Multiple sandboxes can use the same port
Built-in HTTP routing support
Endpoint format varies by ingress configuration

Security Hardening

Apply security controls to Docker containers:

[docker]
# Drop dangerous capabilities
drop_capabilities = [
  "AUDIT_WRITE",
  "MKNOD",
  "NET_ADMIN",
  "NET_RAW",
  "SYS_ADMIN",
  "SYS_MODULE",
  "SYS_PTRACE",
  "SYS_TIME",
  "SYS_TTY_CONFIG"
]

# Block privilege escalation
no_new_privileges = true

# AppArmor profile (when available)
apparmor_profile = ""  # e.g., "docker-default"

# Limit fork bombs
pids_limit = 512  # Set to null to disable

# Seccomp profile
seccomp_profile = ""  # Empty uses Docker default

Refer to Docker container security documentation for more details.

Network Policy with Egress Sidecar

Control outbound network traffic with egress policies:

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

[egress]
image = "opensandbox/egress:v1.0.1"

Requirements:

Only supported in bridge mode
Egress image must be configured when using networkPolicy
Automatically disabled for host mode

Example Request:

{
  "image": {"uri": "python:3.11-slim"},
  "entrypoint": ["python", "-m", "http.server", "8000"],
  "timeout": 3600,
  "resourceLimits": {"cpu": "500m", "memory": "512Mi"},
  "networkPolicy": {
    "defaultAction": "deny",
    "egress": [
      {"action": "allow", "target": "pypi.org"},
      {"action": "allow", "target": "*.python.org"}
    ]
  }
}

Advanced Docker Settings

[docker]
# Docker API timeout (seconds)
api_timeout = 300  # Default: 180

# Host IP for bridge-mode endpoints (when server runs in container)
host_ip = "10.57.1.91"

Ingress Configuration

Configure how clients access sandboxes:

Direct Mode (Default)

[ingress]
mode = "direct"  # Required for Docker runtime

Clients connect directly to sandboxes. No external gateway required.

Gateway Mode

[ingress]
mode = "gateway"

[ingress.gateway]
address = "*.example.com"  # Wildcard domain or IP[:port]

[ingress.gateway.route]
mode = "wildcard"  # wildcard | uri | header

Routing Modes:

Wildcard: <sandbox-id>-<port>.example.com/path/to/request
URI: 10.0.0.1:8000/<sandbox-id>/<port>/path/to/request
Header: gateway.example.com with header OpenSandbox-Ingress-To: <sandbox-id>-<port>

Storage Configuration

Control host path access for bind mounts:

[storage]
# Allowlist of host path prefixes for bind mounts
# Empty list allows all paths (not recommended for production)
allowed_host_paths = ["/data/opensandbox", "/tmp/sandbox"]

Environment Variables

Override configuration with environment variables:

Variable	Description
`SANDBOX_CONFIG_PATH`	Override config file location
`DOCKER_HOST`	Docker daemon URL (e.g., `unix:///var/run/docker.sock`)
`PENDING_FAILURE_TTL`	TTL for failed pending sandboxes in seconds (default: 3600)

Example: Create a Sandbox

Once the server is running, create a sandbox:

curl -X POST "http://localhost:8080/v1/sandboxes" \
  -H "OPEN-SANDBOX-API-KEY: your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {"uri": "python:3.11-slim"},
    "entrypoint": ["python", "-m", "http.server", "8000"],
    "timeout": 3600,
    "resourceLimits": {
      "cpu": "500m",
      "memory": "512Mi"
    },
    "env": {"PYTHONUNBUFFERED": "1"},
    "metadata": {
      "team": "backend",
      "project": "api-testing"
    }
  }'

Get Started

Core Concepts

Deployment

SDKs

Components

Use Cases

Operations

Prerequisites

Installation

Configuration Options

Basic Docker Configuration

Network Modes

Host Mode

Bridge Mode

Security Hardening

Network Policy with Egress Sidecar

Advanced Docker Settings

Ingress Configuration

Direct Mode (Default)

Gateway Mode

Storage Configuration

Environment Variables

Example: Create a Sandbox

Troubleshooting

Server Won’t Start

Connection Refused

Network Policy Not Working

Next Steps

​Prerequisites

​Installation

​Configuration Options

​Basic Docker Configuration

​Network Modes

​Host Mode

​Bridge Mode

​Security Hardening

​Network Policy with Egress Sidecar

​Advanced Docker Settings

​Ingress Configuration

​Direct Mode (Default)

​Gateway Mode

​Storage Configuration

​Environment Variables

​Example: Create a Sandbox

​Troubleshooting

​Server Won’t Start

​Connection Refused

​Network Policy Not Working

​Next Steps

Prerequisites

Installation

Configuration Options

Basic Docker Configuration

Network Modes

Host Mode

Bridge Mode

Security Hardening

Network Policy with Egress Sidecar

Advanced Docker Settings

Ingress Configuration

Direct Mode (Default)

Gateway Mode

Storage Configuration

Environment Variables

Example: Create a Sandbox

Troubleshooting

Server Won’t Start

Connection Refused

Network Policy Not Working

Next Steps