Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/alibaba/OpenSandbox/llms.txt

Use this file to discover all available pages before exploring further.

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