Orgo - Cloud computers for AI agents

A Linux computer boots with one screen and can run up to four. Each screen is its own X server, with its own root window, its own cursor, and its own window manager. An agent working on one screen cannot disturb another.

Extra screens are a Linux feature. A macOS computer or an iPhone has exactly one screen, and this endpoint lists it as default with a display that is not an X display. A Windows computer has no screens endpoints, so it answers 404.

Screens after a restart

Extra screens come back after a restart. Each time a create, resize, or destroy succeeds, Orgo records the computer’s extra screens, with their ids and sizes, before it answers. After a restart, a start, or a resize that restarted the computer (restarted: true), Orgo makes them again with the same ids, so the same displays and ports. A stop keeps the record with the computer’s archive, so the start that follows brings them back too. A screen comes back empty. A restart ends every process, so the windows that were open on it are gone. The recreated screen has a window manager and nothing else, like a newly created one. Recreating screens is best effort:

It happens in the background. The restart or start answers without waiting for it. Orgo then waits up to three minutes for the computer to come up, and makes each screen it is missing. List the screens to see which are back.
A screen that cannot be made again is skipped, and the rest still come back.
If the computer stops running before it comes up, nothing is made.

Screens are not made again after an OS update, after a backup restore, or after a reboot that did not go through Orgo, such as reboot run on the computer itself. A computer that Orgo stops because its owner’s plan was downgraded does not keep them either. The boot screen is never recorded, so a size you give default with resize lasts only until the next restart, when it is back at the size the computer boots with.

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.

Response

array

Every screen on the computer, the boot screen first and the rest in display order. Never empty while the computer is up.

Show Screen

string

Screen identifier. The boot screen is always default. A screen you create is named after its display, so :100 is screen-100. Pass this value as ?screen=<id> on an action to target the screen.

string

X display. The boot screen is :99. Each created screen takes the lowest free display number from :100 up, so a number freed by a destroyed screen is reused.

integer

Width in pixels.

integer

Height in pixels.

integer

VNC port. Derived from the display rather than looked up: 5900 plus the display number, so :99 is 5999 and :100 is 6000.

integer

WebSocket port bridging that VNC stream: 5981 plus the display number, so :99 is 6080 and :100 is 6081.

boolean

true for the screen the computer booted with. It cannot be destroyed.

Errors

Failures raised before the request reaches the computer carry error alone. Failures relayed back from the computer add request_id and upstream_status.

Status	When	Body
`400`	The computer has nothing running behind it: still being created, or frozen.	`{ "error": "Computer not available" }`
`401`	The Bearer token starts with `sk_` but is not a known Orgo key.	`{ "error": "Invalid API key" }`
`401`	No `Authorization` header, or a Bearer token that is not an `sk_` key.	`{ "error": "Authentication required" }`
`401`	You do not own the computer’s workspace and are not a member of it.	`{ "error": "You do not have access to this workspace." }`
`401`	The API key is scoped to a different workspace.	`{ "error": "This API key cannot access this workspace (workspace_scope_mismatch)." }`
`401`	Orgo could not verify the credential because of a server-side fault. Retry.	`{ "error": "Service temporarily unavailable. …" }`
`402`	The computer is a free trial computer that can no longer run.	`{ "error": "Choose a plan to continue." }`
`402`	The computer is paid for by its own subscription or dedicated purchase, and that payment has lapsed.	`{ "error": "Manage this computer’s payment in Account → Usage." }`
`404`	No computer with that ID.	`{ "error": "Desktop not found" }`
`404`	The computer runs Windows, whose agent has no screens endpoint.	`{ "error": "…", "request_id": "…", "upstream_status": 404 }`
`500`	Unexpected failure.	`{ "error": "…", "request_id": "…" }`
`501`	A macOS computer or an iPhone whose agent cannot list screens, when Orgo has no screen size on file for it.	`{ "error": "…", "code": "SCREENS_UNSUPPORTED_OS" }`
`503`	The computer could not be reached.	`{ "error": "Could not reach the desktop. Try again in a moment.", "request_id": "…", "code": "ECONNREFUSED" }`

curl https://www.orgo.ai/api/computers/$COMPUTER_ID/screens \
  -H "Authorization: Bearer $ORGO_API_KEY"

{
  "screens": [
    { "id": "default",    "display": ":99",  "width": 1920, "height": 1080, "vnc_port": 5999, "ws_port": 6080, "default": true },
    { "id": "screen-100", "display": ":100", "width": 1920, "height": 1080, "vnc_port": 6000, "ws_port": 6081, "default": false }
  ]
}

Authorizations

Authorization

string

header

required

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

Path Parameters

string

required

Computer ID

Response

The computer's screens

screens

object[]

Show child attributes

Overview

Account

Clients

Computer Use API

Workspaces

Computers

Computer Lifecycle

Computer Actions

Screens

Files

Templates

List screens

Screens after a restart

Path parameters

Response

Errors

Authorizations

Path Parameters

Response

​Screens after a restart

​Path parameters

​Response

​Errors

Authorizations

Path Parameters

Response

Screens after a restart

Path parameters

Response

Errors