Skip to main content
Give your agent a Mac desktop it can see and control. The agent inspects a screenshot, chooses where to click or what to type, and checks the result in the next screenshot. Its actions land inside the Offstage GUI sandbox. The helper runs wherever your agent runs. If you’re building your own agent, expose the commands below as tools and pass the PNG back to your model as an image, or call the input API from your own code. An agent that can already run shell commands and view images, such as OpenAI Codex, can use the helper directly.

Connect a desktop

Set OFFSTAGE_API_KEY in the environment that runs the helper. Install the SDK and download the helper in the same directory.
The last command waits for the desktop and prints its sandbox ID. You can also use the ID of a ready GUI sandbox you already own, including one restored from a snapshot.

Try it with a computer-use agent

Give the agent the sandbox ID and this task:

Tested with OpenAI Codex

In a fresh Codex session, we opened a TextEdit document containing a random code. Codex read the code from a screenshot, clicked into the document, replaced its contents and pressed Command-S. We then read the saved file through the SDK and verified its contents byte for byte.

Desktop commands

Take a screenshot before choosing coordinates and after each action whose result matters. A successful input command means the desktop accepted the event. Inspect the screen or read the saved file to verify what the app did. Screenshots stay in the reported temporary directory on your computer.

Use the input API directly

The helper is a thin wrapper over the SDK. Take a screenshot, read coordinates from it, and send input in its pixels with its size as screen:
The actions are move, click (with button, count and modifiers), drag, scroll, type, key and wait, performed in order. Over HTTP it is POST /v1/sandboxes/:id/input (reference), and Claude Code’s offstage plugin offers it as offstage_sandbox_input. GUI sandboxes record by default. For work that needs recording off, create the GUI sandbox with the SDK’s record: false option and give the helper its ID. Close the sandbox when finished. If you need the files again, capture a snapshot before closing.