Run OpenSandbox Locally with Docker Runtime

The Docker runtime is the simplest way to run OpenSandbox locally and on a single host. It talks directly to the Docker daemon and manages sandbox containers, expiration timers, volumes, port mappings, optional egress sidecars, and OCI snapshots — all without a Kubernetes cluster. This makes it the default choice for local development, CI pipelines, and single-machine deployments where you need fast iteration and minimal infrastructure overhead.

Prerequisites

Requirement	Details
Docker Engine	20.10+
OpenSandbox server	Installed via `uv pip install opensandbox-server`
Operating system	Linux, macOS, or Windows with WSL2

Quick Setup

Generate a Docker config file

The init-config command scaffolds a ready-to-use TOML file for the Docker runtime.

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

Review and edit the generated config

Open ~/.sandbox.toml and verify the [docker] section matches your environment. In particular, set host_ip if the server itself runs inside a container.

[server]
host = "0.0.0.0"
port = 8080
api_key = "your-secret-api-key"

[log]
level = "INFO"

[runtime]
type = "docker"
execd_image = "opensandbox/execd:latest"

[docker]
network_mode = "bridge"
# Set to host IP or hostname when the server runs inside Docker
host_ip = "host.docker.internal"
drop_capabilities = ["AUDIT_WRITE", "MKNOD", "NET_ADMIN", "NET_RAW",
                     "SYS_ADMIN", "SYS_MODULE", "SYS_PTRACE",
                     "SYS_TIME", "SYS_TTY_CONFIG"]
no_new_privileges = true
# Increase for production to avoid thread exhaustion with many sandboxes
pids_limit = 4096

[ingress]
mode = "direct"

[egress]
image = "opensandbox/egress:latest"
mode = "dns+nft"

Start the server

opensandbox-server

# Or specify a different config path
opensandbox-server --config /path/to/sandbox.toml

Verify the server is healthy:

curl http://localhost:8080/health
# {"status": "healthy"}

Docker Configuration Reference

All Docker-specific settings live under the [docker] section of your TOML config.

Key	Default	Description
`network_mode`	`"host"`	Container network mode: `host`, `bridge`, or a custom Docker network name
`host_ip`	(unset)	Public host IP or hostname used to format sandbox endpoints in bridge mode
`drop_capabilities`	See example	Linux capabilities to drop from sandbox containers
`no_new_privileges`	`true`	Prevent containers from gaining new privileges via `setuid`/`setgid`
`pids_limit`	`4096`	Maximum number of PIDs per sandbox container (`null` to disable)

For production environments with many concurrent sandboxes, set pids_limit to 4096 or higher to avoid “can’t start new thread” errors. See issue #447 for details.

Network Modes

OpenSandbox supports two network modes for Docker-backed sandboxes. Choose the one that fits your deployment scenario.

Bridge mode (recommended)
Host mode

Bridge mode places each sandbox on an isolated Docker network. The Docker runtime maps only the execd proxy port (44772) and, optionally, port 8080. All other container ports are reached through the built-in execd reverse proxy.

[docker]
network_mode = "bridge"
host_ip = "127.0.0.1"

How endpoint routing works in bridge mode:

execd listens on container port 44772 and bundles a lightweight reverse proxy.
The Docker runtime binds a random host port to the container’s 44772 proxy port.
get_endpoint(port=X) returns {host_ip}:{host_proxy_port}/proxy/{X}.
HTTP, SSE, and WebSocket traffic all share that single host port — no additional port mappings needed.
For callers inside the same Docker network, use get_endpoint(resolve_internal=True) to receive the container IP directly.

Advantages: port conflict-free, many sandboxes per host, egress sidecar support, ingress gateway compatible.

Host mode shares the host network stack with each sandbox container. Sandbox ports are directly accessible on the host without port mapping.

[docker]
network_mode = "host"

How endpoint routing works in host mode:

get_endpoint(port=X) returns {host_ip}:{X} with no /proxy/ prefix.
The caller must know the exact port the sandbox is using, and the host must manage firewall rules per sandbox.

Limitations: each sandbox binds ports directly on the host, so running multiple sandboxes on the same machine requires non-overlapping port ranges. Egress sidecar network isolation is not available in host mode.Advantages: maximum network performance, zero proxy overhead.

Private Registry Access

To pull sandbox images from a private container registry, supply credentials either at sandbox creation time or globally in the config.

Per-sandbox (SDK)
Global config (TOML)

Pass image_auth_username and image_auth_password in the image field when creating a sandbox:

from opensandbox import Sandbox

sandbox = await Sandbox.create(
    image={
        "uri": "registry.example.com/myimage:latest",
        "imageAuthUsername": "my-user",
        "imageAuthPassword": "my-token",
    }
)

Set default registry credentials in [docker] for all sandboxes that don’t specify per-request credentials:

[docker]
network_mode = "bridge"
image_auth_username = "my-user"
image_auth_password = "my-token"

Resource Limits

CPU and memory limits are passed at sandbox creation time and enforced by the Docker runtime. Use Kubernetes-style resource strings.

Python SDK
REST API

from opensandbox import Sandbox

sandbox = await Sandbox.create(
    image={"uri": "python:3.11-slim"},
    resource_limits={
        "cpu": "2",        # 2 CPU cores
        "memory": "4Gi",   # 4 GiB RAM
    },
)

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" },
    "resourceLimits": {
      "cpu": "2",
      "memory": "4Gi"
    }
  }'

Resource key	Example values	Notes
`cpu`	`"500m"`, `"2"`	Millicores (`m`) or whole cores
`memory`	`"512Mi"`, `"4Gi"`	Binary suffixes (`Mi`, `Gi`)
`gpu`	`"1"`	GPU count; requires GPU-capable Docker runtime

Volume Mounts

The Docker runtime supports host bind mounts and named Docker volumes.

Host path bind mount
Named volume (PVC model)

Mount a host directory into the sandbox container:

sandbox = await Sandbox.create(
    image={"uri": "python:3.11-slim"},
    volumes=[{
        "type": "host",
        "hostPath": "/home/user/data",
        "mountPath": "/data",
    }],
)

Use a Docker named volume (mapped from the pvc volume model) for persistent storage across sandbox restarts:

sandbox = await Sandbox.create(
    image={"uri": "python:3.11-slim"},
    volumes=[{
        "type": "pvc",
        "name": "my-data-volume",
        "mountPath": "/data",
    }],
)

Egress Network Policy

When a sandbox is created with a networkPolicy, the Docker runtime attaches an egress sidecar container that shares the sandbox’s network namespace. The sidecar enforces FQDN-based allow/deny rules on all outbound traffic.

from opensandbox import Sandbox, NetworkPolicy, EgressRule

sandbox = await Sandbox.create(
    image={"uri": "python:3.11-slim"},
    network_policy=NetworkPolicy(
        default_action="deny",
        egress=[
            EgressRule(action="allow", target="*.pypi.org"),
            EgressRule(action="allow", target="*.github.com"),
        ],
    ),
)

Configure the egress sidecar image and mode in [egress]:

[egress]
image = "opensandbox/egress:latest"
mode = "dns+nft"   # dns | dns+nft (recommended for strict default-deny)

See Network Architecture for a full explanation of egress sidecar isolation.

Secure Container Runtimes

To add kernel-level isolation beyond standard Docker containers, configure a secure OCI runtime in [secure_runtime].

[secure_runtime]
type = "gvisor"          # gvisor | kata-qemu | kata-fc | kata-clh
oci_runtime_name = "runsc"  # must match the runtime name registered in Docker daemon

Then enable it at sandbox creation by passing secureRuntime: true in the request.

gVisor (runsc) does not support the iptables nat table required by the egress sidecar’s DNS interception. If you need both syscall isolation and FQDN egress control, use kata-qemu instead. See the Secure Container guide for the full compatibility matrix.

Running the Server in Docker

You can run the OpenSandbox server itself as a Docker container and have it manage other containers on the same host. Mount the Docker socket so the server can talk to the Docker daemon.

# docker-compose.yaml
services:
  opensandbox-server:
    image: opensandbox/server:latest
    container_name: opensandbox-server
    ports:
      - "8090:8090"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - SANDBOX_CONFIG_PATH=/etc/opensandbox/config.toml

When the server container is on a bridge network, set host_ip to host.docker.internal (Docker Desktop) or the host’s LAN IP so that sandbox endpoints are reachable from outside the container.

Server Deployment — Full server configuration reference
Architecture Overview — How the Docker runtime fits into the platform
Network Architecture — Single-host routing and bridge mode details
Secure Container — gVisor, Kata, and Firecracker on Docker
Credential Vault — Automatic credential injection via the egress sidecar

Get Started

SDKs

CLI & MCP

Guides

Deployment

Architecture

Run OpenSandbox Locally with Docker Runtime

Prerequisites

Quick Setup

Docker Configuration Reference

Network Modes

Private Registry Access

Resource Limits

Volume Mounts

Egress Network Policy

Secure Container Runtimes

Running the Server in Docker

Build docs developers (and LLMs) love

Get Started

SDKs

CLI & MCP

Guides

Deployment

Architecture

Documentation Index

​Prerequisites

​Quick Setup

​Docker Configuration Reference

​Network Modes

​Private Registry Access

​Resource Limits

​Volume Mounts

​Egress Network Policy

​Secure Container Runtimes

​Running the Server in Docker

​Related

Build docs developers (and LLMs) love

Prerequisites

Quick Setup

Docker Configuration Reference

Network Modes

Private Registry Access

Resource Limits

Volume Mounts

Egress Network Policy

Secure Container Runtimes

Running the Server in Docker

Related