Sign in

v5

latestOpenAPI 3.0.3raw.githubusercontent.com2026-07-01224150.1 KB
Sandboxes

Create a sandbox

Provisions a sandbox synchronously. The request blocks until the sandbox is ready (~2–3s typical). Returns 201 with status: "ready". Use a client timeout of at least 90 seconds. On provisioning failure the API returns 503.

GET /sandboxes/{id}/wait remains for reconnect edge cases (e.g. after resume); it is not required after create.

Network egress

Control outbound network access at create time with the egress object, or the legacy blockOutbound: true shorthand (maps to deny_all). You cannot set both on the same request.

egress.modeBehavior
openFull outbound internet (default when omitted)
deny_allAll outbound connections blocked
restrictedDefault deny + allowlist in egress.allow

Change policy later with PUT /sandboxes/{id}/egress.

post/sandboxes

Request body

namestring

Display name. Auto-generated (random animal) if omitted.

templatestring

Template name from the available sandbox images (e.g. node-22, python-3.12). Defaults to the server's configured default.

teamIdstring

Create the sandbox under a team you're a member of. Copy the team ID from the team's settings page in the dashboard. Omit for a personal sandbox.

environmentIdstring

Project-environment ObjectId to scope the sandbox to.

regionstring

Region id from GET /v1/regions, or "auto" to let the server pick one for you. Optional; defaults to "auto" when omitted.

autoDestroyboolean

If true, sandbox auto-destroys after destroyTimeout.

destroyTimeout'30m' | '1h' | '3h' | '6h' | '12h' | '18h'

Required when autoDestroy=true. Ignored otherwise.

oneShotboolean

If true, sandbox auto-destroys when its main process exits.

blockOutboundboolean

Legacy shorthand for egress.mode = deny_all. Prefer egress for new integrations. Cannot be combined with egress on the same request.

persistentboolean

Provision a fresh per-sandbox persistent volume for the sandbox's workspace directory.

persistentDiskGBinteger

Required when persistent=true. Mutually exclusive with volumeId.

volumeIdstring

Attach an existing detached volume. Mutually exclusive with persistent / persistentDiskGB.

fromSnapshotstring

Restore from a snapshot you own; replaces the template image.

snapshotMode'manual' | 'automatic'
snapshotFrequencystring

5-field cron expression (e.g. 0 */2 * * *). Required when snapshotMode=automatic, forbidden otherwise.

Example request

{
  "egress": {
    "mode": "restricted",
    "allow": [
      "1.1.1.1",
      "api.example.com"
    ]
  }
}

Response

Sandbox provisioned and ready

messagestring required

Example response

{
  "message": "Sandbox created"
}