Desktop ›

Create desktop link

POST/v1/sandboxes/{id}/desktop/links

Makes a link to the sandbox's desktop, at an address of its own, for someone to watch the screen, or use it as well, until the link expires: 10 minutes from now unless expiresIn says otherwise. A link to watch leads to a second VNC server in the machine that takes no keys, clicks or clipboard, so what makes it watch-only is the machine and not the page. The desktop has to be turned on and running. The url of GET /v1/sandboxes/{id}/desktop stays as it is. Up to 20 links that have not expired.

RequestTypeScript

import { Agental } from "agental-sdk";
const agental = new Agental();
const sandbox = await agental.sandboxes.get("sbx_2a9a47e50daec64a");
const link = await sandbox.desktop.createLink({
access: "view",
expiresIn: 600,
});

Answer201 Created · DesktopLink

{
"id": string,
"access": "view" | "control",
"url": string | null,
"createdAt": string,
"expiresAt": string,
"cutOnExpiry": boolean,
}

The link, and where it leads.

Path

idrequired

string

e.g. "sbx_0123456789abcdef"

Headers

Authorizationrequired

Bearer key

An API key that may make this call.

Body

`access`required "view" \| "control"	view to watch only, control to use it as well.
`expiresIn` integer	Seconds until the link expires, from 60 to 86400. 600 when it is left out. e.g. `600`
`cutOnExpiry` boolean	Whether a stream that is open through the link is cut when it expires. true when it is left out. false lets it play on until it is closed or the desktop is turned off, and the link opens no new one.

Returns

201 The link, and where it leads.

DesktopLink6 fields

id

string

access

viewcontrol

view: whoever opens it sees the screen, and cannot click, type or paste on it.

control: they can use it as well.

url

stringnull

Where the link leads, in a browser.

It needs no token and is hard to guess: keep it as a password is kept until it expires. Null where GET /v1/policy says publicUrls is false.

createdAt

string

expiresAt

string

From when the link leads nowhere.

cutOnExpiry

boolean

Whether a stream that is open through the link is cut when it expires.

False lets it play on, and the link still opens none after.

Errors and other answers

404	Not found.
409	sandbox_not_running; desktop_not_running: no desktop is turned on, or it is not running now; desktop_unavailable: the machine was made from an image whose desktop cannot be watched without being used, and only access control works; too_many_links: the sandbox has 20 that have not expired.
501	`desktop_not_configured` sandboxes here have no desktop; public_urls_not_configured: sandboxes here have no public addresses, so a link would lead nowhere.

Every error answers { "error": { "code", "message" } }; a key without the action a call needs answers 403 key_action_forbidden, naming it.

← List desktop links Delete desktop link →