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": [ { "archived": true, "class": "linux", "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", "gpu_count": 0, "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": "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", "vcpus": 0, "vcpus_max": 0, "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.
cpu?|Reserved CPU cores.
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: the writable layer's size. Same semantics
as vcpus_max; a disk-snapshot restore requires it equal to the
captured disk, or 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_SANDBOX_TOKEN, DAYTONA_API_URL,
DAYTONA_OTEL_ENDPOINT and DAYTONA_DOCKER_START, 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 vcpus_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.
persistent?booleanWhether writable state persists across stops. Defaults to false.
ports?array<>Ports exposed when the sandbox starts.
region?|Target region. The project default is used when omitted.
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.
vcpus?|Reserved virtual CPU count.
int32vcpus_max?|Maximum virtual CPU count.
int32volumes?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 macOS reservation selected by a successful claim; null until a Mac claims the sandbox.
status*stringInitial lifecycle status — pending, or the sandbox's current status on
an idempotent replay.
toolbox_proxy_url*stringThe sandbox's own region's toolbox proxy base URL, the same value
GET /sandboxes/{id} carries — exec/fs/preview traffic must target
this, not a global proxy.
wait_cap_seconds*integerMaximum server-side create wait in seconds.
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": [ { "archived": true, "class": "linux", "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", "gpu_count": 0, "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": "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", "vcpus": 0, "vcpus_max": 0 } ]}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?|Target region. The snapshot region is used when omitted.
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 macOS reservation selected by a successful claim; null until a Mac claims the sandbox.
status*stringInitial lifecycle status — pending, or the sandbox's current status on
an idempotent replay.
toolbox_proxy_url*stringThe sandbox's own region's toolbox proxy base URL, the same value
GET /sandboxes/{id} carries — exec/fs/preview traffic must target
this, not a global proxy.
wait_cap_seconds*integerMaximum server-side create wait in seconds.
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 GPU sandbox when GPU sandboxes are available to the organization.
AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
application/json- body
Settings for creating a GPU sandbox from an image.
cpu?|Reserved CPU cores.
doublecreate_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: the writable layer's size. Same semantics
as vcpus_max; a disk-snapshot restore requires it equal to the
captured disk, or absent.
int32disk_mib?|Writable disk size in MiB.
int32env?Environment variables defined when the sandbox is created.
gpu?array<string>PCI addresses of dedicated GPUs.
gpu_host?integerThe number of shared GPUs to attach. Mutually exclusive with gpu,
which attaches dedicated GPUs.
int320 <= valueidempotency_key?|Key used to replay the same create operation safely.
image*stringImage ID or name.
labels?User-defined labels.
lifecycle_policy?|Automatic timeout and idle-expiry behavior.
memory_max_mib?|Per-sandbox memory limit in MiB; same semantics as vcpus_max.
int32memory_mib?|Reserved memory in MiB.
int32name?|Sandbox name. A name is generated when omitted.
ports?array<>Ports exposed when the sandbox starts.
region?|Target region. The project default is used when omitted.
secrets?array<string>Secret names made available to the sandbox.
user?|Default operating-system user.
vcpus?|Reserved virtual CPU count.
int32vcpus_max?|Maximum virtual CPU count.
int32wait_seconds?|Seconds to wait before returning. Defaults to 3; 0 returns immediately.
int64Accepted: the GPU 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 macOS reservation selected by a successful claim; null until a Mac claims the sandbox.
status*stringInitial lifecycle status — pending, or the sandbox's current status on
an idempotent replay.
toolbox_proxy_url*stringThe sandbox's own region's toolbox proxy base URL, the same value
GET /sandboxes/{id} carries — exec/fs/preview traffic must target
this, not a global proxy.
wait_cap_seconds*integerMaximum server-side create wait in seconds.
int640 <= valuecurl -X POST 'https://example.com/sandboxes/gpu' \ -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}Creates a GPU sandbox from a snapshot when GPU sandboxes are available to the organization.
AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
application/json- body
Settings for creating a GPU 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?|Target region. The snapshot region is used when omitted.
snapshot*stringSnapshot ID or name.
wait_seconds?|Seconds to wait before returning. Defaults to 3; 0 returns immediately.
int64Accepted: the GPU 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 macOS reservation selected by a successful claim; null until a Mac claims the sandbox.
status*stringInitial lifecycle status — pending, or the sandbox's current status on
an idempotent replay.
toolbox_proxy_url*stringThe sandbox's own region's toolbox proxy base URL, the same value
GET /sandboxes/{id} carries — exec/fs/preview traffic must target
this, not a global proxy.
wait_cap_seconds*integerMaximum server-side create wait in seconds.
int640 <= valuecurl -X POST 'https://example.com/sandboxes/gpu/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 the organization reserves. Acceptance checks the current fit but allocates no reservation resources: concurrent creates can compete for the same room, and an accepted sandbox can wait for room or time out.
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.
create_timeout_seconds?|Seconds the sandbox may take to reach running. 3600 by default; a
create from a saved sandbox disk defaults to 3600 plus the time to
download that disk at the platform's minimum restore rate, at most
86400. -1 uses the maximum. Past it the sandbox is deleted. The
budget runs while the sandbox waits for a Mac, including one whose
reservation this create bought: that reservation stays bought and
charged when the sandbox is deleted.
int64disk_mib?|Disk for this sandbox in MiB, at least 81920: the whole guest disk, macOS included. Omitted or null uses half of the claiming Mac model's sandbox disk room, rounded down to a whole GiB, when its reservation's sandboxes_per_mac is 2, or all of it when it is 1. The first successful claim fixes the size; request and limit are equal. A stopped sandbox keeps holding its disk on its Mac.
int3281920 <= valueenv?Sandbox-specific environment variables. Names must satisfy the shared guest-env rules.
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 base image,
typically base-macos, or a macOS image of this project in the
request's region, such as a saved sandbox disk. The Mac clones a base
from the copy it holds; a saved disk's changed blocks are downloaded
first, so its create takes longer.
labels?User-defined labels. They are stored by the platform and are not visible inside the sandbox.
lifecycle_policy?|Sandbox lifecycle policy (idle stop/delete budgets and a wall-clock
deadline). The pause action and wake-on-request are linux-only; use
POST /sandboxes/{id}/pause to pause a macOS sandbox. The project's
lifecycle defaults do not apply to a macOS sandbox: a field that this
request does not set gets the platform default.
memory_mib?|Memory for this sandbox in MiB, at least 4096. Omitted or null uses half of the claiming Mac's memory, rounded down, when its reservation's sandboxes_per_mac is 2, or all of it when it is 1. The first successful claim fixes the size; request and limit are equal.
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 on its Mac across stop/start and keep memory across pause/resume. Start and resume use the same Mac. Delete erases the disk. At reservation end, the disk is saved as an anonymous image before the Mac is erased. If the Mac is lost, the disk is saved as an image when the Mac comes back, if it comes back within 7 days. If a Mac restarts before it is declared lost, a running persistent sandbox comes back stopped with its disk, a running ephemeral sandbox is lost, and stopped and paused sandboxes are unchanged. Create a sandbox from an image to continue on another Mac.
ports?array<>Ports exposed when the sandbox starts.
region?|The target region. When omitted, uses the named reservation's region.
With neither a region nor a named reservation: when this API serves
exactly one region with Macs, the sandbox is created there; when it
serves several, a region is required (400 BAD_REQUEST) unless the
project or organization default is one of them; otherwise the project,
organization, then platform default applies.
reservation?|Omitted uses any fitting Mac reservation of this organization in the region. "new" buys the cheapest available model that fits. A reservation ID targets that reservation at claim. Acceptance does not reserve room; the sandbox can wait for room or time out.
secrets?array<string>Names of project secrets to attach, as on the Linux create. The sandbox sees each as a placeholder; the value is swapped in on requests to the secret's allowed hosts.
vcpus?|CPU cores for this sandbox, at least 4. Omitted or null uses half of the claiming Mac's cores, rounded down, when its reservation's sandboxes_per_mac is 2, or all of them when it is 1. The first successful claim fixes the size; request and limit are equal.
int324 <= valuevolumes?array<>Disk volumes to attach, as on Linux: at most 8, each read-write. A sandbox with volumes cannot be persistent, and a bucket volume answers 400.
wait_seconds?|Seconds to hold the response until the sandbox is running, capped
at 3 by default. Absent holds for the cap, 0 answers at once, and a
negative value answers 400. The response carries the sandbox's status
when the hold ends: running if it got there in time, as a warm Mac's
claim usually does, otherwise its status then, such as pending.
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 macOS reservation selected by a successful claim; null until a Mac claims the sandbox.
status*stringInitial lifecycle status — pending, or the sandbox's current status on
an idempotent replay.
toolbox_proxy_url*stringThe sandbox's own region's toolbox proxy base URL, the same value
GET /sandboxes/{id} carries — exec/fs/preview traffic must target
this, not a global proxy.
wait_cap_seconds*integerMaximum server-side create wait in seconds.
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?stringComma-separated region slugs. 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.
persistent?booleanPersistent sandboxes only (true) or ephemeral sandboxes only
(false).
spot?booleanSpot-tier sandboxes only (true) or on-demand only (false).
forked_from?stringSandboxes forked from this sandbox ID.
min_vcpus?integerInclusive lower bound on vCPUs.
int64max_vcpus?integerInclusive upper bound on vCPUs.
int64min_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""vcpus""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": [ { "archived": true, "class": "linux", "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", "gpu_count": 0, "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": "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", "vcpus": 0, "vcpus_max": 0, "cursor": "string" } ], "total": 0, "total_relation": "eq"}Creates a Windows sandbox when Windows sandboxes are available to the organization.
AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
application/json- body
Settings for creating a Windows sandbox from an image.
cpu?|Reserved CPU cores.
doublecreate_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: the writable layer's size. Same semantics
as vcpus_max; a disk-snapshot restore requires it equal to the
captured disk, or absent.
int32disk_mib?|Writable disk size in MiB.
int32env?Environment variables defined when the sandbox is created.
idempotency_key?|Key used to replay the same create operation safely.
image*stringImage ID or name.
labels?User-defined labels.
lifecycle_policy?|Automatic timeout and idle-expiry behavior.
memory_max_mib?|Per-sandbox memory limit in MiB; same semantics as vcpus_max.
int32memory_mib?|Reserved memory in MiB.
int32name?|Sandbox name. A name is generated when omitted.
persistent?booleanWhether writable state persists across stops. Defaults to false.
ports?array<>Ports exposed when the sandbox starts.
region?|Target region. The project default is used when omitted.
secrets?array<string>Secret names made available to the sandbox.
spot?booleanWhether to use discounted interruptible capacity. Defaults to false.
vcpus?|Reserved virtual CPU count.
int32vcpus_max?|Maximum virtual CPU count.
int32wait_seconds?|Seconds to wait before returning. Defaults to 3; 0 returns immediately.
int64Accepted: the Windows 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 macOS reservation selected by a successful claim; null until a Mac claims the sandbox.
status*stringInitial lifecycle status — pending, or the sandbox's current status on
an idempotent replay.
toolbox_proxy_url*stringThe sandbox's own region's toolbox proxy base URL, the same value
GET /sandboxes/{id} carries — exec/fs/preview traffic must target
this, not a global proxy.
wait_cap_seconds*integerMaximum server-side create wait in seconds.
int640 <= valuecurl -X POST 'https://example.com/sandboxes/windows' \ -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}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.
archived?|Whether the sandbox's disk is archived to object storage; its next start restores the disk first. The status is unaffected.
class*SandboxClassSandbox class.
"linux""windows""gpu""macos"cpu*numberReserved CPU cores.
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.
gpu_count?|Number of attached GPUs.
int32id*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 writable state persists across stops.
port_map*array<>Port assignments reported for the sandbox.
region*stringRegion containing the sandbox.
reservation_id?|The macOS reservation of the current or latest successful claim; null before the first claim and 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.
vcpus*integerReserved virtual CPU count.
int32vcpus_max?|Maximum virtual CPU count.
int32curl -X GET 'https://example.com/sandboxes/string'{ "archived": true, "class": "linux", "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", "gpu_count": 0, "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": "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", "vcpus": 0, "vcpus_max": 0}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. Returned only here and never stored.
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"}Moves a stopped persistent Linux sandbox's disk to object storage now, whatever its archive interval. Its next start restores the disk first.
AuthorizationBearer <token>Bearer project API key.
Scope: write:sandboxes
sandbox_id*stringThe sandbox ID
The sandbox, unchanged: it is already archived
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/archive'{ "id": "string", "status": "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*stringGuest path the link addresses, verbatim (the canonical and the URL's
path query parameter carry the same string).
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 guest path, as signed.
signature*stringThe link's signature. Pass it back unchanged.
url*stringThe full pre-signed URL against the sandbox region's toolbox proxy.
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 entirely for a memory fork with the default name
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 own region's toolbox proxy base URL (a fork lands in its
source's region), the same value GET /sandboxes/{id} carries.
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 stored label set.
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.
archive_interval_seconds?|Seconds a stopped sandbox waits before it is archived: its disk moves
to object storage, and its next start restores it first. 60..=2592000
(30 days); 0 means the maximum and is stored as 2592000. Omitted at
create: one day (86400 s). Linux persistent only; a sandbox with
volumes keeps its interval but is not archived yet.
int640 <= value <= 2592000nullidle_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 <= 2147483647nullwake_on_request?|Whether incoming traffic resumes a stopped persistent Linux sandbox.
nullThe sandbox lifecycle policy
application/json- response
Response for PATCH /sandboxes/{id}/lifecycle-policy and
POST /sandboxes/{id}/reset-idle-timer (class-blind: one route for every
class) — one echo shape for every lifecycle mutation.
id*stringThe sandbox ID.
lifecycle_policy*The stored policy after the update, plus the derived read-only facts.
curl -X PATCH 'https://example.com/sandboxes/string/lifecycle-policy' \ -H 'Content-Type: application/json' \ -d '{}'{ "id": "string", "lifecycle_policy": { "archive_interval_seconds": 0, "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, "wake_on_request": true }}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).
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
Response for PATCH /sandboxes/{id}/lifecycle-policy and
POST /sandboxes/{id}/reset-idle-timer (class-blind: one route for every
class) — one echo shape for every lifecycle mutation.
id*stringThe sandbox ID.
lifecycle_policy*The stored policy after the update, plus the derived read-only facts.
curl -X POST 'https://example.com/sandboxes/string/reset-idle-timer'{ "id": "string", "lifecycle_policy": { "archive_interval_seconds": 0, "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, "wake_on_request": true }}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 unresolved_legacy.
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 unresolved_legacy.
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: Start the stored disk at its fixed size on the same Mac and live reservation. This operation never buys a reservation or moves the disk.
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. A macOS sandbox keeps its disk on the same Mac until it is deleted, its reservation ends, or the Mac is lost.
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"}