> ## Documentation Index
> Fetch the complete documentation index at: https://opensandbox-oc-s-762ac928075c46d2828bcb22.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Sandbox

Create a new sandbox.

<ParamField body="templateID" type="string">
  Template name (default: `"base"`)
</ParamField>

<ParamField body="timeout" type="integer">
  Idle timeout in seconds (default: `0` — persistent, never auto-hibernates)
</ParamField>

<ParamField body="cpuCount" type="integer">
  CPU cores. If omitted but `memoryMB` is set, inferred automatically.
</ParamField>

<ParamField body="memoryMB" type="integer">
  Memory in MB. If omitted but `cpuCount` is set, inferred automatically.
</ParamField>

<ParamField body="burst" type="boolean">
  Create a [Burst Sandbox](/sandboxes/burst-sandboxes). Disk is preserved across infrastructure restarts; processes may restart.
</ParamField>

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.

<ParamField body="envs" type="object">
  Environment variables as key-value pairs
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value pairs
</ParamField>

<ParamField body="image" type="object">
  Declarative image manifest (see [Image builder](/sandboxes/templates#image-configuration))
</ParamField>

<ParamField body="snapshot" type="string">
  Name of a pre-built snapshot for instant boot
</ParamField>

<ParamField body="previewAuth" type="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`](/api-reference/preview/rotate-auth) to mint a new one.

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

<ResponseExample>
  ```json 201 theme={null}
  {
    "sandboxID": "sb-abc123",
    "status": "running",
    "region": "use2",
    "workerID": "w-use2-abc123",
    "previewAuthToken": "qx2sSi5IYXWBvnnRqwK9Ky_cIAI-x0Vx1bPCt0XMxsI"
  }
  ```

  `previewAuthToken` is only present when `previewAuth` was set in the request. Read it once and store it durably — the server will not return it again.
</ResponseExample>