OpenSandbox Server Configuration: TOML, Auth, and Runtimes

The OpenSandbox server reads all of its settings from a single TOML configuration file. The default path is ~/.sandbox.toml. You can override this with the SANDBOX_CONFIG_PATH environment variable or the --config CLI flag. The file controls the runtime backend (Docker or Kubernetes), authentication, networking, storage, and optional features like secure runtimes and auto-renew.

Generating the Config File

The init-config command writes a ready-to-use config file with sensible defaults. Use the --example flag to pre-populate runtime-specific settings.

# Docker runtime (recommended for local development)
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 config file
opensandbox-server init-config ~/.sandbox.toml --example docker --force

Start with --example docker for local development. The generated file includes inline comments explaining every option.

Running the Server

Once the config file is in place, start the server:

# Reads ~/.sandbox.toml by default
opensandbox-server

# Explicit config path
opensandbox-server --config /path/to/sandbox.toml

The server binds to the server.host and server.port values in your TOML file (0.0.0.0:8080 by default). To verify it is up, query the health endpoint:

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

The three default port bindings used by an OpenSandbox deployment are:

Component	Default port	Notes
Lifecycle server (`opensandbox-server`)	`8080`	Configurable via `server.port` in TOML
Execution daemon (`execd`)	`44772`	Runs inside each sandbox container
Egress sidecar	`18080`	Per-sandbox sidecar; present only when `networkPolicy` is set

Authentication

Set server.api_key in your TOML config to enable API key authentication. All endpoints except /health, /docs, and /redoc will then require the OPEN-SANDBOX-API-KEY header.

[server]
api_key = "your-secret-api-key"

Authenticated request example:

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

If server.api_key is empty or omitted, the server runs without authentication. In non-interactive environments (Docker, Kubernetes, CI), the server will refuse to start unless you explicitly set OPENSANDBOX_INSECURE_SERVER=YES to acknowledge the risk. Always set an API key in production deployments.

Configuration Sections

The table below summarises every top-level TOML section and what it controls.

Section	Description
`[server]`	Bind host, port, API key, concurrency limits, and event-loop settings
`[log]`	Log level, file output, rotation settings
`[runtime]`	Required. Runtime type (`docker` or `kubernetes`) and `execd_image`
`[docker]`	Docker runtime: `network_mode`, `host_ip`, image registry, security hardening
`[kubernetes]`	Kubernetes runtime: `workload_provider`, `batchsandbox_template_file`, informer and rate-limit settings
`[agent_sandbox]`	Agent sandbox settings when using `kubernetes.workload_provider = "agent-sandbox"`
`[ingress]`	Ingress gateway address and routing mode (`direct`, `wildcard`, `uri`, or `header`)
`[egress]`	Egress sidecar image and `networkPolicy` enforcement mode (`dns` or `dns+nft`)
`[storage]`	Host bind-mount allowlist and OSSFS mount root for volume mounts
`[store]`	Persistence backend (default: SQLite at `~/.opensandbox/opensandbox.db`)
`[secure_runtime]`	Strong-isolation runtime type — `gvisor`, `kata`, or `firecracker`
`[renew_intent]`	Experimental auto-renew on access; optional Redis queue integration

Docker Runtime (`[docker]`)

The [docker] section is only read when runtime.type = "docker". Key options:

Key	Default	Description
`network_mode`	`"host"`	`host`, `bridge`, or a custom user-defined network. Egress `networkPolicy` requires `bridge`.
`host_ip`	`null`	Hostname or IP for rewriting bridge-mode endpoint URLs (e.g. `host.docker.internal`).
`no_new_privileges`	`true`	Blocks privilege escalation inside sandbox containers.
`pids_limit`	`4096`	Maximum PIDs per sandbox container. Set to `null` to disable.

Kubernetes Runtime (`[kubernetes]`)

The [kubernetes] section is only read when runtime.type = "kubernetes". Key options:

Key	Default	Description
`workload_provider`	`null` (defaults to `batchsandbox`)	`batchsandbox` or `agent-sandbox`
`batchsandbox_template_file`	`null`	Path to the BatchSandbox CR YAML template
`namespace`	`null`	Kubernetes namespace for sandbox workloads
`sandbox_create_timeout_seconds`	`60`	Max time to wait for a sandbox to become ready
`informer_enabled`	`true`	Use informer/watch cache to reduce API load

Secure Runtime (`[secure_runtime]`)

Key	Default	Description
`type`	`""`	`""` (runc default), `gvisor`, `kata`, or `firecracker` (Kubernetes only)
`docker_runtime`	`null`	Docker OCI runtime name, e.g. `runsc` for gVisor
`k8s_runtime_class`	`null`	Kubernetes RuntimeClass name, e.g. `gvisor`, `kata-qemu`

Environment Variables

The following environment variables are read in addition to the TOML config file. They are useful for containerised deployments and CI pipelines where writing a config file is impractical.

Variable	Description
`SANDBOX_CONFIG_PATH`	Override the config file path (absolute or `~`-expandable)
`OPENSANDBOX_SERVER_API_KEY`	Override the server API key from TOML (server-side; takes precedence over `server.api_key`)
`OPENSANDBOX_INSECURE_SERVER`	Set to `YES` to start the server without an API key in non-interactive mode
`DOCKER_HOST`	Custom Docker daemon address (e.g. `unix:///var/run/docker.sock`)
`PENDING_FAILURE_TTL`	Seconds to retain failed-Pending sandboxes before cleanup (default: `3600`)
`OPEN_SANDBOX_API_KEY`	Client-side API key used by the SDKs and CLI when connecting to the server
`OPEN_SANDBOX_DOMAIN`	Client-side domain (`host:port`) used by the SDKs and CLI

OPEN_SANDBOX_API_KEY and OPEN_SANDBOX_DOMAIN are client-side variables read by SDKs and the osb CLI — they are not read by the server process itself. The server-side API key is set via server.api_key in TOML or the OPENSANDBOX_SERVER_API_KEY environment variable, with the environment variable taking precedence.

API Documentation

When the server is running, interactive API documentation is available at:

Swagger UI — http://localhost:8080/docs
ReDoc — http://localhost:8080/redoc

These pages are always accessible regardless of whether server.api_key is set, making them convenient for local development and exploration.

Secure Container Runtimes

Install and configure gVisor, Kata Containers, and Firecracker on Docker and Kubernetes.

Credential Vault

Inject credentials into sandbox outbound requests without exposing secrets to workloads.

Network Isolation

Understand the egress sidecar design and per-sandbox network policy enforcement.

Kubernetes Deployment

BatchSandbox CRD setup, RBAC, and production Kubernetes configuration.

Get Started

SDKs

CLI & MCP

Guides

Deployment

Architecture

OpenSandbox Server Configuration: TOML, Auth, and Runtimes

Generating the Config File

Running the Server

Authentication

Configuration Sections

Docker Runtime (`[docker]`)

Kubernetes Runtime (`[kubernetes]`)

Secure Runtime (`[secure_runtime]`)

Environment Variables

API Documentation

Secure Container Runtimes

Credential Vault

Network Isolation

Kubernetes Deployment

Build docs developers (and LLMs) love

Get Started

SDKs

CLI & MCP

Guides

Deployment

Architecture

Documentation Index

​Generating the Config File

​Running the Server

​Authentication

​Configuration Sections

​Docker Runtime ([docker])

​Kubernetes Runtime ([kubernetes])

​Secure Runtime ([secure_runtime])

​Environment Variables

​API Documentation

​Related Guides

Secure Container Runtimes

Credential Vault

Network Isolation

Kubernetes Deployment

Build docs developers (and LLMs) love

Generating the Config File

Running the Server

Authentication

Configuration Sections

Docker Runtime (`[docker]`)

Kubernetes Runtime (`[kubernetes]`)

Secure Runtime (`[secure_runtime]`)

Environment Variables

API Documentation

Related Guides