ComputerToolset runs the computer tool loop on the Responses API, and you supply a driver that executes each action the model asks for. E2B Desktop is that driver’s target: a private Ubuntu desktop in the cloud, isolated from your machine, that you can watch live while the model clicks and types.
OpenAI documents two ways to connect a model to a screen, and both run on E2B Desktop:
- Code execution, which OpenAI recommends for
gpt-6-astra: the model writes PyAutoGUI or Playwright code, and the desktop runs it. See Use code execution. - The computer tool: the model returns structured clicks and keystrokes, and your driver performs them. See Run an agent on a desktop.
How it works
- Create a desktop.
Sandbox.create()from E2B Desktop starts an XFCE desktop with LibreOffice, a file manager and other common apps. - Write a driver. One method per computer action (
click,type,scroll, and so on) plusscreenshot, each mapped to an E2B Desktop call. - Run the toolset.
ComputerToolset(driver).run(client, params)calls the Responses API, dispatches every action to your driver, sends back a screenshot, and repeats until the model answers. - Kill the desktop. The helper never creates or closes the environment. You own it.
Install
The helpers needopenai 3.31.0 or newer in Python and 7.33.0 or newer in Node.
E2B_API_KEY (get one) and OPENAI_API_KEY in your environment. Your OpenAI project needs access to a model that supports the computer tool.
Run an agent on a desktop
This script seeds two order notes on a fresh desktop, opens their folder, and asks the model for the order number of the priority one. It prints a live view URL first, so you can watch the run.python agent.py, or npx tsx agent.ts in an ES module project. A run takes a few model turns and ends with Answer: PO-7731.
For a full run, see the Excel to OrangeHRM example in the E2B cookbook, in Python and TypeScript: gpt-6-luna reads new hires from a spreadsheet in LibreOffice Calc, enters each one into the OrangeHRM web app in Chrome, and writes the assigned Employee Ids back into the spreadsheet. It is the same task as the Claude toolsets example, driven by the computer tool alone.
The driver covers every action the computer tool can send. It refuses what E2B Desktop has no direct call for, such as clicks with held modifier keys and horizontal scrolling: a driver must raise instead of silently skipping an action, and the helper stops the run.
The examples use
gpt-6-luna. In our runs of multi-step LibreOffice Calc and web app tasks on E2B Desktop, it finished about twice as fast as Claude Haiku 5.5 at about a tenth of the cost, mostly because OpenAI caches the repeated screenshot history automatically.Use code execution
With code execution, the model gets one function tool instead of the computer tool:exec_py for Python with PyAutoGUI, or exec_js for JavaScript with Playwright. One call can batch several actions, read text from the screen or the page, and check its own result before the model looks again. Your application runs the code and returns its text and screenshots.
E2B Desktop is where that code runs. It executes inside the sandbox, never on your machine, and the desktop stays up between calls, so windows, variables and logins carry over. The E2B side has three parts:
- A template with the library. Build it once per E2B team on top of the stock
desktoptemplate:
- A persistent runtime inside the desktop. A small process you start in the background keeps one Python namespace (or one Playwright context connected to the desktop’s Chrome) for the whole run. It gives the code
logorconsole.logfor text anddisplayfor screenshots, and answers each call with theinput_textandinput_imageitems the Responses API takes as afunction_call_output. Write each call to a file in the sandbox, and have the runtime run that file whencurlposts to its Unix socket throughcommands.run, so nothing listens outside the sandbox. - OpenAI’s loop. The
exec_pyorexec_jstool definition and the Responses loop from OpenAI’s guide, with eachfunction_callsent to the runtime and its output returned unchanged.
gpt-6-astra opens the file in the file manager with PyAutoGUI. In TypeScript, it opens the same folder in Chrome with Playwright. Each run took Astra two calls. The runtimes are adapted from OpenAI’s CUA sample app, which runs the generated code on your own computer; on E2B it runs in a throwaway desktop with no internet access.
PyAutoGUI drives the whole desktop by screen coordinates, so it works with any app. Playwright drives only the browser, but it can read page text and click elements by role, so it needs fewer screenshots.
Watch live
stream.start() serves the desktop over noVNC. With require_auth=True (requireAuth: true) the URL carries a generated password, and view_only keeps viewers from moving the mouse under the model. Anyone with the URL can watch until the desktop is killed, so do not share it.
Approve actions
before_action (beforeAction) runs before every action, including the final screenshot, and must return exactly True to let it through. The example approves everything and logs the action type; this is where an application checks or asks a person before consequential clicks and keystrokes.
Calls that carry pending safety checks stop the run unless you also pass approve_safety_checks (approveSafetyChecks) and return True.
Sandbox ownership
- Cleanup: the helper never kills the desktop. Call
kill()infinallyso a failed or cancelled run does not leave it running until its timeout. - Timeout:
timeout=300(timeoutMs: 300_000) is a backstop. Keep it longer than a run ofmax_stepsmodel turns can take. - Cancellation: pass
cancelled(Python) orsignal(Node) to stop between model calls and actions. - Egress: the desktop has internet access by default. Restrict it with
allow_internet_accessornetwork.allow_outwhen the task does not need the open web.
Related guides
Excel to OrangeHRM
gpt-6-luna copies new hires from a spreadsheet into an HR system on one desktopComputer use
How computer use agents drive E2B Desktop sandboxes
Desktop template
What the desktop sandbox ships with and how to customize it