Skip to main content
The Sandbox Lifecycle API coordinates how untrusted workloads are created, executed, paused, resumed, and finally disposed. This API focuses on the primary lifecycle flows for sandboxes, which are provisioned directly from container images without requiring pre-created templates.

​
Sandbox Lifecycle

A sandbox follows this lifecycle:
  1. Creation → Sandbox enters Pending state (auto-starts)
  2. Execution → Transitions to Running state
  3. Pause (optional) → Pausing → Paused (asynchronous process)
  4. Resume (optional) → Returns to Running from Paused
  5. Termination → Stopping → Terminated (can be triggered by kill action, TTL expiry, or error)
  6. Error → Any state can transition to Failed on critical errors

​
Sandbox States

The status field provides fine-grained details through state, reason, and message.

​
Common State Values

  • Pending: Sandbox is being provisioned
  • Running: Sandbox is running and ready to accept requests
  • Pausing: Sandbox is in the process of pausing
  • Paused: Sandbox has been paused while retaining its state
  • Stopping: Sandbox is being terminated
  • Terminated: Sandbox has been successfully terminated
  • Failed: Sandbox encountered a critical error

​
State Transitions

  • Pending → Running (after creation completes)
  • Running → Pausing (when pause is requested)
  • Pausing → Paused (pause operation completes)
  • Paused → Running (when resume is requested)
  • Running/Paused → Stopping (when kill is requested or TTL expires)
  • Stopping → Terminated (kill/timeout operation completes)
  • Pending/Running/Paused → Failed (on error)
New state values may be added in future versions. Clients should handle unknown state values gracefully.

​
Authentication

API Key authentication is required for all operations:

​
HTTP Header

OPEN-SANDBOX-API-KEY: your-api-key

​
Environment Variable

For SDK clients: 
OPEN_SANDBOX_API_KEY=your-api-key
SDK clients will automatically pick up this environment variable.

​
Base URL

All lifecycle API endpoints use the base path: 
http://localhost:8080/v1

​
Core Endpoints

The Lifecycle API provides the following endpoint groups:

​
Sandbox Management

  • POST /v1/sandboxes - Create a sandbox from a container image
  • GET /v1/sandboxes - List sandboxes with filtering and pagination
  • GET /v1/sandboxes/{sandboxId} - Get detailed sandbox information
  • DELETE /v1/sandboxes/{sandboxId} - Delete a sandbox

​
State Control

  • POST /v1/sandboxes/{sandboxId}/pause - Pause a running sandbox
  • POST /v1/sandboxes/{sandboxId}/resume - Resume a paused sandbox
  • POST /v1/sandboxes/{sandboxId}/renew-expiration - Renew sandbox timeout

​
Network Access

  • GET /v1/sandboxes/{sandboxId}/endpoints/{port} - Get access endpoint for a service port

​
Resource Configuration

Sandboxes support flexible resource configuration similar to Kubernetes: 
{
  "cpu": "500m",
  "memory": "512Mi",
  "gpu": "1"
}

​
Common Features

​
Container Image Support

Create sandboxes from public or private registry images:
  • Docker Hub: python:3.11, ubuntu:22.04
  • GCR: gcr.io/my-project/model-server:v1.0
  • Private registries with authentication

​
Timeout Management

All sandboxes require a timeout (60-86400 seconds) on creation. Use the renewal endpoint to extend timeout before expiry.

​
Metadata & Filtering

Attach custom metadata for management, filtering, and tagging. Use the name key for human-readable identifiers.

​
Pagination

List operations support pagination with page and pageSize query parameters.

Build docs developers (and LLMs) love

Get started for freeTalk to us