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.mode	Behavior
open	Full outbound internet (default when omitted)
deny_all	All outbound connections blocked
restricted	Default 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"
}

Changes

Changed in 3 of the 5 revisions of this API.14

Jul 1, 20267fe2df04159712See the full diff
- ▲
  removed the success response with the status 200
  response-success-status-removed
- ○
  added the non-success response with the status 503
  response-non-success-status-added
- ○
  added the success response with the status 201
  response-success-status-added
Jun 29, 20264a016f074bc01See the full diff
- ○
  added the new optional request property egress
  new-optional-request-property
May 23, 2026b236bf76f9a71See the full diff
- ○
  the request property region became optional
  request-property-became-optional
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history