Desktops

List desktops

GET /v1/desktops

curl -sS "$BASE/desktops?state=awake" -H "$AUTH"

{ "desktops": [ /* DesktopJson[] */ ] }

Create a desktop

POST /v1/desktops

Request body (CreateDesktopBody):

{
  "tier": "small",
  "billing_mode": "hourly",
  "image_version": null,
  "idle_timeout_secs": null,
  "env": null,
  "setup_script": null
}

curl -sS -X POST "$BASE/desktops" \
  -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{
    "tier": "small",
    "billing_mode": "hourly",
    "env": {"APP_ENV": "staging"},
    "setup_script": "#!/bin/sh\napt-get update && apt-get install -y ripgrep\n"
  }'

See Concepts: env and setup_script for the full charset/cap rules and the /root/.canto/env guest layout.

Both 200 and 201 return a full DesktopJson.

Get a desktop

GET /v1/desktops/{id}

curl -sS "$BASE/desktops/$DESKTOP_ID" -H "$AUTH"

Update a desktop

PATCH /v1/desktops/{id}

Today the only updatable field is idle_timeout_secs -- see Concepts: TTL and auto-hibernate.

Request body (UpdateDesktopBody, required; an empty/all-omitted body is a no-op):

{ "idle_timeout_secs": 3600 }

curl -sS -X PATCH "$BASE/desktops/$DESKTOP_ID" \
  -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"idle_timeout_secs": 3600}'

Wake / hibernate / destroy

POST /v1/desktops/{id}/wake POST /v1/desktops/{id}/hibernate POST /v1/desktops/{id}/destroy

These three share an identical request/response shape.

Request body (MutationBody, optional -- an empty body is equivalent to {}):

{ "expected_generation": null }

expected_generation is an optional fencing generation the caller expects the desktop to currently be on -- see Concepts: generation fencing.

curl -sS -X POST "$BASE/desktops/$DESKTOP_ID/wake?wait=true" -H "$AUTH"
curl -sS -X POST "$BASE/desktops/$DESKTOP_ID/hibernate?wait=true" -H "$AUTH"
curl -sS -X POST "$BASE/desktops/$DESKTOP_ID/destroy?wait=true" -H "$AUTH"

Both 200 and 202 return an OperationJson -- see API reference: Operations for its shape and Concepts: Operations for the polling model.

Fork a desktop

POST /v1/desktops/{id}/fork

Creates count new, independent desktops as memory-snapshot copies of a Hibernated source desktop. See Concepts: Forking for the full model (copy-on-write semantics, acknowledge_shared_state, ephemeral forks).

Request body (ForkBody):

{ "count": 3, "acknowledge_shared_state": true, "ephemeral": false }

curl -sS -X POST "$BASE/desktops/$DESKTOP_ID/fork?wait=true" \
  -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"count": 3, "acknowledge_shared_state": true}'

On success, the settled operation's result carries {"desktop_ids": ["...", "...", "..."]}. Forks come back in the Hibernated state -- wake each one on demand, they don't start Awake.