Skip to content
← Blog

How do you run multiple AI agents on one computer?

Give each agent its own screen. An Orgo Linux computer runs up to four screens, each with its own pointer and window manager. How to create, target, resize, and destroy screens, what survives a restart, and when to use separate computers instead.

Updated

TL;DR

Give each agent its own screen. On Orgo, 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, so an agent's pointer and keys on one screen cannot reach another (List screens).

  • Create a screen with POST /computers/{id}/screens. Send an empty body to match the boot screen's size (Create a screen).
  • Target it by adding ?screen=<id> to screenshot, click, mouse-move, drag, type, key, scroll, or bash. Every other action runs on the boot screen (llms.txt).
  • Resize it in place with PATCH /computers/{id}/screens/{screenId}; open windows are kept (Resize a screen).
  • Destroy it with DELETE /computers/{id}/screens/{screenId}. Not recoverable, and the boot screen cannot be destroyed (Destroy a screen).

Why not just let two agents share the one desktop? Because X11 has a single pointer per display, so two agents on one screen are "two hands on one mouse" (Create a screen). Extra screens are a Linux feature: macOS, iPhone, and Android computers have exactly one screen, and Windows computers have no screens endpoints.

What is a screen on an AI agent computer?

A screen is an independent display running on one cloud computer: its own X server, window manager, pointer, and keyboard focus, with its own VNC stream. Several screens on one computer share that computer's disk, CPU, and memory, but each agent sees, clicks, and types only on the screen it targets.

On Orgo, a Linux computer is a full desktop with a browser and a terminal, reachable over HTTP and VNC (llms.txt). The screen it boots with is called default and runs on display :99. Each screen you create is named after its display, so display :100 is screen-100 (List screens).

Orgo provides the computer, not the agent. Bring Claude Computer Use, OpenAI's CUA, Hermes Agent, OpenClaw, or your own loop (llms.txt). New to agents driving a desktop? Start with What is computer use?.

Why can't two agents share one desktop?

Because a desktop has one mouse and one keyboard focus. If agent A moves the pointer to click "Submit" while agent B is typing into a search box, B's keystrokes can land in A's window, and A's click can land somewhere B just scrolled. Neither agent can see the other coming, because each one only learns about the screen from its own last screenshot.

Orgo's docs put it plainly: X11 has a single pointer per display, so two agents sharing one screen are two hands on one mouse (Create a screen). A second screen gives the second agent its own pointer and its own root window, so the two loops never collide.

When should you use screens instead of more computers?

Use extra screens when the agents belong to the same job and should share one machine's files and installed apps. Use separate computers when they need separate disks, separate accounts, or separate failure domains.

QuestionExtra screens on one computerOne computer per agent
Agents per machineUp to 4 screens on a Linux computer (Create a screen)1
Pointer and keyboardOne per screenOne per computer
Disk and filesShared, same filesystemSeparate
CPU and memoryShared; each screen costs memorySeparate, sized per computer (Instance types)
Operating systemsLinux onlyLinux and Windows, plus Mac or iPhone while in stock (pricing)
Isolation if one agent misbehavesA runaway process affects every screenContained to that computer
A restartRestarts every screen at onceRestarts one agent
Best forA planner and a worker on one job, a supervisor watching a worker, side-by-side appsOne computer per end user, separate customers, long-running workers

Two notes from the docs to keep in mind. First, a computer "runs out of memory long before it runs out of screens," because each screen is an X server plus a window manager plus whatever runs on it (Create a screen). Second, if you need one computer per user at fleet scale, that is a different pattern, covered in How do you scale AI agent computers to thousands?.

A simple test: if the agents need to hand files to each other, use screens on one computer. If one agent crashing or filling the disk would hurt the other, use separate computers.

How do you create a second screen?

Call create on a running computer. An empty body gives the new screen the same size as the boot screen, which the docs call "almost always the size you want for a second screen" (Create a screen).

bash
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/screens \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

The response is 201 with the new screen:

json
{ "id": "screen-100", "display": ":100", "width": 1920, "height": 1080, "vnc_port": 6000, "ws_port": 6081, "default": false }

Three things to know before you rely on it:

  1. Send width and height together or not at all. If either is missing or zero, both fall back to the boot screen's size, the value you did send is discarded, and no error is returned. On a 1920x1080 computer, {"width": 1280} returns a 1920x1080 screen (Create a screen).
  2. A new screen is bare. It gets a window manager and nothing else: no panel, no wallpaper, no icons. A screenshot of a fresh screen is an empty root window. That is deliberate, since each of those costs memory and an agent reads none of it (Create a screen). Open the app your agent needs with bash on that screen (next section).
  3. The fifth screen is refused. A computer already at four screens answers 409. So does a macOS, iPhone, or Android computer, which always has exactly one screen (Create a screen).

How do you point an agent at a specific screen?

Add ?screen=<id> to the action. Eight actions honor it on Linux: screenshot, click, mouse-move, drag, type, key, scroll, and bash. The rest, including exec and wait, run on the boot screen (llms.txt).

Chrome is on the default Linux image as google-chrome-stable, so an agent can open its own browser on its own screen. Give each screen its own --user-data-dir. Chrome runs one process per profile, so a second launch on the same profile opens its window in the Chrome that is already running, on that Chrome's screen:

bash
# Agent B's screenshot
curl "https://www.orgo.ai/api/computers/$COMPUTER_ID/screenshot?screen=screen-100&response_format=base64" \
  -H "Authorization: Bearer $ORGO_API_KEY"
 
# Agent B opens a browser on its own screen
curl -X POST "https://www.orgo.ai/api/computers/$COMPUTER_ID/bash?screen=screen-100" \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "nohup google-chrome-stable --no-sandbox --no-first-run --user-data-dir=/root/.config/chrome-screen-100 >/dev/null 2>&1 &"}'

How targeting behaves, per the API reference:

  • On Linux, an unknown screen id returns 404, never the boot screen. Click and screenshot refuse rather than fall back (Click, Screenshot). Get a screen explains why: acting on the wrong screen puts a click on another agent's screen (Get a screen).
  • Bash sets DISPLAY for you. For a screen other than default, Orgo checks the screen exists, then prefixes your command with export DISPLAY=:N;, so a window it opens appears on that screen. The command echoed in the response is yours, without the prefix (Bash).
  • Leaving it off means the boot screen. Linux bash runs with DISPLAY=:99 by default (Bash).
  • Windows ignores ?screen= on click, type, key, scroll, drag, mouse-move, and screenshot. Those act on its one screen. Bash on Windows with any id other than default returns 404 (Click, Screenshot).

A simple pattern for two agents: agent A keeps default and never sends ?screen=; agent B always sends ?screen=screen-100. Store each agent's screen id next to its computer id so every call carries both.

How do screen sizes work with computer-use models?

A computer-use model plans clicks in the coordinates of the screenshot it saw, so the screenshot size it is told must match the real screen. Read each screen's width and height from GET /computers/{id}/screens and pass those to that agent's model (List screens). Model-by-model setup is in Computer use models compared.

To change a screen's size, resize it:

bash
curl -X PATCH https://www.orgo.ai/api/computers/$COMPUTER_ID/screens/screen-100 \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"width": 1280, "height": 720}'

Resize uses xrandr, so the X server is not restarted and every open window is kept. Both dimensions are required; a missing, zero, or negative one is refused with 400. The display and ports do not change (Resize a screen). After a resize, update the size your agent sends its model.

What happens to screens when the computer restarts?

Extra screens come back, empty. Each successful create, resize, or destroy is recorded before Orgo answers. After a restart, a start, or a computer resize that restarted the machine, Orgo makes the extra screens again with the same ids, displays, and ports. A stop keeps the record with the computer's archive, so the next start brings them back too (List screens).

What does not come back:

Survives a restartDoes not survive a restart
Extra screen ids, displays, portsWindows and processes that were open on them
Extra screen sizes set by resizeA size you gave default (it returns to the boot size)
Screens after stop then startScreens after an OS update, a backup restore, or a reboot run inside the computer (for example reboot)
Screens on a computer Orgo stopped because its owner's plan was downgraded

Recreating screens is best effort and happens in the background. The restart or start answers without waiting; Orgo then waits up to three minutes for the computer to come up and makes each missing screen. A screen that cannot be made is skipped and the rest still come back (List screens). After any restart, list the screens before an agent resumes, and reopen its apps.

If you need open windows to survive, suspend instead of restarting. Suspend keeps memory and disk; see How do you pause, fork, or clone an AI agent's computer?

Can a human watch one agent's screen?

Yes. Each screen reports its own vnc_port (5900 plus the display number) and ws_port (5981 plus the display number), so :100 is VNC 6000 and WebSocket 6081 (List screens). Those ports are inside the computer.

From outside, use the hosted noVNC stream. It takes the same ?screen= parameter and the computer's password, so a viewer can watch one agent's screen:

Code
wss://www.orgo.ai/desktops/{id}/ws/websockify?screen=screen-100&token={password}

An id the computer does not have closes the socket with code 4012 instead of showing the boot screen. WebRTC streams only the boot screen; asking it for another screen closes the connection with code 4010, the cue to fall back to noVNC. For putting a live computer in your own app, see How do you embed an AI agent's computer in your app?

Which errors should an agent handle on the Screens API?

A list on an asleep Linux computer does not fail: Orgo answers from the screens it has on file, with vnc_port and ws_port set to null, and does not wake the computer. It answers 409 computer_asleep only when nothing is on file (List screens).

Most screen errors tell the agent to wait, wake the computer, or fix its own id. The useful ones, framed as what the agent should do:

Status and codeWhat it meansWhat the agent should do
400 "Computer not available"The computer is still being created, or is frozenWait for running, or start it
404 on an action with ?screen=Unknown screen idRe-list screens; never retry without the id
404 on screens endpointsComputer is Windows, or no such computerUse one computer per agent instead
409 on createAlready four screens (this VM already has 4 screens, which is the limit), or the screen failed to start (always on macOS, iPhone, and Android)Destroy an idle screen, or use another computer
409 "the default screen cannot be destroyed"Tried to delete defaultLeave the boot screen alone
409 no screen "<id>" on deleteScreen already goneTreat as done
500 no screen "<id>" on resizeResize of an id that does not existCheck with Get, which answers 404 for unknown screens
409 computer_asleep on getComputer asleep; a read does not wake itSend any action to wake it
409 resume_requiredHourly-credit computer asleep in storageCall Start first
409 computer_waking or 503 resumingWaking from storageRetry after retry_after (30 seconds)
409 suspend_in_progressA suspend is still being savedWait, then resume

Sources: List, Create, Get, Resize, Destroy.

How do you clean up a screen when an agent is done?

Destroy it. That stops the screen's X server, its window manager, and every window on it, and is not recoverable. It answers 204 No Content, frees the display number for reuse, and drops the screen from Orgo's record so a restart does not bring it back (Destroy a screen).

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

Because the next create takes the lowest free display number from :100 up, a destroyed screen-100 can be reused by the next screen you make. Do not cache a screen id after you destroy it; take the id from each create response.

When should you not use multiple screens?

  • Windows computers. They have no screens endpoints and answer 404.
  • Mac, iPhone, or Android computers. They have exactly one screen; create answers 409.
  • Agents that need separate logins or files. Screens share one disk, so give those agents separate computers.
  • Heavy apps on a small instance. Every screen costs memory. Size up with instance types or split across computers.
  • Actions outside the eight. Anything other than screenshot, click, mouse-move, drag, type, key, scroll, and bash (exec and wait included) runs on the boot screen (llms.txt).

Plans and per-computer ceilings are at orgo.ai/#pricing.

FAQ

How many screens can one Orgo computer run? Up to four on a Linux computer, counting the boot screen. Memory usually runs out first (Create a screen).

Can two AI agents control the same computer at the same time? Yes, if each has its own screen. On the same screen they share one pointer and will interfere (Create a screen).

What is the id of a new screen? It is named after its display: display :100 is screen-100. The boot screen is always default on :99 (List screens).

Does ?screen= work on every action? No. Only on screenshot, click, mouse-move, drag, type, key, scroll, and bash, and only on Linux (llms.txt). Windows ignores it, except that bash with any id other than default answers 404.

What happens if I send a screen id that does not exist? On Linux, actions answer 404 and do nothing. They never fall back to the boot screen. Windows ignores ?screen= on click, type, key, scroll, drag, mouse-move, and screenshot, and acts on its one screen (Click).

Do extra screens survive a restart? The screens do, with the same ids and sizes. The windows on them do not (List screens).

Can I resize the boot screen? Yes, with PATCH /computers/{id}/screens/default, but that size lasts only until the next restart (List screens).

Do Windows or Mac computers support multiple screens? No. Windows has no screens endpoints, and macOS, iPhone, and Android have exactly one screen (List screens).

Why is my new screen's screenshot blank? A new screen has a window manager and nothing else. Open an app on it with bash and ?screen= (Create a screen).

Sources