Manage Sandbox - OpenSandbox

This page documents the lifecycle management endpoints for controlling sandbox state transitions and expiration.

Pause Sandbox

Pause a running sandbox while preserving its state. Poll GET /v1/sandboxes/{sandboxId} to track state transition to Paused.

Path Parameters

sandboxId

string

required

Unique sandbox identifier

Response

202

Accepted

Pause operation accepted.Sandbox will transition to Pausing state. Poll GET /v1/sandboxes/{sandboxId} to track progress.

Response Headers

X-Request-ID

string

Unique request identifier for tracing

Error Responses

401

Unauthorized

Authentication credentials are missing or invalid

403

Forbidden

The authenticated user lacks permission for this operation

404

Not Found

The requested sandbox does not exist

409

Conflict

The operation conflicts with the current state

500

Internal Server Error

An unexpected server error occurred

Example Request

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

Resume Sandbox

Resume execution of a paused sandbox. Poll GET /v1/sandboxes/{sandboxId} to track state transition to Running.

Path Parameters

sandboxId

string

required

Unique sandbox identifier

Response

202

Accepted

Resume operation accepted.Sandbox will transition from Paused → Running. Poll GET /v1/sandboxes/{sandboxId} to track progress.

Response Headers

X-Request-ID

string

Unique request identifier for tracing

Error Responses

401

Unauthorized

Authentication credentials are missing or invalid

403

Forbidden

The authenticated user lacks permission for this operation

404

Not Found

The requested sandbox does not exist

409

Conflict

The operation conflicts with the current state

500

Internal Server Error

An unexpected server error occurred

Example Request

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

Delete Sandbox

Delete a sandbox, terminating its execution. The sandbox will transition through Stopping state to Terminated.

Path Parameters

sandboxId

string

required

Unique sandbox identifier

Response

204

No Content

Sandbox successfully deleted.Sandbox has been scheduled for termination and will transition to Stopping state, then Terminated.

Response Headers

X-Request-ID

string

Unique request identifier for tracing

Error Responses

401

Unauthorized

Authentication credentials are missing or invalid

403

Forbidden

The authenticated user lacks permission for this operation

404

Not Found

The requested sandbox does not exist

409

Conflict

The operation conflicts with the current state

500

Internal Server Error

An unexpected server error occurred

Example Request

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

Renew Sandbox Expiration

Renew the absolute expiration time of a sandbox.

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 and after the current expiresAt time.Example: "2025-11-16T14:30:45Z"

Response

expiresAt

string

The new absolute expiration time in UTC (RFC 3339 format).Example: "2025-11-16T14:30:45Z"

Response Headers

X-Request-ID

string

Unique request identifier for tracing

Status Code

200

Sandbox expiration updated successfully.Returns only the updated expiresAt field.

Error Responses

400

Bad Request

The request was invalid or malformed

401

Unauthorized

Authentication credentials are missing or invalid

403

Forbidden

The authenticated user lacks permission for this operation

404

Not Found

The requested sandbox does not exist

409

Conflict

The operation conflicts with the current state

500

Internal Server Error

An unexpected server error occurred

Example Request

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

Example Response

{
  "expiresAt": "2025-11-16T14:30:45Z"
}

Get Sandbox

Returns the complete sandbox information including image specification and entrypoint.

Path Parameters

sandboxId

string

required

Unique sandbox identifier

Response

string

Unique sandbox identifier

image

object

Container image specification used to provision this sandbox

Show properties

uri

string

Container image URI in standard format

auth

object

Registry authentication credentials

Show properties

username

string

Registry username or service account

password

string

Registry password or authentication token

status

object

Current lifecycle status and detailed state information

Show properties

state

string

Current lifecycle state of the sandbox

reason

string

Short machine-readable reason code for the current state

message

string

Human-readable message describing the current state

lastTransitionAt

string

Timestamp of the last state transition (RFC 3339 format)

metadata

object

Custom metadata from creation request

entrypoint

array

Entry process specification

expiresAt

string

Timestamp when sandbox will auto-terminate (RFC 3339 format)

createdAt

string

Sandbox creation timestamp (RFC 3339 format)

Response Headers

X-Request-ID

string

Unique request identifier for tracing

Status Code

200

Sandbox current state and metadata

Error Responses

401

Unauthorized

Authentication credentials are missing or invalid

403

Forbidden

The authenticated user lacks permission for this operation

404

Not Found

The requested sandbox does not exist

500

Internal Server Error

An unexpected server error occurred

Example Request

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

Example Response

{
  "id": "sandbox-abc123",
  "image": {
    "uri": "python:3.11"
  },
  "status": {
    "state": "Running",
    "reason": "running",
    "message": "Sandbox is running",
    "lastTransitionAt": "2026-03-01T10:31:00Z"
  },
  "metadata": {
    "name": "My Python Sandbox"
  },
  "entrypoint": ["python", "/app/main.py"],
  "expiresAt": "2026-03-01T11:30:00Z",
  "createdAt": "2026-03-01T10:30:00Z"
}

List Sandboxes

List all sandboxes with optional filtering and pagination using query parameters. All filter conditions use AND logic. Multiple state parameters use OR logic within states.

Query Parameters

state

array

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

metadata

string

Arbitrary metadata key-value pairs for filtering. Keys and values must be url encoded.Example: To filter by project=Apollo and note=Demo Test:?metadata=project%3DApollo%26note%3DDemo%252520Test

page

integer

Page number for paginationDefault: 1, Minimum: 1

pageSize

integer

Number of items per pageDefault: 20, Minimum: 1

Response

items

array

Array of sandbox objects

pagination

object

Pagination metadata for list responses

Show properties

page

integer

Current page number

pageSize

integer

Number of items per page

totalItems

integer

Total number of items matching the filter

totalPages

integer

Total number of pages

hasNextPage

boolean

Whether there are more pages after the current one

Response Headers

X-Request-ID

string

Unique request identifier for tracing

Status Code

200

Paginated collection of sandboxes

Error Responses

400

Bad Request

The request was invalid or malformed

401

Unauthorized

Authentication credentials are missing or invalid

500

Internal Server Error

An unexpected server error occurred

Example Request

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

Example Response

{
  "items": [
    {
      "id": "sandbox-abc123",
      "image": {
        "uri": "python:3.11"
      },
      "status": {
        "state": "Running",
        "reason": "running",
        "message": "Sandbox is running",
        "lastTransitionAt": "2026-03-01T10:31:00Z"
      },
      "metadata": {
        "name": "My Python Sandbox"
      },
      "entrypoint": ["python", "/app/main.py"],
      "expiresAt": "2026-03-01T11:30:00Z",
      "createdAt": "2026-03-01T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 1,
    "totalPages": 1,
    "hasNextPage": false
  }
}

Lifecycle API

Execution API

SDK Reference

​Pause Sandbox

​Path Parameters

​Response

​Response Headers

​Error Responses

​Example Request

​Resume Sandbox

​Path Parameters

​Response

​Response Headers

​Error Responses

​Example Request

​Delete Sandbox

​Path Parameters

​Response

​Response Headers

​Error Responses

​Example Request

​Renew Sandbox Expiration

​Path Parameters

​Request Body

​Response

​Response Headers

​Status Code

​Error Responses

​Example Request

​Example Response

​Get Sandbox

​Path Parameters

​Response

​Response Headers

​Status Code

​Error Responses

​Example Request

​Example Response

​List Sandboxes

​Query Parameters

​Response

​Response Headers

​Status Code

​Error Responses

​Example Request

​Example Response

Build docs developers (and LLMs) love

Pause Sandbox

Path Parameters

Response

Response Headers

Error Responses

Example Request

Resume Sandbox

Path Parameters

Response

Response Headers

Error Responses

Example Request

Delete Sandbox

Path Parameters

Response

Response Headers

Error Responses

Example Request

Renew Sandbox Expiration

Path Parameters

Request Body

Response

Response Headers

Status Code

Error Responses

Example Request

Example Response

Get Sandbox

Path Parameters

Response

Response Headers

Status Code

Error Responses

Example Request

Example Response

List Sandboxes

Query Parameters

Response

Response Headers

Status Code

Error Responses

Example Request

Example Response