Skip to main content
OpenSandbox Server uses TOML configuration files to control runtime behavior, networking, security, and resource management. This guide covers all available configuration options.

​
Configuration File Location

By default, the server looks for configuration at ~/.sandbox.toml. Override with: 
# Environment variable
export SANDBOX_CONFIG_PATH=/path/to/config.toml
opensandbox-server

# Command-line flag
opensandbox-server --config /path/to/config.toml

​
Initialize Configuration

Generate a configuration file with examples: 
# Docker runtime
opensandbox-server init-config ~/.sandbox.toml --example docker

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

# Full schema (no defaults, just placeholders)
opensandbox-server init-config ~/.sandbox.toml

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

​
Server Configuration

Control the HTTP server settings: 
[server]
host = "0.0.0.0"
port = 8080
log_level = "INFO"
api_key = "your-secret-api-key-change-this"

​
Options

KeyTypeDefaultDescription
hoststring"0.0.0.0"Interface to bind. Use "127.0.0.1" for localhost only
portinteger8080Port to listen on
log_levelstring"INFO"Python logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL
api_keystringnullAPI key for authentication. If empty, authentication is disabled

​
Log Levels

  • DEBUG: Detailed diagnostic information
  • INFO: General informational messages
  • WARNING: Warning messages for potential issues
  • ERROR: Error messages for failures
  • CRITICAL: Critical errors that may cause shutdown

​
API Authentication

Authentication is enforced only when api_key is set:
  • Empty or missing: Middleware skips API key checks (for local/dev)
  • Non-empty: All endpoints (except /health, /docs, /redoc) require OPEN-SANDBOX-API-KEY header
curl -H "OPEN-SANDBOX-API-KEY: your-secret-api-key" \
  http://localhost:8080/v1/sandboxes

​
Runtime Configuration

Select and configure the sandbox runtime backend: 
[runtime]
type = "docker"  # or "kubernetes"
execd_image = "opensandbox/execd:v1.0.6"

​
Options

KeyTypeRequiredDescription
typestringYesRuntime implementation: "docker" or "kubernetes"
execd_imagestringYesContainer image with execd binary for sandbox initialization

​
Docker Runtime Configuration

Docker-specific settings: 
[docker]
network_mode = "bridge"
api_timeout = 300
host_ip = "10.57.1.91"
drop_capabilities = [
  "AUDIT_WRITE",
  "MKNOD",
  "NET_ADMIN",
  "NET_RAW",
  "SYS_ADMIN",
  "SYS_MODULE",
  "SYS_PTRACE",
  "SYS_TIME",
  "SYS_TTY_CONFIG"
]
no_new_privileges = true
apparmor_profile = ""
pids_limit = 512
seccomp_profile = ""

​
Options

KeyTypeDefaultDescription
network_modestring"host"Network mode: "host" (shared network) or "bridge" (isolated)
api_timeoutinteger180Docker API timeout in seconds
host_ipstringnullHost IP/hostname for bridge-mode endpoints when server runs in a container
drop_capabilitiesarray[]Linux capabilities to drop from containers
no_new_privilegesbooleanfalseBlock privilege escalation in containers
apparmor_profilestring""AppArmor profile name (e.g., "docker-default")
pids_limitintegernullMax processes per container. null = unlimited
seccomp_profilestring""Seccomp profile path. Empty = Docker default

​
Network Mode Comparison

FeatureHost ModeBridge Mode
PerformanceBestGood
IsolationNoneFull
Port conflictsYesNo
Multiple sandboxesLimitedUnlimited
Network policiesNoYes (with egress sidecar)

​
Security Capabilities

Recommended capabilities to drop:
  • AUDIT_WRITE: Prevent audit log manipulation
  • MKNOD: Block device node creation
  • NET_ADMIN: Disable network configuration
  • NET_RAW: Prevent raw socket creation
  • SYS_ADMIN: Block administrative operations
  • SYS_MODULE: Prevent kernel module loading
  • SYS_PTRACE: Disable process tracing
  • SYS_TIME: Block system clock changes
  • SYS_TTY_CONFIG: Prevent TTY configuration

​
Kubernetes Runtime Configuration

Kubernetes-specific settings: 
[kubernetes]
kubeconfig_path = "~/.kube/config"
namespace = "opensandbox"
workload_provider = "batchsandbox"
batchsandbox_template_file = "~/batchsandbox-template.yaml"
informer_enabled = true
informer_resync_seconds = 300
informer_watch_timeout_seconds = 60

​
Options

KeyTypeDefaultDescription
kubeconfig_pathstringnullPath to kubeconfig. null = in-cluster config
namespacestring"opensandbox"Namespace for sandbox workloads
workload_providerstring"batchsandbox"Provider type: "batchsandbox" or "agent-sandbox"
batchsandbox_template_filestringnullPath to BatchSandbox template YAML
informer_enabledbooleantrueEnable watch-based cache (beta)
informer_resync_secondsinteger300Full list refresh interval (beta)
informer_watch_timeout_secondsinteger60Watch restart interval (beta)

​
Informer Configuration (Beta)

Informers reduce API server load through watch-based caching:
  • Enabled by default: Set informer_enabled = false to disable
  • Resync interval: How often to perform full list refresh
  • Watch timeout: How long before restarting watch connection
  • Tune for your cluster: Adjust based on API rate limits

​
Egress Configuration

Configure egress sidecar for network policy enforcement: 
[egress]
image = "opensandbox/egress:v1.0.1"

​
Options

KeyTypeRequiredDescription
imagestringRequired when using networkPolicyEgress sidecar container image

​
Network Policy Requirements

  • Only supported in Docker bridge mode
  • Egress image must be configured
  • Requests with networkPolicy are rejected in host mode
  • Main container shares sidecar network namespace
  • Main container drops NET_ADMIN capability
  • Sidecar retains NET_ADMIN for iptables management
  • IPv6 disabled in shared namespace

​
Ingress Configuration

Control how clients access sandbox endpoints: 
[ingress]
mode = "direct"  # or "gateway"

# Gateway configuration (when mode = "gateway")
[ingress.gateway]
address = "*.example.com"

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

​
Options

KeyTypeDefaultDescription
modestring"direct"Ingress mode: "direct" or "gateway"
gateway.addressstringnullGateway address (domain, IP, or IP:port). No scheme.
gateway.route.modestring"wildcard"Routing mode: "wildcard", "uri", or "header"

​
Ingress Modes

​
Direct Mode

[ingress]
mode = "direct"
Clients connect directly to sandboxes. Required for Docker runtime.

​
Gateway Mode with Wildcard Routing

[ingress]
mode = "gateway"

[ingress.gateway]
address = "*.example.com"

[ingress.gateway.route]
mode = "wildcard"
Endpoint format: <sandbox-id>-<port>.example.com/path/to/request

​
Gateway Mode with URI Routing

[ingress]
mode = "gateway"

[ingress.gateway]
address = "10.0.0.1:8000"

[ingress.gateway.route]
mode = "uri"
Endpoint format: 10.0.0.1:8000/<sandbox-id>/<port>/path/to/request

​
Gateway Mode with Header Routing

[ingress]
mode = "gateway"

[ingress.gateway]
address = "gateway.example.com"

[ingress.gateway.route]
mode = "header"
Endpoint format: gateway.example.com with header OpenSandbox-Ingress-To: <sandbox-id>-<port>

​
Storage Configuration

Control host path access for volume bind mounts: 
[storage]
allowed_host_paths = ["/data/opensandbox", "/tmp/sandbox"]

​
Options

KeyTypeDefaultDescription
allowed_host_pathsarray[]Allowlist of host path prefixes for bind mounts

​
Behavior

  • Empty list: All host paths allowed (not recommended for production)
  • Non-empty list: Only paths starting with listed prefixes are allowed
  • Applies to volume bind mount requests

​
Agent-Sandbox Configuration

Configuration for agent-sandbox workload provider: 
[agent_sandbox]
template_file = "/path/to/sandbox-template.yaml"
shutdown_policy = "Delete"
ingress_enabled = true

​
Options

KeyTypeDefaultDescription
template_filestringnullSandbox CR YAML template path
shutdown_policystring"Delete"Shutdown policy: "Delete" or "Retain"
ingress_enabledbooleantrueWhether ingress routing is enabled

​
Environment Variables

Override configuration with environment variables:
VariableDescriptionExample
SANDBOX_CONFIG_PATHOverride config file location/etc/opensandbox/config.toml
DOCKER_HOSTDocker daemon URLunix:///var/run/docker.sock or ssh://user@host
PENDING_FAILURE_TTLTTL for failed pending sandboxes (seconds)3600 (default)

​
Complete Configuration Examples

​
Production Docker Setup

[server]
host = "0.0.0.0"
port = 8080
log_level = "INFO"
api_key = "production-secret-key-use-vault-or-secrets-manager"

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

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

[storage]
allowed_host_paths = ["/data/opensandbox"]

[docker]
network_mode = "bridge"
api_timeout = 300
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 = 512

[ingress]
mode = "gateway"

[ingress.gateway]
address = "*.sandbox.example.com"

[ingress.gateway.route]
mode = "wildcard"

​
Production Kubernetes Setup

[server]
host = "0.0.0.0"
port = 8080
log_level = "INFO"
api_key = "production-secret-key-use-vault-or-secrets-manager"

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

[storage]
allowed_host_paths = []

[kubernetes]
kubeconfig_path = null  # Use in-cluster config
namespace = "opensandbox-prod"
workload_provider = "batchsandbox"
batchsandbox_template_file = "/etc/opensandbox/batchsandbox-template.yaml"
informer_enabled = true
informer_resync_seconds = 300
informer_watch_timeout_seconds = 60

[ingress]
mode = "gateway"

[ingress.gateway]
address = "*.sandbox.example.com"

[ingress.gateway.route]
mode = "wildcard"

​
Development Setup

[server]
host = "127.0.0.1"
port = 8080
log_level = "DEBUG"
# api_key not set - authentication disabled

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

[docker]
network_mode = "host"

[ingress]
mode = "direct"

​
Configuration Validation

The server validates configuration at startup: 
opensandbox-server
Common validation errors:
  • Missing required fields: runtime.type and runtime.execd_image are required
  • Invalid runtime type: Must be "docker" or "kubernetes"
  • Network policy misconfiguration: egress.image required when using networkPolicy
  • Invalid log level: Must be a valid Python logging level

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us