Skip to main content
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 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.

​
Path parameters

​
string
required
Computer ID (UUID). The computer must be up. One that is still being created, or that has been frozen, returns 400.

​
Body parameters

​
integer
Width in pixels. Send width and height together or send neither.
​
integer
Height in pixels. Send width and height together or send neither.
If either dimension is missing or zero, both fall back to the size of the boot screen. The value you did send is discarded and no error is returned. On a 1920×1080 computer, {"width": 1280} returns a 1920×1080 screen, not a 1280×1080 one.
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 with 201. Pass its id as ?screen=<id> to target it from screenshot, click, type, key, scroll and drag. An action sent without the parameter acts on the boot screen.
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 carry error alone. Failures relayed back from the computer add request_id and upstream_status.

Authorizations

​
Authorization
string
header
required

API key authentication. Get your key at orgo.ai/workspaces

Path Parameters

​
id
string
required

Computer ID

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.

​
width
integer

Width in pixels. Omitted, the screen matches the boot screen.

Example:

1920

​
height
integer

Height in pixels. Omitted, the screen matches the boot screen.

Example:

1080

Response

Screen created

​
id
string

Screen identifier. The boot screen is always default.

Example:

"screen-1"

​
display
string

X display this screen runs on.

Example:

":100"

​
width
integer

Width in pixels.

Example:

1920

​
height
integer

Height in pixels.

Example:

1080

​
vnc_port
integer

VNC port for this screen.

Example:

6000

​
ws_port
integer

WebSocket port for this screen.

Example:

6081

​
default
boolean

True for the screen the computer boots with. It cannot be destroyed.

Example:

false