Skip to main content
POST
/
api
/
sandboxes
Create Sandbox
curl --request POST \
  --url https://app.opencomputer.dev/api/sandboxes \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "templateID": "<string>",
  "timeout": 123,
  "cpuCount": 123,
  "memoryMB": 123,
  "burst": true,
  "envs": {},
  "metadata": {},
  "image": {},
  "snapshot": "<string>",
  "previewAuth": {}
}
'
{
  "sandboxID": "sb-abc123",
  "status": "running",
  "region": "use2",
  "workerID": "w-use2-abc123",
  "previewAuthToken": "qx2sSi5IYXWBvnnRqwK9Ky_cIAI-x0Vx1bPCt0XMxsI"
}
Create a new sandbox.
​
templateID
string
Template name (default: "base")
​
timeout
integer
Idle timeout in seconds (default: 300)
​
cpuCount
integer
CPU cores. If omitted but memoryMB is set, inferred automatically.
​
memoryMB
integer
Memory in MB. If omitted but cpuCount is set, inferred automatically.
​
burst
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.
​
envs
object
Environment variables as key-value pairs
​
metadata
object
Arbitrary key-value pairs
​
image
object
Declarative image manifest (see Image builder)
​
snapshot
string
Name of a pre-built snapshot for instant boot
​
previewAuth
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.
{
  "sandboxID": "sb-abc123",
  "status": "running",
  "region": "use2",
  "workerID": "w-use2-abc123",
  "previewAuthToken": "qx2sSi5IYXWBvnnRqwK9Ky_cIAI-x0Vx1bPCt0XMxsI"
}