Desktop

Desktop links, and the routes the desktop viewer uses with them.

Create a desktop link

POST /v1/instances/{name}/desktop-link

Mints a reusable link to the Kiste's desktop at desktop.kiste.run. It opens only in browsers signed in to your account, any number of times, until it expires. ttl_seconds defaults to 3600 and must be between 60 and 604800 (seven days). Several links can be live at once; a stop and resume of the Kiste keeps them.

Path parameters:

Name	Type	Required	Description
`name`	string	yes	The Kiste's name.

curl -sS -X POST "https://kiste.run/v1/instances/review-42/desktop-link" \
  -H "Authorization: Bearer $KISTE_TOKEN"

Request body (optional): CreateDesktopLinkRequest

Field	Type	Required	Description
`ttl_seconds`	integer (int32) or null	no

Responses:

200 OK. Body: DesktopLinkResponse

Errors use the error envelope.

Revoke desktop links

DELETE /v1/instances/{name}/desktop-link

Revokes every live desktop link of the Kiste and answers how many. Desktops already open in a browser keep running; revocation only stops new browsers from joining.

Path parameters:

Name	Type	Required	Description
`name`	string	yes	The Kiste's name.

curl -sS -X DELETE "https://kiste.run/v1/instances/review-42/desktop-link" \
  -H "Authorization: Bearer $KISTE_TOKEN"

Responses:

200 OK. Body: RevokeDesktopLinksResponse

Errors use the error envelope.

Check desktop readiness

POST /v1/desktop/native/preflight

Used by the desktop viewer: answers 204 once the desktop can stream, a retryable error while it is still starting. It needs the desktop link and your signed-in account; a link alone opens nothing.

Request body: DesktopBootstrapPreflightRequest

Field	Type	Required	Description
`machine`	string	yes
`protocol`	string	yes

Responses:

204 No content.

Errors use the error envelope.

Start a desktop session

POST /v1/desktop/native/session

Used by the desktop viewer: exchanges a desktop link for this browser's own stream session. The link is not used up. The browser's session lasts 24 hours, independent of the link.

Request body: DesktopBootstrapRequest

Field	Type	Required	Description
`machine`	string	yes
`protocol`	string	yes

Responses:

200 OK. Body: DesktopSessionResponse

Errors use the error envelope.

Re-enter a desktop session

POST /v1/desktop/native/session/renew

Used by the desktop viewer after a reload, with the session the browser already holds.

Request body: DesktopBootstrapRequest

Field	Type	Required	Description
`machine`	string	yes
`protocol`	string	yes

Responses:

200 OK. Body: DesktopSessionResponse

Errors use the error envelope.

Connect the desktop stream

POST /v1/desktop/native/{session}/offer

Used by the desktop viewer: exchanges the browser's WebRTC offer for the answer that starts video and audio.

Path parameters:

Name	Type	Required	Description
`session`	string	yes	The desktop session.

Request body: NativeOfferRequest

Field	Type	Required	Description
`sdp`	string	yes

Responses:

200 OK. Body: NativeOfferResponse

Errors use the error envelope.

End a desktop session

DELETE /v1/desktop/native/session/{session}

Used by the desktop viewer: ends this browser's desktop session.

Path parameters:

Name	Type	Required	Description
`session`	string	yes	The desktop session.

Responses:

204 No content.

Errors use the error envelope.

Connect the recovery console

GET /v1/desktop/recovery/{session}

Used by the desktop viewer: the recovery console, a plain remote-framebuffer view of the desktop for when the video stream cannot start. It has its own short-lived authorization.

Path parameters:

Name	Type	Required	Description
`session`	string	yes	The desktop session.

Responses:

101 WebSocket upgrade.

Errors use the error envelope.

On this page