Desktop ›

Enable desktop

PUT/v1/sandboxes/{id}/desktop

Turns a desktop on for the sandbox. It is started in the sandbox's machine, and the answer says where to watch it. The sandbox has to be running. With no body the screen is 1280 by 800, or the size it already has. Asked again with the size it has, it changes nothing that is already so, and starts a desktop that had ended. Asked with another size, the desktop is started again at that size, which closes what was open on it. From then on the desktop ends when the sandbox stops and is started again by itself when it runs again, with nothing open on it.

RequestTypeScript

import { Agental } from "agental-sdk";
const agental = new Agental();
const sandbox = await agental.sandboxes.get("sbx_2a9a47e50daec64a");
const desktop = await sandbox.desktop.on();

Answer200 OK · DesktopState

{
"enabled": boolean,
"enabledAt": string | null,
"running": boolean,
"width": integer | null,
"height": integer | null,
"display": string | null,
"url": string | null,
}

The desktop is on, and this is where to watch it.

Path

idrequired

string

e.g. "sbx_0123456789abcdef"

Headers

Authorizationrequired

Bearer key

An API key that may make this call.

Body

`width` integer	The width of the screen in pixels. e.g. `1280`
`height` integer	The height of the screen in pixels. e.g. `800`

Returns

200 The desktop is on, and this is where to watch it.

DesktopState7 fields

enabled

boolean

Whether a desktop is turned on for the sandbox.

It stays so through a stop and a start, and a move to another server: the desktop is started again by itself, with nothing open on it.

enabledAt

stringnull

Since when it is on.

Null when it is off.

running

boolean

Whether the desktop is running in the sandbox's machine now.

False while it is off, while the sandbox is not running, and in the moments after a start before it is up again.

width

integernull

The width of its screen in pixels.

Null while it is off.

height

integernull

The height of its screen in pixels.

Null while it is off.

display

stringnull

What DISPLAY is to be for a command that opens a window on the desktop, or takes a picture of it.

Null while it is off.

url

stringnull

Where the desktop is watched and used, in a browser.

It needs no token and is hard to guess, and whoever has it sees the screen and can click and type on it, so it is to be kept as a password is. It is another each time the desktop is turned on. Null while the desktop is not running, and where GET /v1/policy says publicUrls is false.

Errors and other answers

404	Not found.
409	sandbox_not_running, or
409	`desktop_unavailable` the sandbox's machine was made from an image that has no desktop, or the desktop did not start. The message says which. A sandbox made now has one.
501	`desktop_not_configured` sandboxes here have no desktop. GET /v1/policy says so as desktop.

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

← Get desktop Disable desktop →