Create Sandbox

Create a new sandbox.

body templateIDstring

Template name (default: "base")

body timeoutinteger

Idle timeout in seconds (default: 300)

body cpuCountinteger

CPU cores. If omitted but memoryMB is set, inferred automatically.

body memoryMBinteger

Memory in MB. If omitted but cpuCount is set, inferred automatically.

body burstboolean

Create a Burst Sandbox. Disk is preserved across infrastructure restarts; processes may restart.

The 1 GB tier provides 1 vCPU on a best-effort basis. For guaranteed CPU allocation, use the 4 GB tier or above.

If both cpuCount and memoryMB are provided, they must match a platform tier.

body envsobject

Environment variables as key-value pairs

body metadataobject

Arbitrary key-value pairs

body imageobject

Declarative image manifest (see Image builder)

body snapshotstring

Name of a pre-built snapshot for instant boot

body webhooksobject[]

Register webhook destination(s) for this sandbox's lifecycle events, pinned to this sandbox. Registering inline (rather than via a separate call) means the endpoints exist before sandbox.created / sandbox.ready are relayed, so you don't miss the first events.

url (string, required): HTTPS endpoint.
secret (string): signing secret; omit and one is generated and returned on the response (webhooks[].secret), also re-fetchable later.
eventTypes (string[]): event-type allow-list (default all).

Each spec is validated up-front (same rules as POST /api/webhooks): a non-HTTPS url or unknown eventTypes is rejected with 400. Registration is otherwise best-effort — if a spec fails to register downstream, the sandbox is still created; inspect the echoed webhooks: [{ id, url, secret? }] to see what registered.

body previewAuthobject

Opt in to bearer-token authentication on the sandbox's preview URLs. When set, every request to https://sb-<id>-p<port>.<domain> must include an Authorization: Bearer <token> (or X-OC-Preview-Token: <token>) header; missing or wrong → 401.

scheme (string): must be "bearer". Reserved for HMAC/JWT later.
token (string): "auto" (or omitted) → server generates a 256-bit random token. An explicit string of at least 16 characters lets you bring your own.

The plaintext is returned exactly once in the response as previewAuthToken; only its SHA-256 hash is stored. Use POST /api/sandboxes/{id}/preview/rotate to mint a new one.

Omit this field for the legacy open behavior — preview URLs respond to anyone who can reach the hostname.

Ask AI about this page

Response example

12345678910{
  "sandboxID": "sb-abc123",
  "status": "running",
  "region": "use2",
  "workerID": "w-use2-abc123",
  "previewAuthToken": "qx2sSi5IYXWBvnnRqwK9Ky_cIAI-x0Vx1bPCt0XMxsI",
  "webhooks": [
    { "id": "whk_3f9a2c", "url": "https://app.example.com/oc-webhook", "secret": "whsec_Hk9…" }
  ]
}