Skip to main content
POST
Create Sandbox
Create a new sandbox.
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.
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.
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).
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.
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.
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.