Sign in
Sandboxes

Create a sandbox

Provisions a sandbox asynchronously. The response returns immediately with status: "starting"; the sandbox transitions to ready (or failed) a few moments later. Poll GET /sandboxes/{id} until status flips, or watch the dashboard.

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 provisioning queued

messagestring required

Example response

{
  "message": "Sandbox creation started"
}

Changes