Deploy and Run the OpenSandbox Server

The OpenSandbox server is the control plane of the entire platform — a production-grade FastAPI service responsible for creating, monitoring, pausing, resuming, and terminating sandboxes. It authenticates requests, validates configuration, persists server-managed metadata, and delegates all runtime work to a configured backend (Docker or Kubernetes). Every SDK call and CLI command ultimately reaches this service first.

Requirements

Requirement	Minimum Version
Python	3.10+
Package manager	uv (recommended) or pip
Docker (Docker runtime)	Engine 20.10+
Kubernetes (K8s runtime)	1.21.1+
Operating system	Linux, macOS, or Windows with WSL2

Core Features

Lifecycle APIs

Standardized REST interfaces for create, start, pause, resume, and delete across Docker and Kubernetes backends.

Pluggable Runtimes

Switch between Docker (local/single-host) and Kubernetes (scaled/pooled) runtimes via a single config field.

Lifecycle Cleanup

Configurable TTL with renewal, or manual cleanup with explicit delete. Expiration timers are restored after server restart.

API Key Authentication

Enforce OPEN-SANDBOX-API-KEY header on all non-health endpoints. Disable only for local development with explicit acknowledgment.

Networking Modes

Choose host (shared host network, maximum performance) or bridge (isolated network with built-in HTTP routing).

Resource Quotas

CPU and memory limits expressed with Kubernetes-style specs, enforced at container creation time.

Observability

Unified sandbox status with state, reason, message, and lastTransitionAt fields for every lifecycle transition.

Registry Support

Pull from public or private registries. Supply per-request image authentication credentials.

Installation and Startup

Install the server package

Install opensandbox-server from PyPI. For local development, clone the repository and run uv sync inside server/.

uv pip install opensandbox-server

Generate a starter config

Use the init-config command to scaffold a config file for your chosen runtime. Use --example docker for local Docker deployments or --example k8s for Kubernetes.

# Docker runtime (default)
opensandbox-server init-config ~/.sandbox.toml --example docker

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

# Schema-only skeleton (no defaults filled in)
opensandbox-server init-config ~/.sandbox.toml

# Overwrite an existing file
opensandbox-server init-config ~/.sandbox.toml --example docker --force

Edit the config for your environment

Open ~/.sandbox.toml and configure the [server], [runtime], and [docker] or [kubernetes] sections as needed. See the Configuration reference below for all available sections and keys.

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

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

[docker]
network_mode = "bridge"
host_ip = "host.docker.internal"

[ingress]
mode = "direct"

Start the server

Run the server. It listens on the host and port from your TOML config. Pass --config to specify a non-default path.

opensandbox-server

# Specify an explicit config path
opensandbox-server --config /path/to/sandbox.toml

Verify the server is healthy

Send a request to the health endpoint. A healthy server returns {"status": "healthy"}.

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

Configuration Reference

The server reads a TOML file. The default path is ~/.sandbox.toml. Override with the SANDBOX_CONFIG_PATH environment variable or the --config CLI flag.

Config sections

Section	Description
`[server]`	Host, port, API key, and general server settings
`[runtime]`	Runtime backend selection (`docker` or `kubernetes`) and `execd_image`
`[docker]`	Docker-specific settings: `network_mode`, `host_ip`, capability drops, PID limits, registry credentials
`[kubernetes]`	Kubernetes-specific settings: `workload_provider`, `batchsandbox_template_file`
`[egress]`	Egress sidecar image and mode for per-sandbox `networkPolicy` enforcement
`[ingress]`	Ingress gateway configuration for sandbox traffic routing
`[secure_runtime]`	Secure container runtime type (e.g., `gvisor`, `kata-qemu`, `firecracker`) and OCI runtime name
`[storage]`	Host bind-mount allowlist and default PVC size for volume mounts
`[store]`	Persistence backend. Defaults to SQLite at `~/.opensandbox/opensandbox.db`
`[renew_intent]`	Optional auto-renew-on-access integration (experimental)
`[agent_sandbox]`	Agent sandbox settings for the Kubernetes `agent-sandbox` workload provider
`[log]`	Log level and output format

Key server config fields

[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"
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
pids_limit = 4096

[ingress]
mode = "direct"

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

Docker Compose example

The following docker-compose.example.yaml starts the server as a container with access to the host Docker socket.

configs:
  opensandbox-config:
    content: |
      [server]
      host = "0.0.0.0"
      port = 8090

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

      [docker]
      network_mode = "bridge"
      host_ip = "host.docker.internal"
      pids_limit = 4096

      [ingress]
      mode = "direct"

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

When the server runs inside a Docker container and manages sandboxes on bridge mode, set host_ip to the host’s IP or hostname (e.g., host.docker.internal) so that bridge-mode endpoints are reachable from outside the container.

API Authentication

Authentication is enforced when server.api_key is set. Pass the key via the OPEN-SANDBOX-API-KEY header on all calls except /health, /docs, and /redoc.

curl -H "OPEN-SANDBOX-API-KEY: your-secret-api-key" \
  http://localhost:8080/v1/sandboxes

If server.api_key is empty, the server starts unauthenticated. In non-interactive environments (Docker, Kubernetes, CI), set OPENSANDBOX_INSECURE_SERVER=YES to acknowledge the risk. Always set an API key in production. See security issue #750 for background.

Health Check and API Docs

Endpoint	Description
`GET /health`	Returns `{"status": "healthy"}`. No authentication required.
`GET /docs`	Swagger UI — interactive REST API explorer
`GET /redoc`	ReDoc — full OpenAPI reference

Once the server is running, open http://localhost:8080/docs in your browser to explore and call every endpoint interactively.

Sandbox Lifecycle APIs

The lifecycle endpoints all require the OPEN-SANDBOX-API-KEY header when authentication is enabled.

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" }
  }'

Sandbox lifecycle states

       create()
          |
          v
     +---------+
     | Pending |--------------------+
     +----+----+                    |
          |                         |
          | (provisioning)          |
          v                         |
     +---------+    pause()         |
     | Running |---------------+   |
     +----+----+               |   |
          |                    v   |
          |              +---------+
          |              | Pausing |
          |              +----+----+
          |                   |
          |              +---------+
          |              | Paused  |<-- resume()
          |              +----+----+
          |                   |
          |              +----------+
          |              | Resuming |
          |              +----------+
          |
          | delete() or expire()
          v
     +----------+
     | Stopping |
     +----+-----+
          |
     +------------+   +--------+
     | Terminated |   | Failed |
     +------------+   +--------+

Creation is asynchronous. After POST /v1/sandboxes returns, poll GET /v1/sandboxes/{id} or use an SDK readiness helper until the state transitions to Running.

Environment Variables

Variable	Description
`SANDBOX_CONFIG_PATH`	Override the default config file path (`~/.sandbox.toml`)
`OPENSANDBOX_SERVER_API_KEY`	Override the API key from the TOML config file
`DOCKER_HOST`	Custom Docker daemon socket or TCP address
`PENDING_FAILURE_TTL`	Seconds to retain failed `Pending` sandboxes before cleanup (default: `3600`)
`OPENSANDBOX_INSECURE_SERVER`	Set to `YES` to run without an API key in non-interactive environments

Ports

Port	Protocol	Description
`8080`	HTTP	Default server port (configurable via `[server].port`)

Reserved Metadata Prefix

Metadata keys prefixed with opensandbox.io/ are reserved for system use. Any sandbox creation request that supplies keys under this prefix will be rejected. Use a custom namespace for your own metadata (e.g., myapp/team).

Docker Runtime — Configure the Docker backend in detail
Kubernetes Deployment — Deploy on Kubernetes with Helm
Architecture Overview — How the server fits into the broader system
Network Architecture — Networking modes and isolation

Get Started

SDKs

CLI & MCP

Guides

Deployment

Architecture

Deploy and Run the OpenSandbox Server

Requirements

Core Features

Lifecycle APIs

Pluggable Runtimes

Lifecycle Cleanup

API Key Authentication

Networking Modes

Resource Quotas

Observability

Registry Support

Installation and Startup

Configuration Reference

Config sections

Key server config fields

Docker Compose example

API Authentication

Health Check and API Docs

Sandbox Lifecycle APIs

Sandbox lifecycle states

Environment Variables

Ports

Reserved Metadata Prefix

Build docs developers (and LLMs) love

Get Started

SDKs

CLI & MCP

Guides

Deployment

Architecture

Documentation Index

​Requirements

​Core Features

Lifecycle APIs

Pluggable Runtimes

Lifecycle Cleanup

API Key Authentication

Networking Modes

Resource Quotas

Observability

Registry Support

​Installation and Startup

​Configuration Reference

​Config sections

​Key server config fields

​Docker Compose example

​API Authentication

​Health Check and API Docs

​Sandbox Lifecycle APIs

​Sandbox lifecycle states

​Environment Variables

​Ports

​Reserved Metadata Prefix

​Related

Build docs developers (and LLMs) love

Requirements

Core Features

Installation and Startup

Configuration Reference

Config sections

Key server config fields

Docker Compose example

API Authentication

Health Check and API Docs

Sandbox Lifecycle APIs

Sandbox lifecycle states

Environment Variables

Ports

Reserved Metadata Prefix

Related