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

> Hold a Mac and drive it one call at a time: commands, files, screenshots and goals.

A sandbox is one Mac slot (a macOS user account) held for you. Files persist between calls. When it closes, the Mac wipes the whole account before anyone else gets it (see the isolation notes under [Paths](https://offstage.cloud/docs/api/sandboxes.md#paths)). It bills per second from the moment a slot takes it (`ready`) until it closes. A `pending` sandbox costs nothing.

**Keep one sandbox while you iterate.** Each sandbox is a fresh macOS account: an empty home folder, nothing installed beyond [What is on the Mac](https://offstage.cloud/docs/api/sandboxes.md#what-is-on-the-mac), cold build caches. Whatever you clone, install or build in it is gone when it closes. So keep one sandbox open while you edit, build and test, and send every step to it, rather than creating a new one per step and cloning and building from scratch each time. It closes after `idleTimeoutMs` with no op (10 min by default; at creation you can set it up to `timeoutMs`) and at `expiresAt`. [Set the timeout](https://offstage.cloud/docs/api/sandboxes.md#set-the-timeout) keeps it open longer, up to 24 hours from creation. Kill it when the work is done.

### Create a sandbox

`POST /v1/sandboxes`

| Field | Type | |
| - | - | - |
| `session` | `headless` \| `gui` | `headless` by default. See [Sessions](https://offstage.cloud/docs/api/sandboxes.md#sessions-headless-and-gui) |
| `timeoutMs` | integer | How long it may live. 15 min by default, 24 h at most. It closes at `expiresAt` (`createdAt + timeoutMs`) whatever it is doing. [Set the timeout](https://offstage.cloud/docs/api/sandboxes.md#set-the-timeout) moves that |
| `idleTimeoutMs` | integer | The sandbox closes after this long with no op. 10 min by default, and never more than `timeoutMs` |
| `name` | string | What people call it: 1 to 48 lowercase letters, digits and inner hyphens, like `ios-build`. Left out, the plane picks an adjective-noun name like `swift-otter`. An open sandbox of the team already called that is 409 `name-taken` |
| `secrets` | string\[] | Select 1–16 existing team secret names. See [Team secrets and signing](https://offstage.cloud/docs/api/secrets.md) |
| `record` | boolean | A `gui` sandbox is recorded unless this is `false`: its screen, commands and agent runs, played back at its `replayUrl`. See [Recordings](https://offstage.cloud/docs/api/recordings.md) |

```bash theme={null}
curl -s -X POST https://api.offstage.cloud/v1/sandboxes -H "authorization: Bearer $OFFSTAGE_API_KEY" \
  -H 'content-type: application/json' -H "idempotency-key: $(uuidgen)" -d '{"timeoutMs": 1800000}'
```

The answer is `201` with the sandbox, `pending` until a slot takes it and then `ready`. With the SDK, call `await sandbox.ready({ timeoutMs: 15 * 60_000, signal })` inside a `try/finally` that kills the sandbox. This waits for desktop capacity without using the shorter command retry window. Aborting the wait does not delete the sandbox. With REST, poll `GET /v1/sandboxes/:id` until `ready` or `closed`. Polling an unclaimed pending sandbox renews its idle lease; abandoning it allows `idleTimeoutMs` to close it, and the 15-minute queue cap still applies. An empty body is allowed and gives a default sandbox. Refusals: 400 (validation, including `not-an-object` for a body that is not valid JSON, and `bad-name`), 402 (billing), 409 `no-capacity` (Macs are online but no slot takes this `session`) or `name-taken`.

### The sandbox object

```json theme={null}
{
  "id": "sbx_…",
  "name": "swift-otter",
  "session": "headless",
  "state": "ready",
  "createdAt": 1793000000000,
  "expiresAt": 1793001800000,
  "timeoutMs": 1800000,
  "idleTimeoutMs": 600000,
  "lastActivityAt": 1793000040000,
  "boxId": "box_…", "slot": 3,
  "readyAt": 1793000000100,
  "ops": 12,
  "runtimeSeconds": 40,
  "costUsd": 0.002733,
  "createdBy": { "keyName": "ci" }
}
```

The `name` is for people; every route takes the `id`. A `gui` sandbox also has `record` and, when that is true, `replayUrl`, the console page that shows it live and plays it back after it closes (see [Recordings](https://offstage.cloud/docs/api/recordings.md)). A closed sandbox adds `closedAt` and `closeReason`. The reasons are:

* `deleted`: you killed it.
* `expired`: it reached `createdAt + timeoutMs`. An op sent after that closes it there and then, and is refused with 409 `sandbox-closed`.
* `idle`: it went `idleTimeoutMs` with no op.
* `box-lost`: its Mac stopped answering for 2 minutes, mid-command or not. A command still running then fails with 409 `sandbox-closed`. It is billed only up to the Mac's last answer, and its `costUsd` and `runtimeSeconds` stop there too.
* `plane-restart`: the service restarted while it was open and its Mac did not come back with it. This is rare: a restart keeps open sandboxes `ready`, and only an op in flight at that moment is lost (its request fails with a dropped connection or a 502; run it again). A sandbox that closes this way is billed only up to its Mac's last contact, never for the outage. Create a new one.
* `no-capacity`: no slot took it within 15 minutes of creation, or before its `timeoutMs` ran out if that came first. It cost nothing.
* `secret-unavailable`: a selected secret was deleted or could not be read before assignment. It never ran.

### Capture and restore a home snapshot

Call POST /v1/sandboxes/:id/snapshots on a ready sandbox with an optional name and an Idempotency-Key. A 201 response includes the snapshot. A 202 response contains snapshotId to poll with GET /v1/snapshots/:id. GET /v1/snapshots lists your team's captures. DELETE /v1/snapshots/:id removes one.

Create a sandbox with \{"snapshotId":"\<id or committed name>"} and wait for it to become ready. The saved session type and macOS major must match. The source sandbox can be closed after local capture. A local capture can be lost before upload finishes. The durableAt timestamp means the remote copy has been verified. A replacement takes over its name after verification.

Capture saves supported home files, including the working directory. Flush open files before capture. Apps restart when launched in the new sandbox. GUI snapshots carry the sandbox’s standalone default keychain, including supported Chrome secrets. The native login keychain starts fresh. Headless snapshots exclude keychains. Offstage-managed secrets, Safari data, app containers and device-bound keys are excluded. Credentials written to ordinary files can be included. Restore relocates recognized Python virtual environment paths. Each team can retain 10 snapshots totaling 20 GB, with a 5 GB limit per snapshot before compression. Snapshots expire after 30 days without a successful restore, following a warning.

### Read, list and kill

| Call | Answer |
| - | - |
| `GET /v1/sandboxes/:id` | The sandbox. Another team's sandbox is a 404, the same as one that does not exist |
| `GET /v1/sandboxes?state=pending\|ready\|closed&limit=&cursor=` | `{"sandboxes": [...], "nextCursor"}`, newest first |
| `DELETE /v1/sandboxes/:id` | The sandbox, now `closed` (`deleted`). The Mac kills everything the slot's account runs, wipes the account and frees the slot. Billing stops. Deleting a closed sandbox is a no-op that returns it |

### Run a command

`POST /v1/sandboxes/:id/commands`

| Field | Type | |
| - | - | - |
| `cmd` | string, required | A shell command line, run as `zsh -lc "<cmd>"` as the slot's macOS user. At most 64 KiB |
| `cwd` | string | The working directory, relative to the sandbox root (created if missing). Defaults to the root |
| `envs` | object | Extra environment variables for this command only: at most 64 string values |
| `timeoutMs` | integer | 10 min by default, 30 min at most. It is cut to what is left of the sandbox's life (`expiresAt`) when the Mac starts the command, so a command waiting for a place when you [set the timeout](https://offstage.cloud/docs/api/sandboxes.md#set-the-timeout) gets the new life. At the timeout the command's whole process tree is killed |

```bash theme={null}
curl -s -X POST https://api.offstage.cloud/v1/sandboxes/sbx_…/commands -H "authorization: Bearer $OFFSTAGE_API_KEY" \
  -H 'content-type: application/json' -d '{"cmd": "swift build 2>&1", "cwd": "src", "envs": {"CI": "1"}, "timeoutMs": 1200000}'
```

The answer comes within about 50 s, whatever the command does. If the command ended by then, it is `200` with the result:

```json theme={null}
{ "commandId": "cmd_…", "state": "finished", "exitCode": 0, "timedOut": false, "stdout": "…", "stderr": "", "truncated": false, "durationMs": 48213 }
```

If it is still running, it is `202`:

```json theme={null}
{ "commandId": "cmd_…", "state": "running", "startedAt": 1793000000000 }
```

Then follow it with `GET /v1/sandboxes/:id/commands/:commandId?wait=50` until it answers `200` with the result. Each follow is held until the command ends or `wait` seconds pass (0 to 60, never more than 50 s), and answers `202` again while it runs. If the command itself failed (for example 504 `op-timeout`, or 409 `sandbox-closed` because the sandbox closed under it), the follow answers with that error. A finished command's answer stays readable for 10 minutes, so a follow whose answer was lost can simply be repeated. A team keeps at most 500 answers and 16 MiB of them, and its own oldest go first when a newer one needs the room; a follow for one that went answers 404 `not-found`. Closing a sandbox, however it closes, drops its commands, running or finished, and a follow then answers 409 `sandbox-closed`. Running commands are forgotten if the service restarts, and their follow answers 404 `not-found`.

```bash theme={null}
curl -s "https://api.offstage.cloud/v1/sandboxes/sbx_…/commands/cmd_…?wait=50" -H "authorization: Bearer $OFFSTAGE_API_KEY"
```

No request is held longer than about 50 s, so default client timeouts work, and so do proxies with a 60 s idle timeout. The exceptions are large files: a write answers once its upload is done, and a read streams for as long as the Mac takes to send it, with bytes moving the whole time.

* A non-zero exit is still `200`, so check `exitCode`.
* A command killed at its timeout has `timedOut: true` and `exitCode: null`.
* Each stream keeps its last 1 MiB, and `truncated: true` says the start was dropped. Redirect large output to a file and read the file back.
* In a `gui` sandbox, `stdout` carries both streams and `stderr` is empty.
* Each command is a new process, so `cd` and `export` do not carry over to the next call. Use `cwd` and `envs`.
* There is no streaming output and no stdin.

If the sandbox is `pending`, an op waits up to 30 s for a slot, then answers 409 `sandbox-not-ready`. The op never ran, so it is safe to retry. Starting a command is not idempotent: retry a `POST …/commands` whose answer was lost only if running it twice is harmless.

### Write a file

`PUT /v1/sandboxes/:id/files?path=<path>` with the raw bytes as the body. This writes the file under the sandbox root, creating its directories. It replaces any existing file and never appends.

* A file may be up to 2 GiB, so send an app bundle or a source tree as one archive in one write, and unpack it with one command. Over that is 413 `file-too-large`, refused on the declared `content-length` before any upload, or the moment the bytes that arrive pass it. For anything larger, or already online, download it on the Mac with `curl -fLO <url>`.
* The body goes on to the Mac in 4 MiB parts as it arrives, and the answer comes once all of it is written there. A large write takes as long as its upload, longer than the 50 s other calls are held, so give your HTTP client a long timeout (curl has none by default). The whole body must arrive within 40 minutes, or it is 408 `body-timeout`: 2 GiB needs about 0.9 MB/s.
* A write over 4 MiB keeps its parts in a hidden `.offstage-upload-…` folder at the sandbox root and joins them into the file once the last part is in, so the file is untouched until then. The folder is removed when the write ends.
* A team may have 24 MiB of file writes held at once. A write holds at most 8 MiB however large it is, so three large writes can arrive together. One past that, or past the share every team's writes have together, is 429 `uploads-busy` with a `Retry-After`: send it again once the others finish.

```bash theme={null}
curl -s -X PUT "https://api.offstage.cloud/v1/sandboxes/sbx_…/files?path=src.tgz" -H "authorization: Bearer $OFFSTAGE_API_KEY" \
  -H 'content-type: application/octet-stream' --data-binary @src.tgz
```

The answer is `{"path": "src.tgz", "bytes": 482113}`, with the path as the plane normalized it.

### Read a file

`GET /v1/sandboxes/:id/files?path=<path>` returns the file's bytes exactly, as `application/octet-stream` with its `content-length`. A path that is not a file is 404 `file-not-found`.

* A file may be up to 2 GiB: an `.xcarchive` or `.xcresult` zipped, an `.ipa`, a screen recording. Over that is 413 `file-too-large`: compress it, or split it on the Mac (`split -b 1g out.zip out.zip.`) and read the parts.
* A file over 4 MiB is copied into a hidden `.offstage-download-…` folder at the sandbox root in 4 MiB parts when the read starts, so you get the file as it was then. Its bytes stream as the Mac sends the parts, and the folder is removed when the read ends.
* A large read takes as long as the Mac takes to send it, minutes for a file of a GiB or more, so give your HTTP client a long timeout. If the sandbox closes partway, the connection closes before `content-length` bytes have arrived: read it again.

```bash theme={null}
curl -s "https://api.offstage.cloud/v1/sandboxes/sbx_…/files?path=src/build.log" -H "authorization: Bearer $OFFSTAGE_API_KEY" -o build.log
```

### Take a screenshot

**Requires a GUI sandbox.** `GET /v1/sandboxes/:id/screenshot?maxDimension=<64-8192>` returns a PNG of the slot's screen. It works on `gui` sandboxes only. A `headless` one answers 409 `headless-sandbox`. `maxDimension` scales the image so its longer side fits.

A screenshot is what you read click coordinates from: [Click, type and press keys](https://offstage.cloud/docs/api/sandboxes.md#click-type-and-press-keys) takes them in its pixels. A computer-use agent can drive the screen in three ways: from wherever it runs, with screenshots and input calls over HTTP; by handing the sandbox a goal that Claude carries out on the Mac (see [Hand the screen a goal](https://offstage.cloud/docs/api/sandboxes.md#hand-the-screen-a-goal)); or as a program on the Mac itself, a command in the `gui` sandbox or a task with `"session": "gui"`, which takes screenshots and sends clicks and keys through the session socket below.

### Click, type and press keys

**Requires a GUI sandbox.** `POST /v1/sandboxes/:id/input` with body `{"screen": {"width": W, "height": H}, "actions": [...]}` performs the actions on the slot's screen, in order, and answers `{"performed": N}` once the Mac has performed all of them. For example:

```json theme={null}
{"screen": {"width": 1280, "height": 800},
 "actions": [{"type": "click", "x": 640, "y": 400}, {"type": "type", "text": "hello"}, {"type": "key", "key": "cmd+s"}]}
```

* Coordinates are pixels in a screenshot of the sandbox, origin top left, and `screen` is that screenshot's width and height. The Mac scales them to its display, so read them from whatever `maxDimension` you took the screenshot with. `screen` is required when any action has coordinates. A screenshot whose shape no longer matches the display answers 409 `display-changed`: take a new one.
* The actions are `{"type":"move","x","y"}`, `{"type":"click","x","y","button"?,"count"?,"modifiers"?}`, `{"type":"drag","fromX","fromY","toX","toY","button"?}`, `{"type":"scroll","x","y","dx"?,"dy"?}` (lines; a positive `dy` scrolls the content down), `{"type":"type","text"}`, `{"type":"key","key"}` and `{"type":"wait","ms"}`. `key`, modifier and `button` names are the session socket's, listed below; a double click is `"count": 2`.
* One call carries at most 100 actions, types at most 4,096 characters and waits at most 10 s in all. A list with one bad action performs nothing, and the 400 `bad-input` names it.
* The slot's own session daemon posts the events to that sandbox's session only. Input needs an app in front: 409 `no-target` otherwise. The call returns once the events are posted, not once the app has reacted: take another screenshot to see what happened.
* Typed text is not kept: a recording lists each action, with a `type` action's length only.

The program on the Mac holds no screen or input permission of its own, so it cannot capture the screen or post input itself. It asks the slot's session daemon, over the unix socket named in its `OFFSTAGE_SESSION_SOCKET` environment variable. Each connection carries one request line of JSON and gets back JSON lines, the last one holding `ok`:

* `{"op":"screenshot","maxDimension":1600}` answers `{"ok":true,"png":"<base64>","width":…,"height":…,"scale":…,"points":{"width":…,"height":…}}`. Input coordinates are points: a pixel in the PNG divided by `scale`.
* `{"op":"input","actions":[…]}` answers `{"ok":true,"performed":N}`. The actions are `{"type":"move","x","y"}`, `{"type":"click","x","y","button"?,"count"?,"modifiers"?}`, `{"type":"drag","fromX","fromY","toX","toY"}`, `{"type":"scroll","x","y","dx","dy"}`, `{"type":"type","text"}`, `{"type":"key","key":"cmd+s"}` and `{"type":"wait","ms"}`. A list with one bad action performs nothing, and the error names it. Input reaches the slot's own screen only, and needs an app in front (`no-target` otherwise).
  * `key` is one key name, after any modifiers, joined with `+`: `return`, `cmd+s`, `cmd+shift+t`. Names are US-layout and case-insensitive: `a` to `z`, `0` to `9`, `` - = [ ] \ ; ' , . / ` ``, `return` (or `enter`), `tab`, `space`, `backspace` (or `delete`), `forwarddelete`, `escape` (or `esc`), `left`, `right`, `up`, `down`, `home`, `end`, `pageup`, `pagedown` and `f1` to `f12`. Nothing else: a capital is `shift+a`, `+` is `shift+=`, and text goes in a `type` action.
  * Modifiers are `cmd` (or `command`), `shift`, `ctrl` (or `control`), `alt` (or `opt`, `option`) and `fn`. A click's `modifiers` is a list of them, like `["cmd", "shift"]`.
  * `button` is `left` (the default), `right` or `middle`; `count` is 1 to 5; `wait`'s `ms` is 0 to 10000.

### Hand the screen a goal

**Requires a GUI sandbox.** `POST /v1/sandboxes/:id/agent` with body `{"goal": "...", "maxSteps"?: 1-100, "maxDurationMs"?: 10000-1800000, "model"?: "..."}` and header `x-anthropic-api-key: <your Anthropic API key>` hands a `gui` sandbox's screen a goal. This is computer use run for you: Claude carries it out on the Mac itself: a harness inside the slot takes a screenshot, asks the model what to do, and clicks and types there, until the model calls the goal done or failed, or the run's steps or time run out.

* Write the goal as what should be true at the end: `"TextEdit has a document saved as ~/Desktop/note.txt that says hello"`. At most 4,000 characters.
* `maxSteps` counts model turns (default 30); one turn may carry several actions. `maxDurationMs` defaults to 10 minutes and is at most 30. `model` is one of `claude-opus-5-5` (the default), `claude-sonnet-5-5`, `claude-haiku-5-5`, `claude-fable-5-1` and `claude-opus-5`.
* The model is called with your key and billed to it. The plane holds the key in memory for this run only; the Mac gets a token that works for this run's model calls and dies with the run. No click or key crosses the network: the goal, the model's text, the run's steps and its screenshots do.
* The answer comes within about 50 s: 200 with the run if it ended by then, otherwise 202 with the run so far. Follow it with `GET /v1/runs/:id?wait=50` (200 once it has ended, 202 while it runs). A finished run is kept for 24 hours.
* A run is `{"id":"run_…","sandboxId","goal","maxSteps","maxDurationMs","model","state":"running"|"finished","startedAt","endedAt"?,"verdict"?,"reason"?,"error"?,"steps":[…],"frames"}`. `verdict` is `done` or `failed` when the model said so, and `incomplete` when its steps or time ran out or it broke first (`error` then says how). Each step is `{"seq","at","action","input"?,"ok","error"?,"note"?,"frame"?}`: the computer-use action (`left_click`, `type`, `key`, `scroll`, `screenshot`, …), `finish`, or `note` when the model spoke without acting.
* `GET /v1/runs/:id/frames/frame-0001.png` returns a step's `frame`, the screenshot it took, as a PNG.
* When the sandbox records, the run carries its `replayUrl` too. The recording keeps the run's steps against the screen after the run's own 24 hours are up (see [Recordings](https://offstage.cloud/docs/api/recordings.md)).
* One run at a time per sandbox (409 `agent-running`). The sandbox bills as usual while it runs; the run adds nothing.

```bash theme={null}
curl -s -X POST "https://api.offstage.cloud/v1/sandboxes/sbx_…/agent" -H "authorization: Bearer $OFFSTAGE_API_KEY" \
  -H "x-anthropic-api-key: $ANTHROPIC_API_KEY" -H 'content-type: application/json' \
  -d '{"goal": "TextEdit has a document saved as ~/Desktop/note.txt that says hello"}'
curl -s "https://api.offstage.cloud/v1/runs/run_…?wait=50" -H "authorization: Bearer $OFFSTAGE_API_KEY"
```

### Set the timeout

`POST /v1/sandboxes/:id/timeout` with body `{"timeoutMs": <integer>}` keeps the sandbox alive for `timeoutMs` from now, as E2B's `setTimeout` does, and answers with the sandbox.

* The sandbox then closes at now + `timeoutMs`, whether that is sooner or later than before. `expiresAt` shows the new time, and `timeoutMs` in the answer is the new lifetime counted from creation.
* A sandbox lives at most 24 hours from its creation. A value that would pass that is 400 `bad-timeout`, and the message says how much time is left.
* Lengthening the lifetime reserves the extra time against the credit and the budget, so it can be refused with 402.
* `idleTimeoutMs` is lowered to the new lifetime if it was larger.
* A command still waiting for a place in the sandbox (see [Concurrency inside a sandbox](https://offstage.cloud/docs/api/sandboxes.md#concurrency-inside-a-sandbox)) runs for the new lifetime, up to its own `timeoutMs`. A command already running keeps the end it started with.
* A closed sandbox answers 409 `sandbox-closed`.

### Rename a sandbox

`PATCH /v1/sandboxes/:id` with body `{"name": "<name>"}` renames it and answers with the sandbox. The name follows the rules in [Create a sandbox](https://offstage.cloud/docs/api/sandboxes.md#create-a-sandbox): 400 `bad-name` if it doesn't, 409 `name-taken` if another open sandbox of the team has it. A closed sandbox can be renamed too.

### Sessions: headless and gui

| `session` | Runs in | Good for |
| - | - | - |
| `headless` (default) | The slot's user, with no desktop. Every slot can take one as soon as it boots | `swift build`, `swift run`, clang, make, scripts, anything without a window |
| `gui` | The slot's logged-in desktop session | Screenshots, apps with windows, macOS app `xcodebuild test` and UI tests |

### Paths

A file `path` and a command `cwd` are relative to the sandbox root, `/Users/<slot>/offstage-sandbox/<sandbox id>`.

* They are made of letters, digits, `.`, `_`, `-` and `/`.
* They may not contain a `..` segment, start with `/`, or use `~`, and they must be at most 1024 characters.
* `.` segments and repeated slashes are normalized away: `./a//b` becomes `a/b`.

The rules keep the files API tidy, but they are not the security boundary. A command can read and write anywhere the slot user can. The isolation boundary is the slot's macOS account, and the Mac wipes that account after every sandbox and every task:

* it kills everything the account runs;
* it gives the account a new home folder;
* it deletes what the account left in `/tmp`, `/var/tmp`, `/Users/Shared`, `/Library/Caches` and its temp folders.

The reset clears the slot's files and processes before its next customer, subject to the exceptions below. Caches (SwiftPM, DerivedData, CocoaPods) start cold every time. A GUI slot must have a logged-in desktop before it can accept GUI work.

What the wipe does not cover:

* POSIX shared memory and named semaphores (`shm_open`, `sem_open`) last until the Mac reboots. Don't put secrets in them.
* A TCP server listening on `localhost` can be reachable outside your sandbox. Listen on a Unix socket inside your root instead, or require a token.
* Code in another slot can also read your commands' arguments: macOS lists every account's processes with their command lines. It cannot read their environment. Pass a secret in a command's `envs`, never in its `cmd` or a program's arguments.

### Concurrency inside a sandbox

A sandbox runs up to 16 ops at once, so a file read or a quick command is not stuck behind a long build. Calls you make one after another still happen in that order, because each answers only when it is done. Up to 16 more ops wait for a free place (file writes waiting together hold at most about 24 MiB). An op past that is refused with 409 `op-failed`, its message starting `sandbox-busy`. A command is cut to what is left of the sandbox's life only when it starts, so one still waiting when you lengthen the sandbox gets the new life.

### What is on the Mac

Every sandbox starts with exactly this. What you add goes into its home folder and is wiped with it.

* macOS 27 on Apple silicon (arm64).
* Xcode 27.2 with the iOS 27.2 and iOS 27.0 simulator runtimes, Swift 6.4 with SwiftPM, and Apple clang.
* git, make, curl, rsync, tar, zip, unzip, jq, sqlite3, perl and Ruby 2.6.
* Node 24 or later with npm and npx, and Python 3.9 with pip3.
* Rust stable: `cargo` and `rustc` on the PATH.
* Google Chrome and Safari in `/Applications`.
* Not there: sudo, Homebrew, wget (use `curl -fLO <url>`), a Java runtime, CocoaPods and Go.

Add tools without sudo, into the home folder or the project:

* Node: `npx <tool>`, or `npm install` in the project. For global installs, `npm config set prefix ~/.npm-global` first. Another Node version: a version manager such as nvm installs into the home folder.
* Python: `python3 -m venv .venv && .venv/bin/pip install <package>`, or `pip3 install --user <package>` (its commands go to `~/Library/Python/3.9/bin`).
* Rust targets or another toolchain: `curl -fsSL https://sh.rustup.rs | sh -s -- -y` puts rustup in `~/.cargo`.
* Anything else: a release binary, fetched with `curl -fLO`.
* Each command is a new `zsh -lc`, so a PATH you export does not carry over. Put it in the command (`export PATH=$HOME/.cargo/bin:$PATH && cargo build`), or append the export to `~/.zprofile`, which every later command reads.

Xcode and the simulators:

* Inspect installed Xcode versions and build numbers with `offstage toolchains list --json`. Select an exact installed version and build with `offstage toolchains xcode --version VERSION --build BUILD --json`, then set `DEVELOPER_DIR` to the returned path for every build command. A display version alone does not distinguish a release candidate from the final release; a release toolchain must be provisioned before it can be selected.
* `swift build`, `swift run`, `swiftc`, clang and make work for macOS targets.
* `swift test` runs XCTest and Swift Testing suites (`swift build --build-tests` needs the test target declared).
* `xcodebuild` works against Xcode 27.2 (`-version`, `-list`, project builds, `-sdk iphonesimulator`).
* Simulator creation, boot, screenshot and shutdown have been measured in a headless sandbox. `xcrun simctl list devices available` lists destinations; choose a listed device or create one and use its id.
* To see and drive a simulator, use a gui sandbox. Xcode 27's Simulator is Device Hub (no Simulator.app): after `xcrun simctl boot`, `open -b com.apple.dt.Devices` shows the phone on the desktop, and clicks there reach it. Its toolbar's Zoom In button makes the phone readable. The simulator reads key codes, not text: type with one session-daemon `key` action (the names under [Take a screenshot](https://offstage.cloud/docs/api/sandboxes.md#take-a-screenshot)) per lowercase letter, digit or `space`; `type` actions arrive as the wrong letters and modifier keys don't reach it.
* macOS app `xcodebuild test` needs `session: "gui"`: Apple’s testmanagerd service is unavailable in a headless account. A build can succeed there while the test launch fails. Do not retry the same macOS test in headless or change test destinations to hide the failure.
* End-to-end `xcodebuild test` support for arbitrary iOS projects and XCUITest has not been verified. Run the project's actual command and report its result rather than promising simulator test support.
* If a UI test runner stops with "Failed call to AXDisableAccessibilityOnTermination: kAXErrorCannotComplete" or "Timed out waiting for AX loaded notification", the Mac's accessibility is in a bad state that a restart of the Mac clears; it has happened once. Run the unit tests and tell the user the UI tests could not run.
* `GET /v1/capacity` distinguishes ready, busy, resetting and unavailable work; a busy or resetting desktop can queue GUI work.


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