> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opencomputer.dev/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: `300`)
</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="webhooks" type="object[]">
  Register [webhook](/sandboxes/webhooks) 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`](/api-reference/webhooks/create)): 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.
</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",
    "webhooks": [
      { "id": "whk_3f9a2c", "url": "https://app.example.com/oc-webhook", "secret": "whsec_Hk9…" }
    ]
  }
  ```

  `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. `webhooks` is present only when `webhooks` were requested; each `secret` (`whsec_…`) is returned here and stays re-fetchable via [`GET /api/webhooks/{id}/secret`](/api-reference/webhooks/get).
</ResponseExample>