Screens
Create screen
Start another screen on the same computer.
POST
Starts another screen on a computer that is already running. Use a second
screen when two agents need to work at the same time. X11 has a single pointer
per display, so two agents sharing one screen are two hands on one mouse.
A Linux computer supports at most four screens. Each one is an X server plus a
window manager plus whatever runs on it, so a computer runs out of memory
long before it runs out of screens.
Extra screens are a Linux feature. A macOS computer, an iPhone or an Android phone has exactly
one screen, so this endpoint answers
409 there. A Windows computer has no
screens endpoints, so it answers 404.Path parameters
Computer ID (UUID). The computer must be up. One that is still being created,
or that has been frozen, returns
400.Body parameters
Send an empty body to match the screen the computer booted with. That is almost always the size you want for a second screen.Response
Returns the new screen with201. Pass its id
as ?screen=<id> to target it from
screenshot,
click,
move mouse,
type,
key,
scroll,
drag and
bash. An action sent without the parameter
acts on the boot screen.
Orgo records the new screen before it answers, so a restart or start brings it
back with the same id, as described in
Screens after a restart.
A created screen gets a window manager and nothing else: no panel, no
wallpaper, no icons. That is deliberate. Each of those costs memory on every
screen, and an agent reads none of it. A screenshot of a fresh screen is an
empty root window, which is what a working screen looks like before anything
has been opened on it.
Errors
Failures raised before the request reaches the computer carryerror alone.
Failures relayed back from the computer add request_id and upstream_status.
Authorizations
Body
application/json
Size for a new screen. Send both dimensions or neither: if either is missing or zero, both fall back to the size of the boot screen and the value you did send is discarded without an error.
Response
Screen created