Sandbox Lifecycle API: Create, List, Delete, Pause, Resume

The Sandbox Lifecycle API is the primary interface for provisioning and managing sandbox environments. Every sandbox follows a predictable state machine: Pending → Running → (optionally) Pausing → Paused → Resuming → Running → Stopping → Terminated. Any state can transition to Failed on a critical error. All endpoints share the base URL http://localhost:8080/v1 and require the OPEN-SANDBOX-API-KEY header for authentication.

POST /v1/sandboxes

Creates a new sandbox from a container image or restores one from a previously saved snapshot. The response is returned immediately with status.state: "Pending" — poll GET /v1/sandboxes/{sandboxId} to track provisioning progress until the sandbox reaches Running. Auth: OPEN-SANDBOX-API-KEY header required. Exactly one startup source must be provided: image or snapshotId. When image is given, entrypoint is required. When snapshotId is given, entrypoint is optional (defaults to ["tail", "-f", "/dev/null"]).

Request Body

image

object

Container image specification. Mutually exclusive with snapshotId.

Show image fields

image.uri

string

required

Container image URI. Examples: "python:3.11", "gcr.io/my-project/server:v1.0".

image.auth

object

Registry credentials for private images.

Show auth fields

image.auth.username

string

Registry username or service account.

image.auth.password

string

Registry password or authentication token.

snapshotId

string

Snapshot identifier to restore from. Mutually exclusive with image.

entrypoint

array

Command to run as the sandbox entry process. Format: [executable, arg1, arg2, ...]. Required when image is provided.

timeout

integer | null

Sandbox TTL in seconds (minimum 60). The sandbox auto-terminates after this duration. Omit or set null to disable automatic expiration (requires manual cleanup).

resourceLimits

object

Hard resource caps for the sandbox instance. Required unless using pool mode.

Show resourceLimits fields

resourceLimits.cpu

string

CPU in millicores, e.g. "500m".

resourceLimits.memory

string

Memory in bytes or human-readable format, e.g. "512Mi".

resourceLimits.gpu

string

Number of GPU devices, e.g. "1".

resourceRequests

object

Resource reservations (guaranteed minimums). When provided, enables Kubernetes Burstable QoS. When omitted, resourceLimits values apply to both limits and requests (Guaranteed QoS). Ignored by Docker runtime.

env

object

Key-value environment variables injected into the sandbox runtime. Example: {"DEBUG": "true", "LOG_LEVEL": "info"}.

metadata

object

Custom string key-value pairs for tagging and filtering. Use "name" for a human-readable identifier.

platform

object

Optional platform scheduling constraint.

Show platform fields

platform.os

string

Target OS. Enum: linux, windows.

platform.arch

string

Target CPU architecture. Enum: amd64, arm64.

networkPolicy

object

Outbound network policy applied at sandbox startup.

Show networkPolicy fields

networkPolicy.defaultAction

string

Default action when no rule matches. Enum: allow, deny. Defaults to deny.

networkPolicy.egress

array

Ordered list of egress rules. Each rule has action (allow|deny) and target (FQDN or wildcard domain).

credentialProxy

object

Credential Vault proxy configuration.

Show credentialProxy fields

credentialProxy.enabled

boolean

When true, enables transparent MITM credential injection. Requires networkPolicy.

secureAccess

boolean

When true, provisions endpoint access credentials. Supported only for Kubernetes sandboxes in ingress gateway mode. Defaults to false.

volumes

array

Storage mounts. Each entry requires name and mountPath, plus exactly one backend: host, pvc, or ossfs.

extensions

object

Opaque provider-specific parameters. Pass through transparently. Well-known key: access.renew.extend.seconds (300–86400) to enable renew-on-access.

Response — 202 Accepted

string

required

Unique sandbox identifier.

status

object

required

Current lifecycle status.

Show status fields

status.state

string

Lifecycle state, e.g. "Pending", "Running", "Failed".

status.reason

string

Machine-readable reason code, e.g. "provision_timeout".

status.message

string

Human-readable description of the current state.

status.lastTransitionAt

string

RFC 3339 timestamp of the last state transition.

entrypoint

array

required

The resolved entry process command.

metadata

object

Custom metadata echoed from the creation request.

platform

object

Platform constraint echoed from request or workload template.

expiresAt

string

RFC 3339 timestamp of auto-termination. Omitted when manual cleanup is enabled.

createdAt

string

required

RFC 3339 sandbox creation timestamp.

The create response does not include image, snapshotId, or updatedAt. Use GET /v1/sandboxes/{sandboxId} to retrieve the full sandbox representation.

Example

curl -X POST http://localhost:8080/v1/sandboxes \
  -H "OPEN-SANDBOX-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "image": { "uri": "python:3.11" },
    "entrypoint": ["python", "/app/main.py"],
    "timeout": 3600,
    "resourceLimits": { "cpu": "500m", "memory": "512Mi" },
    "networkPolicy": {
      "defaultAction": "deny",
      "egress": [{ "action": "allow", "target": "pypi.org" }]
    }
  }'

GET /v1/sandboxes

Lists all sandboxes with optional filtering and pagination. Multiple state values use OR logic; all other filter conditions are ANDed together. Auth: OPEN-SANDBOX-API-KEY header required.

Query Parameters

state

string

Filter by lifecycle state. Pass multiple times for OR logic. Example: ?state=Running&state=Paused.

metadata

string

Filter by metadata key-value pairs. Keys and values must be URL-encoded. Example: ?metadata=project%3DApollo.

page

integer

Page number for pagination (minimum 1, default 1).

pageSize

integer

Number of items per page (minimum 1, default 20).

Response — 200 OK

items

array

required

Array of sandbox objects.

pagination

object

required

Show pagination fields

pagination.page

integer

Current page number.

pagination.pageSize

integer

Items per page.

pagination.totalItems

integer

Total items matching the filter.

pagination.totalPages

integer

Total number of pages.

pagination.hasNextPage

boolean

Whether additional pages exist.

Example

curl "http://localhost:8080/v1/sandboxes?state=Running&page=1&pageSize=10" \
  -H "OPEN-SANDBOX-API-KEY: your-api-key"

GET /v1/sandboxes/

Returns the complete sandbox resource including startup source (image or snapshotId), entrypoint, current status, and metadata. Auth: OPEN-SANDBOX-API-KEY header required.

Path Parameters

sandboxId

string

required

Unique sandbox identifier.

Response — 200 OK

string

required

Unique sandbox identifier.

status

object

required

Full lifecycle status with state, reason, message, and lastTransitionAt.

image

object

Container image spec. Present when the sandbox was created from an image.

snapshotId

string

Source snapshot ID. Present when the sandbox was restored from a snapshot.

entrypoint

array

required

Entry process command.

platform

object

Platform constraint, if any.

metadata

object

Custom metadata key-value pairs.

expiresAt

string

Auto-termination timestamp. Omitted when manual cleanup is enabled.

createdAt

string

required

Creation timestamp (RFC 3339).

Example

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

DELETE /v1/sandboxes/

Terminates a sandbox. The sandbox transitions through Stopping to Terminated. Returns 204 No Content on success. Auth: OPEN-SANDBOX-API-KEY header required.

Path Parameters

sandboxId

string

required

Unique sandbox identifier.

Example

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

POST /v1/sandboxes//pause

Initiates an asynchronous pause of a running sandbox. State transitions through Pausing and eventually reaches Paused. Returns 202 Accepted immediately — poll GET /v1/sandboxes/{sandboxId} to track completion. Auth: OPEN-SANDBOX-API-KEY header required.

Path Parameters

sandboxId

string

required

Unique sandbox identifier.

Example

curl -X POST http://localhost:8080/v1/sandboxes/sbx_abc123/pause \
  -H "OPEN-SANDBOX-API-KEY: your-api-key"

POST /v1/sandboxes//resume

Resumes a paused sandbox. State transitions Paused → Resuming → Running. Returns 202 Accepted — poll GET /v1/sandboxes/{sandboxId} to confirm the sandbox has returned to Running. Auth: OPEN-SANDBOX-API-KEY header required.

Path Parameters

sandboxId

string

required

Unique sandbox identifier.

Example

curl -X POST http://localhost:8080/v1/sandboxes/sbx_abc123/resume \
  -H "OPEN-SANDBOX-API-KEY: your-api-key"

PATCH /v1/sandboxes//metadata

Updates sandbox metadata using JSON Merge Patch (RFC 7396) semantics. Keys with string values are added or replaced; keys with null values are deleted; absent keys are left unchanged. Returns the full updated sandbox object. Auth: OPEN-SANDBOX-API-KEY header required.

Keys with the opensandbox.io/ prefix are reserved and will be rejected. Concurrent PATCH requests may interleave — use a single writer or coordinate out-of-band when concurrent modifications to the same key are expected.

Path Parameters

sandboxId

string

required

Unique sandbox identifier.

Request Body

The request body is the metadata object itself. Example:

{
  "project": "new-project",
  "team": null,
  "environment": "production"
}

Example

curl -X PATCH http://localhost:8080/v1/sandboxes/sbx_abc123/metadata \
  -H "OPEN-SANDBOX-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"environment": "production", "team": null}'

POST /v1/sandboxes//renew-expiration

Updates the absolute expiration time for a sandbox. The new timestamp must be in the future and after the current expiresAt value. Returns only the updated expiresAt field. Auth: OPEN-SANDBOX-API-KEY header required.

Path Parameters

sandboxId

string

required

Unique sandbox identifier.

Request Body

expiresAt

string

required

New absolute expiration time in UTC (RFC 3339 format). Must be in the future. Example: "2025-11-16T14:30:45Z".

Response — 200 OK

expiresAt

string

required

The new absolute expiration time in UTC (RFC 3339 format).

Example

curl -X POST http://localhost:8080/v1/sandboxes/sbx_abc123/renew-expiration \
  -H "OPEN-SANDBOX-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"expiresAt": "2025-11-16T14:30:45Z"}'

GET /v1/sandboxes//endpoints/

Resolves the public access endpoint for a service running on a specific port inside the sandbox. The service must be actively listening on that port. Auth: OPEN-SANDBOX-API-KEY header required.

Path Parameters

sandboxId

string

required

Unique sandbox identifier.

port

integer

required

Port number where the service is listening inside the sandbox (1–65535).

Query Parameters

use_server_proxy

boolean

Return a server-proxied URL. Cannot be combined with expires. Default: false.

expires

string

Unix epoch seconds (decimal integer string). When set, the server issues a signed access route (OSEP-0011). Cannot be combined with use_server_proxy=true.

Response — 200 OK

endpoint

string

required

Public URL for the service. Format: {endpoint-host}/sandboxes/{sandboxId}/port/{port}.

headers

object

Required request headers that callers must include when targeting this endpoint. Present when secureAccess was enabled at sandbox creation.

Example

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

Overview

Lifecycle API

Execution API

Egress & Diagnostics

Documentation Index

​POST /v1/sandboxes

​Request Body

​Response — 202 Accepted

​Example

​GET /v1/sandboxes

​Query Parameters

​Response — 200 OK

​Example

​GET /v1/sandboxes/

​Path Parameters

​Response — 200 OK

​Example

​DELETE /v1/sandboxes/

​Path Parameters

​Example

​POST /v1/sandboxes//pause

​Path Parameters

​Example

​POST /v1/sandboxes//resume

​Path Parameters

​Example

​PATCH /v1/sandboxes//metadata

​Path Parameters

​Request Body

​Example

​POST /v1/sandboxes//renew-expiration

​Path Parameters

​Request Body

​Response — 200 OK

​Example

​GET /v1/sandboxes//endpoints/

​Path Parameters

​Query Parameters

​Response — 200 OK

​Example

Build docs developers (and LLMs) love

POST /v1/sandboxes

Request Body

Response — 202 Accepted

Example

GET /v1/sandboxes

Query Parameters

Response — 200 OK

Example

GET /v1/sandboxes/

Path Parameters

Response — 200 OK

Example

DELETE /v1/sandboxes/

Path Parameters

Example

POST /v1/sandboxes//pause

Path Parameters

Example

POST /v1/sandboxes//resume

Path Parameters

Example

PATCH /v1/sandboxes//metadata

Path Parameters

Request Body

Example

POST /v1/sandboxes//renew-expiration

Path Parameters

Request Body

Response — 200 OK

Example

GET /v1/sandboxes//endpoints/

Path Parameters

Query Parameters

Response — 200 OK

Example