Sandboxes
region*stringThe event stream region tag, or _ when sandbox IDs carry no region tag
The sandbox event stream
curl -X GET 'https://example.com/events/string'AuthorizationBearer <token>Bearer project API key.
Scope: read:sandboxes
region*stringThe event stream region tag, or _ when sandbox IDs carry no region tag
The sandbox event ticket
application/json- response
expires_in_ms*integerMilliseconds until the ticket expires unused.
int640 <= valuesubprotocol*stringProtocol negotiated for the event stream.
ticket*stringOne-time value presented when opening the event stream.
curl -X POST 'https://example.com/events/string/ticket'{ "expires_in_ms": 0, "subprotocol": "string", "ticket": "string"}AuthorizationBearer <token>Bearer project API key.
Scope: read:sandboxes
limit?integerMaximum number of items to return, 1–200 (default 100)
int641 <= value <= 200100cursor?stringOpaque continuation token returned as next_cursor by a previous request
The page of sandboxes
application/json- response
A page of sandboxes.
next_cursor?|The next page cursor, or null at the end.
sandboxes*array<>The sandboxes in this page.
curl -X GET 'https://example.com/sandboxes'{ "next_cursor": "string", "sandboxes": [ { "class": "linux", "cores_max": 0.1, "cpu": 0.1, "create_timeout_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "disk_max_mib": 0, "disk_mib": 0, "error": "string", "forked_from": "string", "id": "string", "image": null, "image_build_id": "1e3d8f2d-6818-44ae-8d8a-cebebd30fb2f", "image_ref": "string", "imported_from": { "id": "string", "platform": "string" }, "labels": { "property1": "string", "property2": "string" }, "last_activity_at": "2019-08-24T14:15:22Z", "lifecycle_policy": null, "mac_boot_mode": "string", "memory_max_mib": 0, "memory_mib": 0, "name": "string", "persistent": true, "port_map": [ { "host_port": 1, "proto": "tcp", "vm_port": 1 } ], "region_id": "string", "reservation_id": "string", "snapshot": null, "spot": true, "spot_evicted_at": "2019-08-24T14:15:22Z", "ssh_gateway_host": "string", "ssh_gateway_port": 0, "started_at": "2019-08-24T14:15:22Z", "status": "string", "stopped_at": "2019-08-24T14:15:22Z", "toolbox_proxy_url": "string", "updated_at": "2019-08-24T14:15:22Z", "user": "string", "cursor": "string" } ]}Creates a Linux sandbox when Linux sandboxes are available to the organization.
AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
application/json- body
Settings for creating a Linux sandbox from an image.
cores_max?|Maximum CPU, in cores (1 core = 2 vCPUs): the size the sandbox boots at. A positive multiple of 0.5; the system or plan cap when omitted.
doublecpu?|Reserved CPU, in cores (1 core = 2 vCPUs).
doublecpu_arch?|The CPU architecture the sandbox requires. Omit it to use the region
default — unless the image was imported from Daytona v0 and
cpu_type is omitted too, in which case the architecture that image
was imported for is used.
cpu_type?|Preferred CPU type.
create_timeout_seconds?|Seconds allowed for the sandbox to reach running. Defaults to 3600; -1 uses the maximum.
int64disk_max_mib?|Per-sandbox disk limit in MiB. Same semantics as cores_max; when
restoring a snapshot, it must equal the captured disk size or be absent.
int32disk_mib?|Writable disk size in MiB.
int32env?Sandbox-specific environment variables (real values, verbatim). Names
must be POSIX-ish identifiers ([A-Za-z_][A-Za-z0-9_]*). Names the
platform reserves for its own use, including every DAYTONA_* name
other than DAYTONA_API_URL, DAYTONA_OTEL_ENDPOINT and
DAYTONA_DOCKER_START (so DAYTONA_SANDBOX_TOKEN too), fail the
create with 400 naming the key.
idempotency_key?|Key used to replay the same create operation safely.
image?|Image name or img_… id. Omit to boot the platform default image.
labels?User-defined labels.
lifecycle_policy?|Automatic timeout and idle-expiry behavior.
memory_max_mib?|Per-sandbox memory limit in MiB; same semantics as cores_max.
int32memory_mib?|Reserved memory in MiB.
int32name?|Sandbox name. A name is generated when omitted.
network_policy?|Outbound network rules applied to the sandbox.
ports?array<>Ports exposed when the sandbox starts.
region_id?|The region to create the sandbox in. Any listed region, including
earth (anywhere). When omitted: the project's default region, then
the organization's, then earth.
secrets?array<string>Secret names made available to the sandbox.
spot?booleanWhether to use discounted interruptible capacity. Defaults to false.
user?|Default operating-system user.
volumes?array<>Volumes mounted in the sandbox.
wait_seconds?|Seconds to wait before returning. Defaults to 3; 0 returns immediately.
int64Accepted: the sandbox create
application/json- response
The result of an accepted sandbox create.
access_token?|Secret access value returned once, or null on a replay.
passwordaccess_token_expires_at?|When the access value expires, or null when it has no expiry or this is a replay.
date-timecreate_timeout_at?|Create deadline, or null after the sandbox reaches its target status.
date-timeid*stringThe sandbox ID.
image?|The image the sandbox boots. For a create without image, this is the
platform default image; omitted for a sandbox restored from a snapshot.
name*stringSandbox name (caller-provided or the generated sandbox-<short-id>).
reservation_id?|The Mac reservation that the sandbox runs on; null until the sandbox reaches a Mac.
status*stringInitial lifecycle status — pending, or the sandbox's current status on
an idempotent replay.
toolbox_proxy_url*stringThe sandbox’s toolbox base URL, also returned by GET /sandboxes/{id}. Use this URL for sandbox operations.
wait_cap_seconds*integerMaximum server-side create wait in seconds. 0 when the server skipped
the hold because the organization already has its limit of held
creates; wait for the rest of wait_seconds client-side.
int640 <= valuecurl -X POST 'https://example.com/sandboxes' \ -H 'Content-Type: application/json' \ -d '{}'{ "access_token": "pa$$word", "access_token_expires_at": "2019-08-24T14:15:22Z", "create_timeout_at": "2019-08-24T14:15:22Z", "id": "string", "image": null, "name": "string", "reservation_id": "string", "status": "string", "toolbox_proxy_url": "string", "wait_cap_seconds": 0}AuthorizationBearer <token>Bearer project API key.
Scope: read:sandboxes
ids*stringComma-separated sandbox IDs. At most 200 IDs are accepted.
wait?stringBlock until the resource reaches this status or a terminal status. Omit to return immediately.
wait_exact?stringExact status to wait for. Other terminal states do not satisfy it.
timeout_ms?integerMaximum time to block, in milliseconds. Default 30000, maximum 60000.
int640 <= valueThe sandboxes
application/json- response
The requested sandboxes, after the optional wait.
sandboxes*array<>The requested sandboxes.
curl -X GET 'https://example.com/sandboxes/batch-wait?ids=string'{ "sandboxes": [ { "class": "linux", "cores_max": 0.1, "cpu": 0.1, "create_timeout_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "disk_max_mib": 0, "disk_mib": 0, "error": "string", "forked_from": "string", "id": "string", "image": null, "image_build_id": "1e3d8f2d-6818-44ae-8d8a-cebebd30fb2f", "image_ref": "string", "imported_from": { "id": "string", "platform": "string" }, "labels": { "property1": "string", "property2": "string" }, "last_activity_at": "2019-08-24T14:15:22Z", "lifecycle_policy": null, "mac_boot_mode": "string", "memory_max_mib": 0, "memory_mib": 0, "name": "string", "persistent": true, "port_map": [ { "host_port": 1, "proto": "tcp", "vm_port": 1 } ], "region_id": "string", "reservation_id": "string", "snapshot": null, "spot": true, "spot_evicted_at": "2019-08-24T14:15:22Z", "ssh_gateway_host": "string", "ssh_gateway_port": 0, "started_at": "2019-08-24T14:15:22Z", "status": "string", "stopped_at": "2019-08-24T14:15:22Z", "toolbox_proxy_url": "string", "updated_at": "2019-08-24T14:15:22Z", "user": "string" } ]}Creates a Linux sandbox from a snapshot when Linux sandboxes are available to the organization.
AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
application/json- body
Settings for creating a Linux sandbox from a snapshot.
create_timeout_seconds?|Seconds allowed for the sandbox to reach running. Defaults to 3600; -1 uses the maximum.
int64idempotency_key?|Key used to replay the same create operation safely.
labels?User-defined labels.
lifecycle_policy?|Automatic timeout and idle-expiry behavior.
name?|Sandbox name. A name is generated when omitted.
ports?array<>Ports exposed when the sandbox starts.
region_id?|The region to create the sandbox in. When omitted, the snapshot's region.
snapshot*stringSnapshot name or snap_… id. Required.
wait_seconds?|Seconds to wait before returning. Defaults to 3; 0 returns immediately.
int64Accepted: the sandbox create from a snapshot
application/json- response
The result of an accepted sandbox create.
access_token?|Secret access value returned once, or null on a replay.
passwordaccess_token_expires_at?|When the access value expires, or null when it has no expiry or this is a replay.
date-timecreate_timeout_at?|Create deadline, or null after the sandbox reaches its target status.
date-timeid*stringThe sandbox ID.
image?|The image the sandbox boots. For a create without image, this is the
platform default image; omitted for a sandbox restored from a snapshot.
name*stringSandbox name (caller-provided or the generated sandbox-<short-id>).
reservation_id?|The Mac reservation that the sandbox runs on; null until the sandbox reaches a Mac.
status*stringInitial lifecycle status — pending, or the sandbox's current status on
an idempotent replay.
toolbox_proxy_url*stringThe sandbox’s toolbox base URL, also returned by GET /sandboxes/{id}. Use this URL for sandbox operations.
wait_cap_seconds*integerMaximum server-side create wait in seconds. 0 when the server skipped
the hold because the organization already has its limit of held
creates; wait for the rest of wait_seconds client-side.
int640 <= valuecurl -X POST 'https://example.com/sandboxes/from-snapshot' \ -H 'Content-Type: application/json' \ -d '{ "snapshot": "string"}'{ "access_token": "pa$$word", "access_token_expires_at": "2019-08-24T14:15:22Z", "create_timeout_at": "2019-08-24T14:15:22Z", "id": "string", "image": null, "name": "string", "reservation_id": "string", "status": "string", "toolbox_proxy_url": "string", "wait_cap_seconds": 0}Creates a macOS sandbox on a Mac reservation of the organization. The sizes of the sandboxes on one Mac must fit that Mac. An accepted create can wait for space on a Mac until create_timeout_seconds.
AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
application/json- body
Settings for creating a macOS sandbox.
auto_renew?|With reservation: "new" only: whether the bought reservation renews itself
while a sandbox is active on it. Defaults to the organization's
auto-reserve setting.
cores?|CPU cores for this sandbox, at least 4. A Mac core is one CPU of the Mac (Apple Silicon has no SMT). Omitted or null uses the Mac model's default size (default_size in GET /mac-models).
int324 <= valuecreate_timeout_seconds?|Seconds the sandbox can take to reach running: 3600 by default, or
86400 for an image captured on an earlier version of macOS sandboxes.
-1 uses the maximum, 86400. After this time, the platform deletes the
sandbox. The time includes the wait for a Mac. A reservation that this
create bought stays bought and charged after that delete.
int64disk_mib?|Disk for this sandbox in MiB, macOS included, at least 81920. Omitted or null uses the Mac model's default size (default_size in GET /mac-models). For a create from a captured image, omitted or null uses the image's disk_mib, and a smaller value returns 400. The disk and the disk volumes must fit the disk space of the sandbox's Mac (sandbox_disk_mib in GET /mac-models).
int3281920 <= valueenv?Sandbox-specific environment variables. Names must be valid environment variable names.
idempotency_key?|Idempotency key; the Idempotency-Key header wins if both are set.
It also covers a reservation the create buys: a retry never buys two.
image*stringThe macOS image, by name or img_… id: a platform macOS image,
typically base-macos, or a macOS image of this project in the
request's region, such as an image captured from a macOS sandbox.
labels?User-defined labels. Not visible inside the sandbox.
lifecycle_policy?|Sandbox lifecycle policy: idle stop and delete timeouts and a wall-clock deadline. Use POST /sandboxes/{id}/pause to pause a macOS sandbox. Project lifecycle defaults do not apply to macOS: omitted fields use platform defaults.
memory_mib?|Memory for this sandbox in MiB, at least 4096. Omitted or null uses the Mac model's default size (default_size in GET /mac-models).
int324096 <= valuename?|Optional sandbox name (defaults to sandbox-<short-id>).
network_policy?|Egress policy, as on the Linux create: enforced from the sandbox's
first boot. Change it later with PUT /sandboxes/{id}/network-policy.
persistent?booleanKeep the sandbox's disk and machine across stop and start, and its memory across pause and resume. A start can run on any Mac of the organization. After a start on a different Mac, iCloud asks the user to sign in again. A reservation end or a Mac failure stops a sandbox that has started and never deletes it.
ports?array<>Ports exposed when the sandbox starts.
region_id?|The region to create the sandbox in. When omitted: the named
reservation's region. Otherwise, when Macs are offered in exactly one
region, that region; when they are offered in several, the project's or
organization's default region if it is one of them, else region_id is
required (400 BAD_REQUEST). With no Mac region offered, the project's
default region, then the organization's, then earth.
reservation?|Omitted uses any Mac reservation of the organization in the region that fits this size. "new" buys a reservation of the cheapest available Mac model that fits this size. A reservation ID uses only that reservation. An accepted create can wait for space on a Mac until create_timeout_seconds.
secrets?array<string>Names of project secrets to attach. Secret values are used only for requests to their allowed hosts.
volumes?array<>Disk volumes to attach, as on Linux: at most 8, each read-write. Each
volume uses its size_gib (100 GiB when omitted) of disk space on the
sandbox's Mac, beside the sandbox's disk. A sandbox with volumes cannot
be persistent. A bucket volume returns 400.
wait_seconds?|Seconds to hold the response until the sandbox is running, capped at 3 by default. Omitted uses the cap, 0 returns immediately, and a negative value returns 400. The response carries the status reached when the wait ends.
int64Accepted: the macOS sandbox create
application/json- response
The result of an accepted sandbox create.
access_token?|Secret access value returned once, or null on a replay.
passwordaccess_token_expires_at?|When the access value expires, or null when it has no expiry or this is a replay.
date-timecreate_timeout_at?|Create deadline, or null after the sandbox reaches its target status.
date-timeid*stringThe sandbox ID.
image?|The image the sandbox boots. For a create without image, this is the
platform default image; omitted for a sandbox restored from a snapshot.
name*stringSandbox name (caller-provided or the generated sandbox-<short-id>).
reservation_id?|The Mac reservation that the sandbox runs on; null until the sandbox reaches a Mac.
status*stringInitial lifecycle status — pending, or the sandbox's current status on
an idempotent replay.
toolbox_proxy_url*stringThe sandbox’s toolbox base URL, also returned by GET /sandboxes/{id}. Use this URL for sandbox operations.
wait_cap_seconds*integerMaximum server-side create wait in seconds. 0 when the server skipped
the hold because the organization already has its limit of held
creates; wait for the rest of wait_seconds client-side.
int640 <= valuecurl -X POST 'https://example.com/sandboxes/macos' \ -H 'Content-Type: application/json' \ -d '{ "image": "string"}'{ "access_token": "pa$$word", "access_token_expires_at": "2019-08-24T14:15:22Z", "create_timeout_at": "2019-08-24T14:15:22Z", "id": "string", "image": null, "name": "string", "reservation_id": "string", "status": "string", "toolbox_proxy_url": "string", "wait_cap_seconds": 0}Searches the project's sandboxes using the supplied filters. Results may be briefly stale after a change.
AuthorizationBearer <token>Bearer project API key.
Scope: read:sandboxes
q?stringFree text over the sandbox name and image_ref. A value that is a
sandbox ID matches that sandbox exactly.
name_prefix?stringname starts with this string (case-sensitive).
id_prefix?stringThe sandbox ID starts with this string.
status?array<>Comma-separated lifecycle statuses. An unrecognized value answers 400.
class?array<>Comma-separated sandbox classes.
region_ids?stringComma-separated region IDs. A broader region (a geo group, or
earth) matches every region inside it. An unknown region answers
400. Defaults to every region.
image_ref?stringExact image reference.
image_ref_prefix?stringimage_ref starts with this string.
labels?stringLabel containment filter: a JSON-encoded object {"k":"v",...}; only
sandboxes whose labels contain every pair match. A malformed or
non-object value answers 400. The whole query string, URL-encoded,
may be at most 12,288 bytes; a longer one answers 400.
persistent?booleanFilter by persistence: true for persistent macOS sandboxes, false for ephemeral sandboxes.
spot?booleanSpot-tier sandboxes only (true) or on-demand only (false).
forked_from?stringSandboxes forked from this sandbox ID.
reservation_id?stringmacOS sandboxes that run, or last ran, on this Mac reservation ID.
min_cores?numberInclusive lower bound on cores_max, in cores (1 core = 2 vCPUs).
doublemax_cores?numberInclusive upper bound on cores_max, in cores (1 core = 2 vCPUs).
doublemin_memory_mib?integerInclusive lower bound on memory_mib.
int64max_memory_mib?integerInclusive upper bound on memory_mib.
int64min_disk_mib?integerInclusive lower bound on disk_mib.
int64max_disk_mib?integerInclusive upper bound on disk_mib.
int64created_start_at?stringInclusive lower bound on creation time.
date-timecreated_end_at?stringExclusive upper bound on creation time.
date-timeupdated_start_at?stringInclusive lower bound on last-modified time.
date-timeupdated_end_at?stringExclusive upper bound on last-modified time.
date-timelast_activity_start_at?stringInclusive lower bound on last-activity time.
date-timelast_activity_end_at?stringExclusive upper bound on last-activity time.
date-timesort?stringSort field. Defaults to created_at; ties break on the ID.
"created_at""updated_at""last_activity_at""name""cores""memory_mib""disk_mib"order?stringSort order. Defaults to desc.
"asc""desc"limit?integerMaximum number of items to return, 1–200 (default 100)
int641 <= value <= 200100cursor?stringOpaque continuation token returned as next_cursor by a previous request
The page of matching sandboxes
application/json- response
A page of matching sandboxes.
next_cursor?|Continuation token for the next page; null on the last page.
sandboxes*array<>Matching sandboxes in this page.
total*integerThe number of matching sandboxes. Exact when total_relation is
eq, and a lower bound of 10000 when it is gte.
int640 <= valuetotal_relation*SearchTotalRelationWhether total is exact (eq) or a lower bound (gte).
"eq""gte"curl -X GET 'https://example.com/sandboxes/search'{ "next_cursor": "string", "sandboxes": [ { "class": "linux", "cores_max": 0.1, "cpu": 0.1, "create_timeout_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "disk_max_mib": 0, "disk_mib": 0, "error": "string", "forked_from": "string", "id": "string", "image": null, "image_build_id": "1e3d8f2d-6818-44ae-8d8a-cebebd30fb2f", "image_ref": "string", "imported_from": { "id": "string", "platform": "string" }, "labels": { "property1": "string", "property2": "string" }, "last_activity_at": "2019-08-24T14:15:22Z", "lifecycle_policy": null, "mac_boot_mode": "string", "memory_max_mib": 0, "memory_mib": 0, "name": "string", "persistent": true, "port_map": [ { "host_port": 1, "proto": "tcp", "vm_port": 1 } ], "region_id": "string", "reservation_id": "string", "snapshot": null, "spot": true, "spot_evicted_at": "2019-08-24T14:15:22Z", "ssh_gateway_host": "string", "ssh_gateway_port": 0, "started_at": "2019-08-24T14:15:22Z", "status": "string", "stopped_at": "2019-08-24T14:15:22Z", "toolbox_proxy_url": "string", "updated_at": "2019-08-24T14:15:22Z", "user": "string", "cursor": "string" } ], "total": 0, "total_relation": "eq"}AuthorizationBearer <token>Bearer project API key.
Scope: read:sandboxes
sandbox_id*stringThe sandbox ID
wait?stringBlock until the resource reaches this status or a terminal status. Omit to return immediately.
wait_exact?stringExact status to wait for. Another terminal status ends the wait without satisfying it.
timeout_ms?integerMaximum time to block, in milliseconds. Default 30000, maximum 60000.
int640 <= valueThe sandbox
application/json- response
A sandbox and its current configuration.
class*SandboxClassSandbox class.
"linux""macos"cores_max*numberMaximum CPU, in cores (1 core = 2 vCPUs): the size the sandbox boots at, a multiple of 0.5.
doublecpu*numberReserved CPU, in cores (1 core = 2 vCPUs).
doublecreate_timeout_at?|Create deadline; absent after the sandbox reaches its target status.
date-timecreated_at?|When the sandbox was created.
date-timedisk_max_mib?|Maximum writable disk size in MiB.
int32disk_mib*integerWritable disk size in MiB.
int32error?|Failure detail, or null when no failure is recorded.
forked_from?|Source sandbox ID when this sandbox is a fork.
id*stringThe sandbox ID.
image?|The image the sandbox was created from; absent when it was created from a snapshot.
image_build_id?|Build ID associated with the sandbox image.
uuidimage_ref?|The original image reference when no image resource is associated.
imported_from?The platform and sandbox ID this sandbox was imported from; absent for a sandbox created here.
labels?|User-defined sandbox labels.
last_activity_at?|When activity was last observed.
date-timelifecycle_policy?|Automatic timeout and idle-expiry behavior.
mac_boot_mode?|How a macOS sandbox resumed; absent when it has not resumed.
memory_max_mib?|Maximum memory in MiB.
int32memory_mib*integerReserved memory in MiB.
int32name*stringThe sandbox name.
persistent?|Whether the sandbox keeps its disk across stop and start.
port_map*array<>Port assignments reported for the sandbox.
region_id*stringThe region the sandbox runs in.
reservation_id?|The Mac reservation that the macOS sandbox runs on, or ran on last. Null before the sandbox first reaches a Mac; absent for other sandbox classes.
snapshot?|The snapshot the sandbox was created from; absent when it was created from an image.
spot?|Whether discounted interruptible capacity was requested.
spot_evicted_at?|When discounted capacity reclaimed the sandbox; absent when it has not been reclaimed.
date-timessh_gateway_host?|SSH gateway host for the sandbox region.
ssh_gateway_port?|SSH gateway port for the sandbox region.
int320 <= valuestarted_at?|When the sandbox most recently started.
date-timestatus*stringCurrent lifecycle status.
stopped_at?|When the sandbox most recently stopped.
date-timetoolbox_proxy_url?|Base URL for sandbox tools.
updated_at?|When the sandbox was last updated.
date-timeuser?|Default operating-system user.
curl -X GET 'https://example.com/sandboxes/string'{ "class": "linux", "cores_max": 0.1, "cpu": 0.1, "create_timeout_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "disk_max_mib": 0, "disk_mib": 0, "error": "string", "forked_from": "string", "id": "string", "image": null, "image_build_id": "1e3d8f2d-6818-44ae-8d8a-cebebd30fb2f", "image_ref": "string", "imported_from": { "id": "string", "platform": "string" }, "labels": { "property1": "string", "property2": "string" }, "last_activity_at": "2019-08-24T14:15:22Z", "lifecycle_policy": null, "mac_boot_mode": "string", "memory_max_mib": 0, "memory_mib": 0, "name": "string", "persistent": true, "port_map": [ { "host_port": 1, "proto": "tcp", "vm_port": 1 } ], "region_id": "string", "reservation_id": "string", "snapshot": null, "spot": true, "spot_evicted_at": "2019-08-24T14:15:22Z", "ssh_gateway_host": "string", "ssh_gateway_port": 0, "started_at": "2019-08-24T14:15:22Z", "status": "string", "stopped_at": "2019-08-24T14:15:22Z", "toolbox_proxy_url": "string", "updated_at": "2019-08-24T14:15:22Z", "user": "string"}Deletion is asynchronous. The sandbox leaves the list once it completes.
AuthorizationBearer <token>Bearer project API key.
Scope: delete:sandboxes
sandbox_id*stringThe sandbox ID
Accepted: the sandbox deletion
application/json- response
An accepted asynchronous operation.
id*stringThe ID of the resource the operation acts on.
status*stringThe resource's lifecycle status at acceptance.
curl -X DELETE 'https://example.com/sandboxes/string'{ "id": "string", "status": "string"}AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
sandbox_id*stringThe sandbox ID
application/json- body
The created sandbox access token
application/json- response
POST …/access-token response.
access_token*stringThe sandbox access token.
passwordexpires_at*stringAbsolute expiry (RFC 3339). The token cannot be refreshed — mint a fresh one through this route instead.
date-timeoperations*array<string>The granted operations, canonical order — echoes what the token's
scope claim carries.
ports?array<>|The granted ports (sorted, deduped), or null for all ports.
token_type*stringAlways Bearer.
curl -X POST 'https://example.com/sandboxes/string/access-token'{ "access_token": "pa$$word", "expires_at": "2019-08-24T14:15:22Z", "operations": [ "string" ], "ports": [ 0 ], "token_type": "string"}AuthorizationBearer <token>Bearer project API key.
Scope: read:sandboxes
sandbox_id*stringThe sandbox ID
The sandbox build logs URL
application/json- response
A link to build logs.
url*stringThe URL for reading the build logs.
curl -X GET 'https://example.com/sandboxes/string/build-logs-url'{ "url": "string"}AuthorizationBearer <token>Bearer project API key.
Scope: read:sandboxes
sandbox_id*stringThe sandbox ID
The sandbox console log
response?stringtext/plaincurl -X GET 'https://example.com/sandboxes/string/console-logs'"string"AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
sandbox_id*stringThe sandbox ID
application/json- body
A request to sign a sandbox file URL.
expires_at*stringAbsolute expiry. Must lie in the future and at most the deployment's signed-URL ceiling ahead (7 days by default).
date-timemethod*stringGET signs a download link (/files/download) and POST an upload
link (/files/upload); no other method can be signed.
path*stringSandbox file path the link addresses. The URL's path query parameter must match this string exactly.
The signed file URL
application/json- response
A signed sandbox file URL and the fields needed to recompose it.
expires_at*stringThe expiry that was signed.
date-timemethod*stringGET or POST, as signed.
path*stringThe sandbox file path, as signed.
signature*stringThe link's signature. Pass it back unchanged.
url*stringThe full pre-signed file URL.
curl -X POST 'https://example.com/sandboxes/string/files/sign' \ -H 'Content-Type: application/json' \ -d '{ "expires_at": "2019-08-24T14:15:22Z", "method": "string", "path": "string"}'{ "expires_at": "2019-08-24T14:15:22Z", "method": "string", "path": "string", "signature": "string", "url": "string"}AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
sandbox_id*stringThe sandbox ID
Optional body; omit it for a fork with the default name and the default memory.
application/json- body
Accepted: the sandbox fork
application/json- response
The result of forking a sandbox.
forked_from*stringThe ID of the source sandbox.
id*stringThe ID of the new fork.
status*stringThe fork's status at acceptance, always pending. A memory fork then
lands paused and a disk-only fork lands stopped; a fork of a
running source is brought up automatically.
toolbox_proxy_url*stringThe fork’s toolbox base URL in its source region, also returned by GET /sandboxes/{id}.
curl -X POST 'https://example.com/sandboxes/string/fork'{ "forked_from": "string", "id": "string", "status": "string", "toolbox_proxy_url": "string"}AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
sandbox_id*stringThe sandbox ID
application/json- body
Request body for PUT /sandboxes/{id}/labels: the full replacement label set.
labels?The new label set. It replaces the current one, and {} clears all
labels.
{}The sandbox labels
application/json- response
Response for PUT /sandboxes/{id}/labels.
id*stringThe sandbox ID.
labels*The sandbox’s labels.
curl -X PUT 'https://example.com/sandboxes/string/labels' \ -H 'Content-Type: application/json' \ -d '{}'{ "id": "string", "labels": { "property1": "string", "property2": "string" }}Updates the supplied lifecycle settings. Omitted settings remain unchanged.
AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
sandbox_id*stringThe sandbox ID
application/json- body
Sandbox lifecycle settings accepted during creation and lifecycle updates. Unknown fields return 400 instead of being ignored.
idle_expiry_seconds?|Idle seconds before the idle action runs. A value below 60 is raised to 60; use -1 to clear the idle expiry.
int64-1 <= value <= 2147483647nullon_idle_timeout?|Action to run when the idle expiry elapses.
nullon_timeout?|Action to run when the timeout expires.
nulltimeout_seconds?|Seconds before the timeout action runs. Supplying a value restarts the countdown.
int641 <= value <= 2147483647nullThe sandbox lifecycle policy
application/json- response
Lifecycle update response for PATCH /sandboxes/{id}/lifecycle-policy and POST /sandboxes/{id}/reset-idle-timer.
id*stringThe sandbox ID.
lifecycle_policy*The updated policy and its effective deadlines and activity information.
curl -X PATCH 'https://example.com/sandboxes/string/lifecycle-policy' \ -H 'Content-Type: application/json' \ -d '{}'{ "id": "string", "lifecycle_policy": { "idle_expiry_seconds": 0, "idle_timeout_at": "2019-08-24T14:15:22Z", "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_source": "string", "on_idle_timeout": null, "on_timeout": null, "timeout_at": "2019-08-24T14:15:22Z", "timeout_seconds": 0 }}AuthorizationBearer <token>Bearer project API key.
Scope: read:sandboxes
sandbox_id*stringThe sandbox ID
The sandbox log
response?stringtext/plaincurl -X GET 'https://example.com/sandboxes/string/logs'"string"AuthorizationBearer <token>Bearer project API key.
Scope: read:sandboxes
sandbox_id*stringThe sandbox ID
The sandbox network policy
application/json- response
applied?|Rules currently active for the sandbox, or null when the policy is open.
applied_revision?|Revision currently active for the sandbox.
int64applied_start_id?|The sandbox start the active revision was applied to, or null when
no revision is active.
desired?|Requested rules, or null when the policy is open.
desired_revision*integerRevision of the requested rules.
int64error?|Failure detail when the requested rules could not be applied.
status?|Application status of the requested rules.
curl -X GET 'https://example.com/sandboxes/string/network-policy'{ "applied": null, "applied_revision": 0, "applied_start_id": "string", "desired": null, "desired_revision": 0, "error": "string", "status": "string"}AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
sandbox_id*stringThe sandbox ID
If-Match*stringThe ETag from the last read or update of this policy
Full replacement. Send a JSON object to set the policy, or null to reset the sandbox to open network access. An empty body is rejected. With a non-null allow_domains, block_all defaults to true and setting it to false is rejected (NETWORK_POLICY_DOMAINS_REQUIRE_BLOCK_ALL). A non-empty allow_cidrs without default deny or a domain gate has no effect and is rejected (400 BAD_REQUEST). CIDRs with host bits set are rejected with the canonical network in the message.
application/json- body
Accepted: the sandbox network policy update
application/json- response
applied?|Rules currently active for the sandbox, or null when the policy is open.
applied_revision?|Revision currently active for the sandbox.
int64applied_start_id?|The sandbox start the active revision was applied to, or null when
no revision is active.
desired?|Requested rules, or null when the policy is open.
desired_revision*integerRevision of the requested rules.
int64error?|Failure detail when the requested rules could not be applied.
status?|Application status of the requested rules.
curl -X PUT 'https://example.com/sandboxes/string/network-policy' \ -H 'If-Match: string'{ "applied": null, "applied_revision": 0, "applied_start_id": "string", "desired": null, "desired_revision": 0, "error": "string", "status": "string"}AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
sandbox_id*stringThe sandbox ID
Accepted: the sandbox pause
application/json- response
An accepted asynchronous operation.
id*stringThe ID of the resource the operation acts on.
status*stringThe resource's lifecycle status at acceptance.
curl -X POST 'https://example.com/sandboxes/string/pause'{ "id": "string", "status": "string"}AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
sandbox_id*stringThe sandbox ID
The sandbox lifecycle policy
application/json- response
Lifecycle update response for PATCH /sandboxes/{id}/lifecycle-policy and POST /sandboxes/{id}/reset-idle-timer.
id*stringThe sandbox ID.
lifecycle_policy*The updated policy and its effective deadlines and activity information.
curl -X POST 'https://example.com/sandboxes/string/reset-idle-timer'{ "id": "string", "lifecycle_policy": { "idle_expiry_seconds": 0, "idle_timeout_at": "2019-08-24T14:15:22Z", "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_source": "string", "on_idle_timeout": null, "on_timeout": null, "timeout_at": "2019-08-24T14:15:22Z", "timeout_seconds": 0 }}AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
sandbox_id*stringThe sandbox ID
Accepted: the sandbox resume
application/json- response
An accepted asynchronous operation.
id*stringThe ID of the resource the operation acts on.
status*stringThe resource's lifecycle status at acceptance.
curl -X POST 'https://example.com/sandboxes/string/resume'{ "id": "string", "status": "string"}AuthorizationBearer <token>Bearer project API key.
Scope: read:sandboxes, read:secrets
sandbox_id*stringThe sandbox ID
The sandbox secrets
application/json- response
The secrets attached to a sandbox: the requested names and how far the sandbox has applied them.
applied_revision?|Revision the sandbox has applied, or null before the first one.
int64capture_status?|For a restored or forked sandbox, how much of the source's secrets the
copy received: complete, partial or an unknown status.
capture_unresolved_count?|For a partial copy, how many of the source's secrets the copy did not
receive.
int32desired_revision*integerRevision of the requested secrets.
int64error?|Failure detail when the requested secrets could not be applied.
secrets*array<string>Names of the project secrets requested for the sandbox.
status?|Application status of the requested secrets: pending, applied or
failed; null before the first change.
curl -X GET 'https://example.com/sandboxes/string/secrets'{ "applied_revision": 0, "capture_status": "string", "capture_unresolved_count": 0, "desired_revision": 0, "error": "string", "secrets": [ "string" ], "status": "string"}AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes, read:secrets
sandbox_id*stringThe sandbox ID
If-Match*stringThe ETag from the last read or update of these secrets
Full replacement of the secrets attached to the sandbox, by project secret name. Values are never sent or returned.
application/json- body
secrets*array<string>The complete desired set of project secret names. Required; send []
to detach every secret.
Accepted: the sandbox secrets update
application/json- response
The secrets attached to a sandbox: the requested names and how far the sandbox has applied them.
applied_revision?|Revision the sandbox has applied, or null before the first one.
int64capture_status?|For a restored or forked sandbox, how much of the source's secrets the
copy received: complete, partial or an unknown status.
capture_unresolved_count?|For a partial copy, how many of the source's secrets the copy did not
receive.
int32desired_revision*integerRevision of the requested secrets.
int64error?|Failure detail when the requested secrets could not be applied.
secrets*array<string>Names of the project secrets requested for the sandbox.
status?|Application status of the requested secrets: pending, applied or
failed; null before the first change.
curl -X PUT 'https://example.com/sandboxes/string/secrets' \ -H 'If-Match: string' \ -H 'Content-Type: application/json' \ -d '{ "secrets": [ "string" ]}'{ "applied_revision": 0, "capture_status": "string", "capture_unresolved_count": 0, "desired_revision": 0, "error": "string", "secrets": [ "string" ], "status": "string"}AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
sandbox_id*stringThe sandbox ID
Sandbox signing key rotated
curl -X POST 'https://example.com/sandboxes/string/signing-key/rotate'macOS: Starts the sandbox with its disk and size on any Mac of the organization. After a start on a different Mac, iCloud asks the user to sign in again. If the organization has no Mac reservation in the region and auto-reserve is on, the start buys one.
AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
sandbox_id*stringThe sandbox ID
Accepted: the sandbox start
application/json- response
An accepted asynchronous operation.
id*stringThe ID of the resource the operation acts on.
status*stringThe resource's lifecycle status at acceptance.
curl -X POST 'https://example.com/sandboxes/string/start'{ "id": "string", "status": "string"}Stops a persistent sandbox and keeps its disk. A sandbox that is not persistent cannot be stopped.
AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
sandbox_id*stringThe sandbox ID
Accepted: the sandbox stop
application/json- response
An accepted asynchronous operation.
id*stringThe ID of the resource the operation acts on.
status*stringThe resource's lifecycle status at acceptance.
curl -X POST 'https://example.com/sandboxes/string/stop'{ "id": "string", "status": "string"}