Skip to main content
POST
Create a sandbox

Authorizations

Authorization
string
header
required

A team API key, sk_offstage_…, created in the console. Everything it touches belongs to its team.

Headers

Idempotency-Key
string

Any unique string. A retry with the same key and body within 24 hours answers 201 with what the first request made, as it is now, instead of creating again, including after a plane restart; the same key with a different body is 409 idempotency-key-reused. Failures are not remembered. Scoped to the team and the route.

Required string length: 1 - 255

Body

application/json

Optional: an empty body is a default sandbox.

Unknown fields are refused with 400 unknown-field.

snapshotId
string

Saved snapshot ID or committed name. The session defaults to its saved type.

session
enum<string>
default:headless

headless: the slot's user with no desktop; every slot takes it from boot. gui: the slot's logged-in desktop session, remade after every customer, so gui slots are scarce.

Available options:
headless,
gui
timeoutMs
integer
default:900000

Sandbox lifetime. A restore starts this timer when ready. Default 15 minutes, maximum 24 hours.

Required range: 1 <= x <= 86400000
idleTimeoutMs
integer
default:600000

Closes after this long without activity, pending or ready. Default10minutes (or timeoutMs if shorter). Polling GET while unclaimed pending renews the idle lease; queue cap15minutes still applies.

Required range: 1 <= x <= 86400000
name
string

1 to 48 lowercase letters, digits and inner hyphens. Left out, the plane picks an adjective-noun name. 409 name-taken if an open sandbox of the team already has it.

Required string length: 1 - 48
Pattern: ^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$
record
boolean

Keep a recording of a gui sandbox's screen (its timeline: pictures, commands, agent steps). Default true for gui; a headless sandbox has no screen to record.

secrets
string[]

Existing team names. Encoded selected payload at most120 KiB; at most one apple-signing bundle.

Required array length: 1 - 16 elements
Pattern: ^[A-Za-z_][A-Za-z0-9_-]{0,63}$

Response

The sandbox, usually pending. A replay with the same Idempotency-Key and body answers 201 with that sandbox as it is now (the same id, in its current state), with idempotent-replayed: true.

A sandbox: one Mac slot (a macOS user account) held for the team. Files persist between calls. Fields that do not apply yet are absent, not null.

id
string
required

sbx_….

Pattern: ^sbx_
name
string
required

What people call it, like swift-otter: picked at creation unless you choose one, and unique among the team's open sandboxes. Routes take the id, not the name.

Required string length: 1 - 48
Pattern: ^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$
session
enum<string>
required

headless: the slot's user with no desktop; every slot takes it from boot. gui: the slot's logged-in desktop session, remade after every customer, so gui slots are scarce.

Available options:
headless,
gui
state
enum<string>
required

pending until a slot takes it, ready while it is held, then closed.

Available options:
pending,
ready,
closed
createdAt
integer
required

A time, in Unix milliseconds.

Required range: x >= 0
expiresAt
integer
required

Current deadline in Unix milliseconds. For a restore, the sandbox lifetime starts when setup succeeds.

Required range: x >= 0
timeoutMs
integer
required

Sandbox lifetime, counted from creation or, for a restore, from readiness.

Required range: x >= 1
idleTimeoutMs
integer
required

It closes after this long with no op.

Required range: x >= 1
lastActivityAt
integer
required

A time, in Unix milliseconds.

Required range: x >= 0
ops
integer
required

Commands, file calls and screenshots run in it so far. The pictures the plane takes for its recording are not counted.

Required range: x >= 0
costUsd
number
required

What its time on a Mac costs: so far while open, final once closed.

createdBy
object
required

Who started the work: {keyName} for an API key, {email} for a console user.

snapshotId
string

The source snapshot ID when restored.

boxId
string

The Mac holding it. Absent until a slot takes it.

Pattern: ^box_
slot
integer

The slot on that Mac. Absent until taken.

Required range: x >= 1
readyAt
integer

When it became ready; billing starts here. Absent until then.

Required range: x >= 0
closedAt
integer

Absent until it closes.

Required range: x >= 0
closeReason
enum<string>

Absent until it closes.

Available options:
deleted,
expired,
idle,
box-lost,
plane-restart,
no-capacity,
restore-failed,
secret-unavailable
runtimeSeconds
integer

Whole seconds from ready to closed (or now). Absent until ready.

Required range: x >= 0
record
boolean

Whether the plane keeps a recording of it: true for a gui sandbox unless created with record: false.

replayUrl
string

Where to watch it, live while it is open and as a replay after: the console's /r/{id} page. Present when it records.