Snapshots

Accept a listing known to be short. Without it this endpoint answers 503 when a hypervisor holding some of your things cannot be reached, because a short list is not a smaller truth — it reads exactly like the missing ones were deleted, and the obvious next thing a script does with something that has disappeared is tidy it up. A snapshot on a host that cannot be reached is listed as its id and unreachable: true, and nothing else; a key scoped to a workspace gets no such rows, only the short answer. A row whose source computer cannot be found for certain carries computer_unreachable: true and no orphaned.

Widen the listing to snapshots whose deletion began and has not finished — their state reads deleting. Left out by default because a half-deleted snapshot is not one you can restore or clone, so a bare listing is the set you can actually act on. Poll with it to learn when a deletion has finished: the row goes then.

The computer these bytes came from. May name a computer that no longer exists.

For a computer that still exists, its current name — so a rename is reflected without re-reading anything. For an orphan, the name at capture, which is all there is. Absent on snapshots taken before the daemon recorded it.

True when no host that answered lists the source computer, and every host that did not answer is one the platform’s records show holding none of this account’s computers. False when a host lists it. Omitted when that cannot be established, with computer_unreachable: true. Also omitted on the row DELETE /snapshots/{id} answers with, which does not work it out; read it from GET /snapshots.

True when source computer presence cannot be established. Snapshot bytes may still be available; orphaned is omitted.

The snapshot has a usable copy on the current source computer host. False for old-host copies; clone remains available when the snapshot itself is reachable.

disk or memory.

Where these bytes have got to. capturing — the copy is still being taken, and this row is a placeholder rather than a snapshot: restore, clone and delete all 404 on it, though its id is already the id it will keep. pending — it is on the host and usable, and is being pushed to backup storage. durable — it is in backup storage too, which is the state your plan’s retention (GET /retention) ages out. deleting — a deletion began and has not finished, whether still under way or stalled; you only see these if you asked for them with include=unfinished.

Poll this after a capture, and wait for it to stop reading capturing rather than for it to read pending. pending is where a finished capture lands, but replication can carry it on to durable between two polls; both are states you can act on. A row that disappears without ever leaving capturing is a capture that failed.

A capture holds its computer until its upload to backup storage has finished, not just until it leaves capturing: a new capture of the SAME computer is refused (409, reason: "contention") while that upload runs, which is ordinarily for as long as this row reads pending, and is accepted once it reads durable. Restore, clone and delete all work from pending.

RFC 3339 timestamp.

The screen the capture was taken at, and what a clone of it comes up as.

Taken by the scheduler rather than by hand. Only these are ever aged out by your plan’s retention, and GET /retention is the window they are aged out on.

This snapshot is a link in a chain rather than a full copy, which is why it bills smaller.

As on Computer — a row from the placement cache, with nothing else on it.

The computer id.

Physical snapshot copies across the complete fleet, including duplicate IDs on different hosts, captures, and unfinished deletions.

The total currently reported bytes of those physical copies.

Whether the source computer is currently present. This presence is bound into the fingerprint. A snapshot-only cleanup confirmation must require false.

In-flight captures. Purge is refused while any remain.

Copies with unfinished deletion work.

Opaque versioned fingerprint binding scope, computer presence, host lifecycle identities and the exact physical copies. Pass it back as expect on DELETE /computers/{id}?snapshots=delete; a changed inventory is refused before mutation.

The computer id.

Defaults to the computer’s name, a space, and the UTC time the copy was taken as YYYY-MM-DD HH:MM. When you do not send one, the capturing row this call returns has an empty name until the capture lands.

Include the running session. The computer must be running, and one holding secrets must have finished receiving them, must not have had its bindings changed while it ran, and must be on a host that seals saved memory — each a 409 at admission otherwise, and a capture already accepted can still end afterwards for the same reasons; see above.

The computer these bytes came from. May name a computer that no longer exists.

For a computer that still exists, its current name — so a rename is reflected without re-reading anything. For an orphan, the name at capture, which is all there is. Absent on snapshots taken before the daemon recorded it.

True when no host that answered lists the source computer, and every host that did not answer is one the platform’s records show holding none of this account’s computers. False when a host lists it. Omitted when that cannot be established, with computer_unreachable: true. Also omitted on the row DELETE /snapshots/{id} answers with, which does not work it out; read it from GET /snapshots.

True when source computer presence cannot be established. Snapshot bytes may still be available; orphaned is omitted.

The snapshot has a usable copy on the current source computer host. False for old-host copies; clone remains available when the snapshot itself is reachable.

disk or memory.

Where these bytes have got to. capturing — the copy is still being taken, and this row is a placeholder rather than a snapshot: restore, clone and delete all 404 on it, though its id is already the id it will keep. pending — it is on the host and usable, and is being pushed to backup storage. durable — it is in backup storage too, which is the state your plan’s retention (GET /retention) ages out. deleting — a deletion began and has not finished, whether still under way or stalled; you only see these if you asked for them with include=unfinished.

Poll this after a capture, and wait for it to stop reading capturing rather than for it to read pending. pending is where a finished capture lands, but replication can carry it on to durable between two polls; both are states you can act on. A row that disappears without ever leaving capturing is a capture that failed.

A capture holds its computer until its upload to backup storage has finished, not just until it leaves capturing: a new capture of the SAME computer is refused (409, reason: "contention") while that upload runs, which is ordinarily for as long as this row reads pending, and is accepted once it reads durable. Restore, clone and delete all work from pending.

RFC 3339 timestamp.

The screen the capture was taken at, and what a clone of it comes up as.

Taken by the scheduler rather than by hand. Only these are ever aged out by your plan’s retention, and GET /retention is the window they are aged out on.

This snapshot is a link in a chain rather than a full copy, which is why it bills smaller.

As on Computer — a row from the placement cache, with nothing else on it.

The snapshot id.

Optional: a key of your choosing, 1 to 255 printable ASCII characters with no spaces (a UUID is ideal), that makes this call safe to send again after a lost answer. The call and its operation are recorded BEFORE it is carried out, so GET /operations?idempotency_key= finds it however the connection ended. For 24 hours, the same key with the byte-identical request (method, path, query and body, from a credential of the same scope) is not carried out again: it answers 409 idempotency_in_progress while the first is running, and the original answer — status and body, with Idempotent-Replayed: true — once it has finished. An answer too large to keep (over 1 MiB) is replayed instead as a 200 carrying {operation_id, operation}, also with Idempotent-Replayed: true: operation is the call’s operation, or null when there is none to show. Keys are kept per scope: a key used by a workspace's credential and the same key used by another workspace's, or by an account-wide one, are different keys, and neither is refused because of the other. A replayed body omits the desktop credentials the original carried (vnc, with its tokens and URLs): read the computer (GET /computers/{id}) for them. The same key on a different request is a 422 with code: "idempotency_key_reused", and a malformed key (empty, too long, outside printable ASCII, or the header sent twice) a 400 with code: "idempotency_key_invalid"; neither does anything. A call refused with a 4xx that did nothing releases its key, so it may be sent again under the same one. The exception is a delete whose 4xx says the computer was deleted — computer_deleted: true, or a purge result beside computer_deleted: false (it was deleted, then listed again): it happened, so its key keeps that answer and its operation is succeeded. Except a 409 with reason: "contention" whose purge deleted, queued and left in doubt nothing (the computer was already gone and copies in use refused the purge): nothing happened, so its key is released and the same request may be sent again under it. With computer_deleted: null, or false where the platform cannot confirm the computer was left in place, it is an unknown outcome: its key answers 409 idempotency_in_progress until the platform gives up on it, then 409 idempotency_outcome_unknown. A 5xx answer that names an operation_id is an unknown outcome too: that is the operation reserved for it. From then on the same key answers 409 idempotency_outcome_unknown, naming that operation (not idempotency_in_progress): read the computer, or the operation. The operation stays pending until the platform gives up on it; if it never learns how the call ended, it becomes failed with error.code: "lost". Some 5xx answers are refusals given before the call was sent anywhere — the platform could not check the account’s usage, or find a host for the call, for example — and some are a create or clone the host confirms it refused before building anything, such as a 503 from a host with no room left, and some are a start, restore or suspend the host confirms it refused before changing anything (a sealed session whose key could not be opened or whose transport failed first; on a suspend, suspend_outcome: "not_started"). Those name no operation_id: nothing was done, so the key is released as a 4xx refusal’s is, and the same call may be sent again under the same key. A host running older software cannot confirm such a refusal, so its 5xx is an unknown outcome like any other. A 5xx without an operation_id is not proof that nothing was done on its own: a call that records no operation (a PATCH that does not resize) names none, and neither does one whose operation could not be recorded. Sending the same call again under the same key is safe after any 5xx: it is carried out if its key was released, and answered 409 idempotency_outcome_unknown if not.

Always true. A failure is a status code, not ok: false.

This call’s operation, already succeeded: the step was done before the answer was sent. Read it with GET /operations/{id}. Absent, with the call still done, in the rare case the operation could not be recorded; a client must not treat its absence as a failure of the call.

The snapshot id.

Optional: a key of your choosing, 1 to 255 printable ASCII characters with no spaces (a UUID is ideal), that makes this call safe to send again after a lost answer. The call and its operation are recorded BEFORE it is carried out, so GET /operations?idempotency_key= finds it however the connection ended. For 24 hours, the same key with the byte-identical request (method, path, query and body, from a credential of the same scope) is not carried out again: it answers 409 idempotency_in_progress while the first is running, and the original answer — status and body, with Idempotent-Replayed: true — once it has finished. An answer too large to keep (over 1 MiB) is replayed instead as a 200 carrying {operation_id, operation}, also with Idempotent-Replayed: true: operation is the call’s operation, or null when there is none to show. Keys are kept per scope: a key used by a workspace's credential and the same key used by another workspace's, or by an account-wide one, are different keys, and neither is refused because of the other. A replayed body omits the desktop credentials the original carried (vnc, with its tokens and URLs): read the computer (GET /computers/{id}) for them. The same key on a different request is a 422 with code: "idempotency_key_reused", and a malformed key (empty, too long, outside printable ASCII, or the header sent twice) a 400 with code: "idempotency_key_invalid"; neither does anything. A call refused with a 4xx that did nothing releases its key, so it may be sent again under the same one. The exception is a delete whose 4xx says the computer was deleted — computer_deleted: true, or a purge result beside computer_deleted: false (it was deleted, then listed again): it happened, so its key keeps that answer and its operation is succeeded. Except a 409 with reason: "contention" whose purge deleted, queued and left in doubt nothing (the computer was already gone and copies in use refused the purge): nothing happened, so its key is released and the same request may be sent again under it. With computer_deleted: null, or false where the platform cannot confirm the computer was left in place, it is an unknown outcome: its key answers 409 idempotency_in_progress until the platform gives up on it, then 409 idempotency_outcome_unknown. A 5xx answer that names an operation_id is an unknown outcome too: that is the operation reserved for it. From then on the same key answers 409 idempotency_outcome_unknown, naming that operation (not idempotency_in_progress): read the computer, or the operation. The operation stays pending until the platform gives up on it; if it never learns how the call ended, it becomes failed with error.code: "lost". Some 5xx answers are refusals given before the call was sent anywhere — the platform could not check the account’s usage, or find a host for the call, for example — and some are a create or clone the host confirms it refused before building anything, such as a 503 from a host with no room left, and some are a start, restore or suspend the host confirms it refused before changing anything (a sealed session whose key could not be opened or whose transport failed first; on a suspend, suspend_outcome: "not_started"). Those name no operation_id: nothing was done, so the key is released as a 4xx refusal’s is, and the same call may be sent again under the same key. A host running older software cannot confirm such a refusal, so its 5xx is an unknown outcome like any other. A 5xx without an operation_id is not proof that nothing was done on its own: a call that records no operation (a PATCH that does not resize) names none, and neither does one whose operation could not be recorded. Sending the same call again under the same key is safe after any 5xx: it is carried out if its key was released, and answered 409 idempotency_outcome_unknown if not.

Name for the new computer. Defaults to the snapshot’s name followed by -restored. Cut to 64 characters, with control characters turned into spaces and the ends trimmed. A name left empty by that cleaning gets the default too.

Memory snapshots only: false builds from the disk alone; it lands stopped and boots fresh when started. Defaults to true. Ignored for a disk snapshot. A memory snapshot whose workspace was deleted needs false; see above.

Consent to resuming a memory snapshot of a computer that held secrets: the new computer holds the same credentials. Ignored for a snapshot that holds none, and when memory is false.

Stable identifier, e.g. vm-a1b2c3d4e5f6.

The name you gave it.

running, stopped, suspended, building, build-failed or half-removed. The last is a computer whose deletion stopped partway and took its disk with it: every call that needs a disk is refused on it, it will never start again, and deleting it again is what clears it. A client that treats an unknown status as stopped will offer a start this API always refuses, so read these as a closed set and everything outside it as not startable. A running computer can be paused by its host without its status changing. When the host is low on disk space, the guests writing fastest are paused, and when it is critically low every running computer on it is paused, including ones that wrote nothing. Screenshots, input and commands stall or fail meanwhile, and the computer resumes by itself once space recovers. A suspend or memory snapshot that fails can also leave it paused: always when the failure says “this computer remains paused because the host is low on disk space”, and other failures can, at any free space. While the platform holds it for disk-space recovery, start, restart, suspend and snapshot answer 503 (“waiting for disk-space recovery”) until it resumes by itself once that recovery can finish, and a stop discards the paused session. Nor does any computer start or resume on a host that is low on disk space: a start, a restart of a stopped computer and the resume that using a suspended computer sets off answer 503 (“this host is low on disk space…”), and a restore answers 503 too, until space on that host has been freed.

linux or windows.

The display protocol this computer’s desktop speaks: wayland, x11, or absent (X11, or a host too old to say); branch on === "wayland". Screenshots, input and exec behave identically either way. What differs on a Wayland computer is that a window id is the compositor’s address rather than an X window id — opaque and handed back the same way, but not comparable across the two — and that moving or resizing a window the compositor is TILING is refused rather than silently ignored, because a tiled window’s geometry belongs to the layout. Read it here rather than from the template: a computer keeps the image it was built from, and a template’s version can advance underneath it.

The template this computer was built from.

Cores.

The guest memory this computer is holding against your plan’s running pool: ram_mb while a process is live, or while a start or resume has been admitted and has not launched yet, and 0 otherwise. Non-zero BEFORE status says running, which is the point of publishing it — admission reserves the memory, and status is read from the guest process, which does not exist yet. So stopped with a non-zero value here is a cold boot on its way up, and suspended with one is a resume on its way up; 0 beside either means nothing has been admitted. Not proof that nothing will be: a start still waiting on this computer’s lifecycle lock has reserved nothing yet. ABSENT rather than 0 wherever this API cannot say — a host that could not be reached, a response written before the computer was read back (a create that answers with a start error, PATCH, either clone), or a host too old to report it. Absence means unknown, never zero.

The screen this guest renders at, as WIDTHxHEIGHTxDEPTH. This is the coordinate space every click and every screenshot is in — size your model prompts from it rather than by decoding a PNG. Chosen at create and fixed for the life of the computer.

The workspace this computer is in. Absent when it is in none. It can change: a stopped computer can be moved to another workspace, or to none, with PUT /computers/{id}/workspace or from the dashboard.

RFC 3339 timestamp.

Present only while status is building or build-failed.

Present only while status is suspended.

How long this computer may go untouched before its host suspends it. Absent on a computer with no override, which follows whatever its host is sweeping at. The host default is deliberately not reported in its place — it is a property of the host and it changes when an operator changes it.

The proxy this computer’s browsers are sent through — Chromium, Chrome where it is installed, and Firefox — as a managed policy each reads when it starts, locked so the browser’s own settings cannot override it. Only the browsers: exec, a terminal and every other program reach the network directly. Absent when none is set. Set at create or with PATCH /computers/{id}; a clone does not inherit it.

The proxy ALL of this computer’s outbound TCP is sent through, taken on its host at the computer’s network port, so nothing inside the computer is configured and nothing there can opt out: exec, terminals, package managers and browsers alike. Each connection is tunnelled to the host and port it was going to, by name where the connection says one (the TLS server name, or an HTTP Host) so the proxy resolves it, and otherwise by address. It FAILS CLOSED: when the proxy is down or refuses, the connection fails and nothing is sent directly. UDP to the internet is dropped (so QUIC falls back to TCP, and NTP and other UDP do not work), as is ICMP. DNS lookups still go to the platform’s resolver and are not proxied. Connections through the proxy are closed when the setting changes, and when the computer stops. One owner’s computers on a host hold at most 512 proxied connections at once together (256 through an https:// proxy), and fewer when the host is busy with other owners’; past that a new connection is closed at once. A connection whose server speaks first (SMTP, MySQL, an FTP control channel) waits about 250 ms for the computer to send first, then is tunnelled by address. A connection one side has finished is closed after 60 seconds of silence from the other side. Absent when none is set. Set at create or with PATCH /computers/{id}; a clone does not inherit it.

Present and true while a running computer’s egress_proxy names credentials_secret_id and its host does not hold that secret’s value yet — just after a create or a change, after the host restarts, or once the secret is deleted. Every connection the computer opens meanwhile is closed, never sent directly; it usually clears within seconds. It does NOT clear by itself once the computer’s workspace is deleted: its egress credentials then resolve account-wide only, so a proxy naming one of that workspace’s own secrets is held closed until it is saved again naming an account-wide secret. Never present on a computer that is not running.

Present and true while a running computer’s guest does not have its browser_proxy yet — just after a create, a start or a change — or still has the files of one just removed. Wait for it to go away before starting a browser that must use the proxy. A browser already running when the setting changes applies it at its next start (Chromium usually within seconds). Never present on a computer that is not running: the setting is applied as it starts.

Whether this computer exists, as the platform’s own record has it — a different question from status, which is what its host says it is doing. live: its host lists it. unreachable: its host has not answered — on a listing row, for this request; the computer is most likely fine and nothing has been done to it. deleting: a delete was sent and not yet answered. deleted and lost are terminal, and are only ever shown when asked for with state=: deleted is a delete that was answered, lost is a computer whose host was written off by an operator while it was unreachable. Present on listing rows; absent on a single computer, which is served by its host and is therefore live.

RFC 3339 timestamp of the answered delete. Present once state has been deleted.

RFC 3339 timestamp of the write-off. Present once state has been lost.

Present and true only on a row the platform served from its own record because the host holding this computer could not be reached. Such a row carries the computer’s identity — name, os, template, size, workspace_id, created_at, state — and nothing only its host knows: no status, no resolution. Its state is unreachable, or deleting when a delete is in flight for it. A listing with any such row carries X-GC-Incomplete, so you only ever see this after asking for a partial answer with allow_partial=1.

The secrets bound to this computer — at create, or since with PUT /computers/{id}/secrets — as references: which secret, which revision of it, and the environment variable or file each lands under. Never a value. Present only on a computer that holds secrets; every field in this group is absent on one that does not, except secrets_pending while it is true. On any host that seals saved sessions a computer that holds secrets restarts — by this API or from inside it — and gets its secrets again as it comes back up; a restart of a stopped one is refused (409, reason: "unavailable"): start it instead, which delivers its secrets. It suspends — by hand or when idle — and can be memory-snapshotted. A disk snapshot restored onto it starts it with its secrets delivered afresh; a memory snapshot restored onto it resumes holding what it held when the snapshot was taken, and is refused if it was taken without sealing or the platform will no longer open it (see POST /snapshots/{id}/restore). Taking disk snapshots, cloning, moving between hosts and deletion work as usual, and a clone starts with no secrets bound, unless it is a fork of one of its memory snapshots made with inherit_secrets: true.

How many delivering starts this computer has had. Each cold start of a computer that holds secrets is one generation; the receipt below names the generation it is for, so a receipt whose generation is behind this one is from an earlier start.

The receipt that the bound values reached this computer’s desktop session: which start, when, and which revision of each secret. This is the confirmation — a start that was taken but whose delivery did not land has no receipt for its generation and secrets_error says why. Absent before the first delivery.

Why the last delivering start was stopped, in one fixed sentence naming the class of failure and never a value. A start whose delivery fails is stopped by the host and stays stopped until you start it again; this is the reason. Cleared when the next delivering start begins. Absent when the last delivery landed or none has been tried.

Whether this computer’s desktop is missing a change to its secrets that a restart would deliver: a binding, an env name or file, or a newer value it does not hold — or, once every secret has been removed, whether its running or saved session still holds the values it had. Compared against the receipt, so it clears once any delivery lands — a start, a restart from anywhere, a reboot inside it, or a secret file replaced while it runs — and stays after one that failed. A value replaced for a secret bound as a file is replaced live on a running computer, and is pending only if that did not land. One bound as an environment variable is the same on an image that hands new shells the current values: once they see it, it is not pending, though programs already running — the desktop session among them — keep the value they started with until a restart; on any other image it waits for a restart. A change that removed a secret, or moved one to another revision, stays pending until a restart either way, since the running session may still hold the old value. Only ever true of a running or suspended computer: a suspended one resumes with the values it had, and a stopped one gets everything current when it starts, so it is never pending. null when it could not be checked — the current values could not be read, or the computer’s last delivery predates the record of the names it was made under and it has been rebound since; a restart makes it known. A delivery still on its way is not pending — wait on secrets_delivering for that. Present whenever secrets is, and on a computer with no secrets bound only while true.

Whether values are on their way into this computer’s desktop right now. A computer comes back running a few seconds before its secrets land, and a command run in between sees them unset; after a create, a start or a restart, wait for this to be false before relying on them. Also true from the moment a restart, or a reboot inside the computer, clears them until they are delivered again, and while a replaced value is written to a file. Reported by the computer’s host, which is doing the delivering. False on a computer that is not running and after a delivery that failed (secrets_error says why, and the computer is stopped). After a restart or a reboot it can also go back to false with nothing delivered and no secrets_error: that is a computer that has not come back up three minutes after it, and its secrets are not in it — restart it, or stop and start it. While it reads true only because a restarted computer has not come back up yet, a further restart is accepted, since that is the way out of one that does not; once the delivery itself has begun, a restart answers 409 until it lands. Present whenever secrets is.

Present only on the answer to a lifecycle call — a create, a clone, or a PATCH that resized — and never on a read: the operation it started, which GET /operations/{id} answers. A clone’s is running until its disk has been copied. Absent, with the call still done, in the rare case the operation could not be recorded; a client must not treat its absence as a failure of the call.

Present and true when a memory snapshot's session was asked for and the computer was built from the disk instead. Absent otherwise.

Why, when memory_dropped is set: secrets, for a snapshot of a computer that held secrets, cloned without inherit_secrets; bindings unrecorded, for one taken before its bindings were recorded, which cannot be resumed with them; capture unrecorded, for one taken before the platform recorded which capture each snapshot is, which cannot be resumed with them either.

The snapshot id.

The computer these bytes came from. May name a computer that no longer exists.

For a computer that still exists, its current name — so a rename is reflected without re-reading anything. For an orphan, the name at capture, which is all there is. Absent on snapshots taken before the daemon recorded it.

True when no host that answered lists the source computer, and every host that did not answer is one the platform’s records show holding none of this account’s computers. False when a host lists it. Omitted when that cannot be established, with computer_unreachable: true. Also omitted on the row DELETE /snapshots/{id} answers with, which does not work it out; read it from GET /snapshots.

True when source computer presence cannot be established. Snapshot bytes may still be available; orphaned is omitted.

The snapshot has a usable copy on the current source computer host. False for old-host copies; clone remains available when the snapshot itself is reachable.

disk or memory.

Where these bytes have got to. capturing — the copy is still being taken, and this row is a placeholder rather than a snapshot: restore, clone and delete all 404 on it, though its id is already the id it will keep. pending — it is on the host and usable, and is being pushed to backup storage. durable — it is in backup storage too, which is the state your plan’s retention (GET /retention) ages out. deleting — a deletion began and has not finished, whether still under way or stalled; you only see these if you asked for them with include=unfinished.

Poll this after a capture, and wait for it to stop reading capturing rather than for it to read pending. pending is where a finished capture lands, but replication can carry it on to durable between two polls; both are states you can act on. A row that disappears without ever leaving capturing is a capture that failed.

A capture holds its computer until its upload to backup storage has finished, not just until it leaves capturing: a new capture of the SAME computer is refused (409, reason: "contention") while that upload runs, which is ordinarily for as long as this row reads pending, and is accepted once it reads durable. Restore, clone and delete all work from pending.

RFC 3339 timestamp.

The screen the capture was taken at, and what a clone of it comes up as.

Taken by the scheduler rather than by hand. Only these are ever aged out by your plan’s retention, and GET /retention is the window they are aged out on.

This snapshot is a link in a chain rather than a full copy, which is why it bills smaller.

As on Computer — a row from the placement cache, with nothing else on it.