Create Sandbox
Sandboxes
Create Sandbox
POST
Create Sandbox
Create a new sandbox.
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
string
Template name (default:
"base")integer
Idle timeout in seconds (default:
300)integer
CPU cores. If omitted but
memoryMB is set, inferred automatically.integer
Memory in MB. If omitted but
cpuCount is set, inferred automatically.boolean
Create a Burst Sandbox. Disk is preserved across infrastructure restarts; processes may restart.
cpuCount and memoryMB are provided, they must match a platform tier.
object
Environment variables as key-value pairs
object
Arbitrary key-value pairs
object
Declarative image manifest (see Image builder)
string
Name of a pre-built snapshot for instant boot
object[]
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).
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.object
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.
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.