Computers

For developers who connect a client to OpenBot or extend its server. The examples need the access stated on this page. Start with the developer manual.

A Computer is a machine where a Bot works. The Bot runs shell commands, reads and writes files, opens ports and uses a desktop there. A Computer is one of two kinds:

• A sandbox at a Computer provider, such as E2B or Daytona. You bring your own account at the provider. The provider bills you directly.
• Your own machine, such as a laptop or a server. You pair it with OpenBot once. Then a small program on it keeps a connection to OpenBot.

A Computer belongs to a member or to the organization, like a trigger. Bots never own a Computer. A Bot gets the right to use a Computer. Many Bots can use the same Computer.

---

Add a Computer provider

See Computer providers.

Create and use a Computer

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"commandKey":"create-build-box-1","name":"Build box","source":{"_tag":"Provider","provider":"cpp_...","template":null},"desktop":true}' \
  https://api.example.com/v1/computers

Field	What it does
source	{"_tag":"Provider","provider":"<id>","template":null} for a sandbox. A template picks an image of the provider.
desktop	Optional. true asks for a desktop, for screenshots, the mouse and the keyboard.
pauseAfter	Optional. Seconds without work before OpenBot pauses the Computer. The default is 600. null never pauses it.
shared	Optional. true makes a shared Computer of the organization.

Create, pause, resume and delete are saved commands. Each HTTP request needs a commandKey and returns 202 with an execution receipt. Send the same key and body after a lost HTTP reply. The SDK helpers Computers.create, pause, resume and remove keep this key across retries.

Use GET /v1/executions/:executionId for the saved state. Use GET /v1/executions/:executionId/observe?afterSequence=0 for events, and keep the last sequence when you reconnect. The execution resource gives the Computer ID. An active Computer also gives its executionId. Closing the event stream does not stop the command. Use the execution cancel route for that.

For pause, resume and delete, send a JSON body such as {"commandKey":"pause-build-box-1"}. Only one lifecycle command may run for a Computer. A conflicting command returns ComputerConflict with that execution ID. Work on the Computer waits for an explicit resume to finish. The server checks current rights again before each provider action.

A Computer has a state: starting, running, paused, offline (your machine is not connected) or failed.

Route	What it does
POST /v1/computers/:computerId/sessions	Starts a shell command. See Commands.
GET, PUT, DELETE /v1/computers/:computerId/files	Reads, writes and removes a file. utf8 for text, base64 for other bytes.
GET /v1/computers/:computerId/directory?path=	Lists a directory.
PUT /v1/computers/:computerId/ports/:port	Gives a port a public HTTPS address. Anyone with the address can use it.
POST /v1/computers/:computerId/desktop/screenshot	Takes a screenshot.
POST /v1/computers/:computerId/desktop/actions	Clicks, types, presses keys and scrolls, then takes a screenshot.
POST /v1/computers/:computerId/desktop/stream	Gives an address where a person can watch and use the desktop.
POST /v1/computers/:computerId/pause, /resume	Pauses or resumes the Computer.

A paired machine gives no desktop stream, so desktop/stream fails there with ComputerUnsupported. A command on a paused Computer first submits a saved resume. Provider adapters never resume or repeat a command by themselves. DELETE /v1/computers/:computerId deletes the Computer and its sandbox. Its files are gone. If preparation fails before a delete is sent, the execution fails and the Computer stays. A new command can try again later.

A lost reply after a provider action leaves outcome_unknown. Read its saved DecisionNeeded event and send a decision through the execution API. A retry needs a check of the provider result first. A stop leaves the Computer in failed; it is not proof that the sandbox stopped. Late create replies keep the sandbox reference and its use record. OpenBot never reports a lost reply as successful deletion.

Commands

A command runs with bash -lc in a session. OpenBot waits up to yieldTimeMs for it (10 seconds by default, from 0.25 to 30 seconds). Then it gives the output so far:

{
  "session": "cse_…",
  "running": true,
  "exitCode": null,
  "signal": null,
  "output": ">>> ",
  "truncated": false
}

When the command has ended, session is null and exitCode or signal says how it ended. While it runs, use the session for more:

Route	What it does
POST /v1/computers/:computerId/sessions	Starts a command: command, cwd, env, tty, rows, cols.
POST /v1/computers/:computerId/sessions/:sessionId/input	Sends chars to stdin and gives the new output. Empty chars only reads.
POST /v1/computers/:computerId/sessions/:sessionId/resize	Gives the terminal a new size.
DELETE /v1/computers/:computerId/sessions/:sessionId	Stops the command and gives its last output.

chars takes C escapes: \n is Enter, \x03 is Ctrl-C, and \x04 is Ctrl-D, the end of the input. With tty, the command gets a terminal (a PTY), for programs such as python3, ssh or top. Then stdout and stderr come together. Each answer gives at most maxOutputBytes of new output (64 KiB by default). With more, only its end comes, and truncated is true.

A session belongs to the one who started it. It ends after 30 minutes with no use. A Daytona Computer gives no terminal, so tty fails there.

---

Pair your own machine

See Pair a machine.

Bots and the right to use a Computer

Give your Bot the right to use a Computer:

curl -X PUT -H "Authorization: Bearer $OPENBOT_TOKEN" \
  https://api.example.com/v1/computers/cmp_.../bots/bot_...

You must be able to use the Computer and to change the Bot. GET /v1/computers/:computerId/bots lists the Bots with the right. DELETE /v1/computers/:computerId/bots/:botId takes the right away. The right also ends when the Bot is archived. The Computer stays.

A Bot has tools for Computers. It lists them with openbot_computers_list. Then it can:

• Ask for the right to use a Computer that exists, with openbot_computers_acquire. A child Bot can ask for a Computer of the Bot that gave it work.
• Make a new sandbox with openbot_computers_create. The Computer belongs to its person, and the Bot gets the right to use it. The tool takes name, source, desktop and pauseAfter in the same form as POST /v1/computers, and a reason. The source must be a provider.
• Give up its right with openbot_computers_release. With destroy, it also deletes the Computer.
• Run commands with openbot_computer_exec, and send input to them with openbot_computer_write_stdin, in the same way as Commands. When a command still runs after its yield time, the Chat gets a notice of kind computer_session when it ends.
• Change files, open ports and use the desktop. A screenshot comes back as an image that the model sees.

These four actions are capabilities. The chain of deciders decides them, as for any other capability:

Action	Target	When a Bot uses it
computers.acquire	The ID of the Computer	It asks for the right to use a Computer.
computers.create	The ID of the provider	It makes a new sandbox.
computers.delete	The ID of the Computer	It deletes a Computer with its files.
computers.expose	The ID of the Computer	It gives a port a public address.

When OpenBot cannot check one of these actions, the action does not run, and the tool tells the Bot why. For example, the person of the Bot may not see the Computer, or OpenBot cannot read its data.

All other work on a Computer needs no decision. The Computer is the boundary: a Bot with the right can do anything inside it.

---

Pause and usage

OpenBot pauses a sandbox when it had no work for pauseAfter seconds. A command that still runs counts as work. E2B keeps its files, memory and running programs. Daytona keeps its files and starts it again from them. Your own machines never pause.

GET /v1/computers/:computerId/usage lists the times when a Computer ran. The provider bills you for them. OpenBot only records them. It does not set a price, and budgets do not stop a Computer.

Execution and recovery

A command session is bound to its Computer and Chat. The openbot_computer_write_stdin tool takes both computer and session. Each call checks current use rights, including every token that limits the task. Removing access stops further input and output reads through OpenBot. When a Bot has no grant to use a Computer, its tool returns the safe category forbidden and an error ID. The command does not reach the provider.

OpenBot routes command sessions to the node that owns the process. That node checks current rights again before it sends input. Calls for one session run in order. A normal close keeps its last reply. A lost reply can leave a write with an unknown result; OpenBot does not send that write again. The HTTP error ComputerExecutionFailed gives a safe error category and an error ID.

Computer and provider lists use all current caller limits before reading rows. The same lists supply tool replies and Bot prompts. A grant to a Bot does not remove the limits of a token.

Paired machines use the same private, authenticated route as command sessions. File and desktop calls run on the node with the physical connection. A new connection takes the place of the old one. The old connection cannot change the new connection’s state. Output is sent in order with a bounded buffer. A broken stream or lost write result is reported as unknown and is never replayed.

Idle checks use one saved schedule shared by all nodes. Each idle pause has its own execution. Restarting a node does not reset another node’s work. An unknown idle pause accepts only stop from a member with current write rights. Check the provider before a new command. Unknown pause results do not close a use record as though the sandbox had stopped.