Create Sandbox

Creates a new sandbox from a container image with optional resource limits, environment variables, and metadata. Sandboxes are provisioned directly from the specified image without requiring a pre-created template.

Authentication

API Key authentication is required via the OPEN-SANDBOX-API-KEY header.

Request Body

image

object

required

Container image specification for the sandbox

Show properties

uri

string

required

Container image URI in standard format.Examples:

"python:3.11" (Docker Hub)
"ubuntu:22.04"
"gcr.io/my-project/model-server:v1.0"
"private-registry.company.com:5000/app:latest"

auth

object

Registry authentication credentials (required for private registries)

Show properties

username

string

Registry username or service account

password

string

Registry password or authentication token

timeout

integer

required

Sandbox timeout in seconds. The sandbox will automatically terminate after this duration.

Minimum: 60
Maximum: 86400

SDK clients should provide a default value (e.g., 3600 seconds / 1 hour).

resourceLimits

object

required

Runtime resource constraints for the sandbox instance. Similar to Kubernetes resource specifications.SDK clients should provide sensible defaults (e.g., cpu: "500m", memory: "512Mi").Common resource types:

cpu: CPU allocation in millicores (e.g., “250m” for 0.25 CPU cores)
memory: Memory allocation in bytes or human-readable format (e.g., “512Mi”, “1Gi”)
gpu: Number of GPU devices (e.g., “1”)

Example:

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

entrypoint

array

required

The command to execute as the sandbox’s entry process (required).Explicitly specifies the user’s expected main process, allowing the sandbox management service to reliably inject control processes before executing this command.Format: [executable, arg1, arg2, ...]Examples:

["python", "/app/main.py"]
["/bin/bash"]
["java", "-jar", "/app/app.jar"]
["node", "server.js"]

env

object

Environment variables to inject into the sandbox runtime.Example:

{
  "API_KEY": "secret-key",
  "DEBUG": "true",
  "LOG_LEVEL": "info"
}

metadata

object

Custom key-value metadata for management, filtering, and tagging.Use “name” key for a human-readable identifier.Example:

{
  "name": "Data Processing Sandbox",
  "project": "data-processing",
  "team": "ml",
  "environment": "staging"
}

networkPolicy

object

Optional outbound network policy for the sandbox. If omitted or empty, the sidecar starts in allow-all mode until updated.

Show properties

defaultAction

string

Default action when no egress rule matches. Defaults to “deny”.Values: allow, deny

egress

array

List of egress rules evaluated in order.

Show rule properties

action

string

required

Whether to allow or deny matching targets.Values: allow, deny

target

string

required

FQDN or wildcard domain (e.g., “example.com”, “*.example.com”).IP/CIDR not yet supported in the egress MVP.

volumes

array

Storage mounts for the sandbox. Each volume entry specifies a named backend-specific storage source and common mount settings.

Show volume properties

name

string

required

Unique identifier for the volume within the sandbox.Must be a valid DNS label (lowercase alphanumeric, hyphens allowed, max 63 chars).

mountPath

string

required

Absolute path inside the container where the volume is mounted.Must start with ’/’.

readOnly

boolean

If true, the volume is mounted as read-only. Defaults to false (read-write).

subPath

string

Optional subdirectory under the backend path to mount.Must be a relative path without ’..’ components.

host

object

Host path bind mount backend. Maps a directory on the host filesystem into the container.

Show properties

path

string

required

Absolute path on the host filesystem to mount.Must start with ’/’ and be under an allowed prefix.

pvc

object

Platform-managed named volume backend.

Show properties

claimName

string

required

Name of the volume on the target platform.In Kubernetes this is the PVC name; in Docker this is the named volume name.

extensions

object

Opaque container for provider-specific or transient parameters not supported by the core API.

This field is reserved for internal features, experimental flags, or temporary behaviors. Standard parameters should be proposed as core API fields.

Best Practices:

Namespacing: Use prefixed keys (e.g., storage.id) to prevent collisions.
Pass-through: SDKs and middleware must treat this object as opaque and pass it through transparently.

Response

string

Unique sandbox identifier

status

object

Current lifecycle status and detailed state information

Show properties

state

string

Current lifecycle state of the sandbox (“Pending” on creation)

reason

string

Short machine-readable reason code for the current state.Examples: “user_delete”, “ttl_expiry”, “provision_timeout”, “runtime_error”

message

string

Human-readable message describing the current state or reason for state transition

lastTransitionAt

string

Timestamp of the last state transition (RFC 3339 format)

metadata

object

Custom metadata from creation request

entrypoint

array

Entry process specification from creation request

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

Location

string

URI of the newly created sandbox resource

The create response does not include image and updatedAt fields. Use GET /v1/sandboxes/{sandboxId} to retrieve the complete sandbox information including image spec.

Status Code

202

Accepted

Sandbox created and accepted for provisioning.The returned sandbox includes:

id: Unique sandbox identifier
status.state: "Pending" (auto-starting provisioning)
status.reason and status.message indicating initialization stage
metadata, expiresAt, createdAt: Core sandbox information

To track provisioning progress, poll GET /v1/sandboxes/{sandboxId}. The sandbox will automatically transition to Running state once provisioning completes.

Error Responses

400

Bad Request

The request was invalid or malformed

401

Unauthorized

Authentication credentials are missing or invalid

409

Conflict

The operation conflicts with the current state

500

Internal Server Error

An unexpected server error occurred

Example Request

Deny by default with allowed domains

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"
    },
    "timeout": 3600,
    "resourceLimits": {
      "cpu": "500m",
      "memory": "512Mi"
    },
    "entrypoint": ["python", "/app/main.py"],
    "networkPolicy": {
      "defaultAction": "deny",
      "egress": [
        {
          "action": "allow",
          "target": "pypi.org"
        }
      ]
    }
  }'

Allow by default with a deny rule

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"
    },
    "timeout": 3600,
    "resourceLimits": {
      "cpu": "500m",
      "memory": "512Mi"
    },
    "entrypoint": ["python", "/app/main.py"],
    "networkPolicy": {
      "defaultAction": "allow",
      "egress": [
        {
          "action": "deny",
          "target": "bad.example.com"
        }
      ]
    }
  }'

Example Response

{
  "id": "sandbox-abc123",
  "status": {
    "state": "Pending",
    "reason": "provisioning",
    "message": "Sandbox is being provisioned",
    "lastTransitionAt": "2026-03-01T10:30:00Z"
  },
  "metadata": {},
  "entrypoint": ["python", "/app/main.py"],
  "expiresAt": "2026-03-01T11:30:00Z",
  "createdAt": "2026-03-01T10:30:00Z"
}

Lifecycle API

Execution API

SDK Reference

Authentication

Request Body

Response

Response Headers

Status Code

Error Responses

Example Request

Deny by default with allowed domains

Allow by default with a deny rule

Example Response

Build docs developers (and LLMs) love

Lifecycle API

Execution API

SDK Reference

​Authentication

​Request Body

​Response

​Response Headers

​Status Code

​Error Responses

​Example Request

​Deny by default with allowed domains

​Allow by default with a deny rule

​Example Response

Build docs developers (and LLMs) love

Authentication

Request Body

Response

Response Headers

Status Code

Error Responses

Example Request

Deny by default with allowed domains

Allow by default with a deny rule

Example Response