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

# Sandboxes

> A whole macOS user account that you drive one call at a time.

Every call takes `{ apiKey?, baseUrl? }`, which default to `OFFSTAGE_API_KEY` and `https://api.offstage.cloud`.

| Call | What it does |
| - | - |
| `Sandbox.create({ session?, timeoutMs?, idleTimeoutMs? })` | Makes a sandbox. `session` is `"headless"` (the default) or `"gui"`. It lives 15 minutes by default and never more than 24 hours; it closes after 10 idle minutes by default |
| `sandbox.commands.run(cmd, { cwd?, envs?, timeoutMs? })` | Runs a command in `zsh -lc` and returns `stdout`, `stderr`, `exitCode` and `durationMs`. Long commands are followed for you, up to 30 minutes |
| `sandbox.files.write(path, data)` | Writes up to 2 GiB, replacing any file there. Paths are relative to the sandbox |
| `sandbox.files.read(path)` | Reads up to 2 GiB back, as text or byte-exact with `{ format: "bytes" }` |
| `sandbox.screenshot({ maxDimension? })` | A PNG of the screen, in gui sandboxes |
| `sandbox.runAgent({ goal, maxSteps?, maxDurationMs? })` | Hands a gui sandbox's screen a goal, which Claude carries out on the Mac with your Anthropic API key. Returns the verdict, every step and its screenshots |
| `sandbox.replayUrl`, `sandbox.recording()` | A gui sandbox is recorded: its screen, commands and agent steps. `replayUrl` is the console page that shows it live and plays it back after it closes, for 7 days. Create it with `record: false` to keep none |
| `sandbox.createSnapshot({ name? })` | Saves supported home files for another run. See [Snapshots](https://offstage.cloud/docs/snapshots.md) for capture and restore |
| `sandbox.setTimeout(ms)` | Keeps it alive `ms` from now, within 24 hours of creation |
| `sandbox.kill()` | Closes it and stops the clock |
| `Sandbox.connect(id)`, `Sandbox.list()` | Picks up a sandbox by id, or lists your team's |

> [!TIP]
>
> **Keep one sandbox while you iterate.** Each sandbox is a fresh macOS account with cold build caches. Send every edit, build and test to the same one rather than starting over for each step, and kill it when the work is done.

## Headless or gui

Use `headless` for command-line work, or `gui` for apps, screenshots and computer-use agents. A `gui` sandbox can take a goal and have Claude carry it out on its screen ([hand the screen a goal](https://offstage.cloud/docs/api/sandboxes.md#hand-the-screen-a-goal)), or let [your own computer-use agent](https://offstage.cloud/docs/computer-use.md) inspect screenshots, click and type on the Mac. In the console, choose **Desktop** when creating a sandbox.

A headless sandbox can take work as soon as a Mac boots. A gui sandbox runs in the account's logged-in desktop session, for screenshots and apps with windows, and can wait for a slot.

To drive a UI, take a screenshot and send clicks, keys and text in its pixels with `sandbox.input` ([click, type and press keys](https://offstage.cloud/docs/api/sandboxes.md#click-type-and-press-keys)). Or hand the sandbox a goal with `runAgent`: a harness inside the slot carries it out with your Anthropic API key. Or drive it with a program that runs on the Mac. That program holds no screen or input permission of its own; it asks the slot's session daemon for screenshots and input, over the socket named in `OFFSTAGE_SESSION_SOCKET`. Scripts that send Apple Events, such as `osascript` driving System Events, wait about 90 s on a permission prompt nobody can answer and fail with error -1743; use the input API instead.

Web content shows as a white page in a gui sandbox. The sandbox's desktop session is not the one on the Mac's display, so macOS reports every window in it as hidden, and WebKit stops painting a web view whose window is hidden. Safari and apps built on a default `WKWebView` show a blank page, even though the page loads and its scripts run. Native AppKit and SwiftUI windows draw normally. Playwright's WebKit turns that check off, so use it for web pages; Chromium has not been measured here. In an app you build and test, set the web view's private `_windowOcclusionDetectionEnabled` property to `NO` in the test build, as Playwright's WebKit does.

A keychain item a command adds can still prompt. A gui sandbox's default keychain is `offstage-session.keychain-db`, and the sandbox is not given its password. An item made with `security add-generic-password`, even with `-A`, carries only the `apple-tool:` partition, so a signed app that reads it gets a prompt for that keychain's password, which nobody can answer. Let the app create its own item, or pass the secret to the app another way in tests. Or put the item in a keychain of your own with a known password and add your app's team to its partition list. This recipe is untested:

```sh theme={null}
security create-keychain -p test-pass test.keychain
security set-keychain-settings test.keychain
security unlock-keychain -p test-pass test.keychain
# Keep offstage-session first in the search list.
security list-keychains -d user -s offstage-session.keychain-db test.keychain-db
security add-generic-password -s SERVICE -a ACCOUNT -w SECRET -A test.keychain
security set-generic-password-partition-list -S apple-tool:,apple:,teamid:TEAMID -s SERVICE -k test-pass test.keychain
```

Every field, state and error is in the [Sandboxes API reference](https://offstage.cloud/docs/api/sandboxes.md).


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