specs

OpenSandbox API Specifications

English | 中文

This directory contains OpenAPI specification documents for the OpenSandbox project, defining the complete API interfaces and data models. Use the server base URLs defined in each spec (for example, http://localhost:8080/v1 for the lifecycle API and http://localhost:8080 for execd) when constructing requests.

Specification Files

1. sandbox-lifecycle.yml

Sandbox Lifecycle Management API

Defines the complete lifecycle interfaces for creating, managing, and destroying sandbox environments directly from container images.

Core Features:

• Sandbox Management: Create, list, query, and delete sandbox instances with metadata filters and pagination
• State Control: Pause and resume sandbox execution
• Lifecycle States: Supports transitions across Pending → Running → Pausing → Paused → Stopping → Terminated, and error handling with Failed
• Resource & Runtime Configuration: Specify CPU/memory/GPU resource limits, required entrypoint, environment variables, and opaque extensions
• Image Support: Create sandboxes from public or private registries, including registry auth
• Timeout Management: Mandatory timeout on creation with explicit renewal via API
• Endpoint Access: Retrieve public access endpoints for services running inside sandboxes

Main Endpoints (base path /v1):

• POST /sandboxes - Create a sandbox from an image with timeout and resource limits
• GET /sandboxes - List sandboxes with state/metadata filters and pagination
• GET /sandboxes/{sandboxId} - Get full sandbox details (including image and entrypoint)
• DELETE /sandboxes/{sandboxId} - Delete a sandbox
• POST /sandboxes/{sandboxId}/pause - Pause a sandbox (asynchronous)
• POST /sandboxes/{sandboxId}/resume - Resume a paused sandbox
• POST /sandboxes/{sandboxId}/renew-expiration - Renew sandbox expiration (TTL)
• GET /sandboxes/{sandboxId}/endpoints/{port} - Get an access endpoint for a service port

Authentication:

• HTTP Header: OPEN-SANDBOX-API-KEY: your-api-key
• Environment Variable: OPEN_SANDBOX_API_KEY (for SDK clients)

2. execd-api.yaml

Code Execution API Inside Sandbox

Defines interfaces for executing code, commands, and file operations within sandbox environments, providing complete code interpreter and filesystem management capabilities. All endpoints require the X-EXECD-ACCESS-TOKEN header.

Core Features:

• Code Execution: Stateful code execution supporting Python, JavaScript, and other languages with context lifecycle management
• Command Execution: Shell command execution with foreground/background modes and polling endpoints for status/output
• File Operations: Complete CRUD operations for files and directories
• Real-time Streaming: Real-time output streaming via SSE (Server-Sent Events)
• System Monitoring: Real-time monitoring of CPU and memory metrics
• Access Control: Token-based API authentication via X-EXECD-ACCESS-TOKEN

Main Endpoint Categories:

Health Check:

• GET /ping - Service health check

Code Interpreter:

• GET /code/contexts - List active code execution contexts (filterable by language)
• DELETE /code/contexts - Delete all contexts for a language
• DELETE /code/contexts/{context_id} - Delete a specific context
• POST /code/context - Create a code execution context
• POST /code - Execute code in a context (streaming output)
• DELETE /code - Interrupt code execution

Command Execution:

• POST /command - Execute shell command (streaming output)
• DELETE /command - Interrupt command execution
• GET /command/status/{session} - Get foreground/background command status
• GET /command/output/{session} - Fetch accumulated stdout/stderr for a command

Filesystem:

• GET /files/info - Get metadata for files
• DELETE /files - Delete files (not directories)
• POST /files/permissions - Change file permissions
• POST /files/mv - Move/rename files
• GET /files/search - Search files (supports glob patterns)
• POST /files/replace - Batch replace file content
• POST /files/upload - Upload files (multipart)
• GET /files/download - Download files (supports range requests)

Directory Operations:

• POST /directories - Create directories with permissions (mkdir -p semantics)
• DELETE /directories - Recursively delete directories

System Metrics:

• GET /metrics - Get system resource metrics
• GET /metrics/watch - Watch system metrics in real-time (SSE stream)

Technical Features

Streaming Output (Server-Sent Events)

Code execution and command execution interfaces use SSE for real-time streaming output, supporting the following event types:

• init - Initialization event
• status - Status update
• stdout / stderr - Standard output/error streams
• result - Execution result
• execution_complete - Execution completed
• execution_count - Execution count
• error - Error information

Resource Limits

Supports flexible resource configuration (similar to Kubernetes):

{
  "cpu": "500m",
  "memory": "512Mi",
  "gpu": "1"
}

File Permissions

Supports Unix-style file permission management:

• Owner
• Group
• Permission mode (octal format, e.g., 755)