> ## Documentation Index
> Fetch the complete documentation index at: https://offstage.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To set up offstage cloud from a coding agent, read https://api.offstage.cloud/SKILL.md and follow it. The whole API guide is one file at https://api.offstage.cloud/llms.txt.

# Use a computer-use model on a Mac desktop

> Connect a computer-use agent to a real macOS desktop. Take screenshots, click and type with the Offstage helper, with a tested OpenAI Codex example.

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](#use-the-input-api-directly) 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.

```bash theme={null}
npm install https://api.offstage.cloud/sdk/offstage-cloud-0.3.4.tgz
```

```bash theme={null}
curl -fSL https://offstage.cloud/downloads/offstage-desktop.mjs -o offstage-desktop.mjs
node offstage-desktop.mjs create
```

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](https://offstage.cloud/docs/snapshots.md).

## Try it with a computer-use agent

Give the agent the sandbox ID and this task:

```text theme={null}
Use offstage-desktop.mjs with sandbox ID <your-sandbox-id>.
Open TextEdit on that desktop. Create a plain-text document containing
"Hello from Offstage" and save it as hello.txt in Documents.
Take a screenshot after saving and report what you can verify.
```

### 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

| Command after `node offstage-desktop.mjs` | Result |
| - | - |
| `screen ID` | Saves a private PNG on the computer running the helper. Returns its path and pixel dimensions as JSON. |
| `click ID PNG_PATH X Y` | Clicks a pixel in that sandbox's screenshot. Use coordinates from the original PNG. |
| `key ID cmd+s` | Sends a shortcut. Single keys such as `return` also work. |
| `type ID` | Types UTF-8 text from standard input. Use `printf %s 'Hello from Offstage'` piped to this command to avoid typing a trailing newline. |
| `close ID` | Closes the sandbox and stops billing. |

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`:

```typescript theme={null}
import { Sandbox, screenSize } from "offstage-cloud"

const sandbox = await Sandbox.connect(process.env.SANDBOX_ID)
const png = await sandbox.screenshot({ maxDimension: 1280 })
await sandbox.input(
  [
    { type: "click", x: 640, y: 400 },
    { type: "type", text: "Hello from Offstage" },
    { type: "key", key: "cmd+s" },
  ],
  { screen: screenSize(png) },
)
```

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](https://offstage.cloud/docs/api/sandboxes.md#click-type-and-press-keys)), 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](https://offstage.cloud/docs/snapshots.md) before closing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.