Create Sandbox

Create a new sandbox from a container image

POST /v1/sandboxes

Create Sandbox

cURL

curl --request POST \
  --url https://api.example.com/v1/sandboxes \
  --header 'Content-Type: application/json' \
  --data '
{
  "image": {
    "uri": "<string>",
    "auth": {
      "username": "<string>",
      "password": "<string>"
    }
  },
  "timeout": 123,
  "resourceLimits": {},
  "entrypoint": [
    {}
  ],
  "env": {},
  "metadata": {},
  "networkPolicy": {
    "defaultAction": "<string>",
    "egress": [
      {
        "action": "<string>",
        "target": "<string>"
      }
    ]
  },
  "volumes": [
    {
      "name": "<string>",
      "mountPath": "<string>",
      "readOnly": true,
      "subPath": "<string>",
      "host": {
        "path": "<string>"
      },
      "pvc": {
        "claimName": "<string>"
      }
    }
  ],
  "extensions": {}
}
'

200

{
  "202": {},
  "400": {},
  "401": {},
  "409": {},
  "500": {},
  "id": "<string>",
  "status": {
    "state": "<string>",
    "reason": "<string>",
    "message": "<string>",
    "lastTransitionAt": "<string>"
  },
  "metadata": {},
  "entrypoint": [
    {}
  ],
  "expiresAt": "<string>",
  "createdAt": "<string>",
  "X-Request-ID": "<string>",
  "Location": "<string>"
}

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

id · 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"
}