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, 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 keeps it open longer, up to 24 hours from creation. Kill it when the work is done.
Create a sandbox
POST /v1/sandboxes
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
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). A closed sandbox adds closedAt and closeReason. The reasons are:
deleted: you killed it.expired: it reachedcreatedAt + timeoutMs. An op sent after that closes it there and then, and is refused with 409sandbox-closed.idle: it wentidleTimeoutMswith no op.box-lost: its Mac stopped answering for 2 minutes, mid-command or not. A command still running then fails with 409sandbox-closed. It is billed only up to the Mac’s last answer, and itscostUsdandruntimeSecondsstop 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 sandboxesready, 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 itstimeoutMsran 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
Run a command
POST /v1/sandboxes/:id/commands
200 with the result:
202:
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.
- A non-zero exit is still
200, so checkexitCode. - A command killed at its timeout has
timedOut: trueandexitCode: null. - Each stream keeps its last 1 MiB, and
truncated: truesays the start was dropped. Redirect large output to a file and read the file back. - In a
guisandbox,stdoutcarries both streams andstderris empty. - Each command is a new process, so
cdandexportdo not carry over to the next call. Usecwdandenvs. - There is no streaming output and no stdin.
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 declaredcontent-lengthbefore any upload, or the moment the bytes that arrive pass it. For anything larger, or already online, download it on the Mac withcurl -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-busywith aRetry-After: send it again once the others finish.
{"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
.xcarchiveor.xcresultzipped, an.ipa, a screen recording. Over that is 413file-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-lengthbytes have arrived: read it again.
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 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); 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:
- Coordinates are pixels in a screenshot of the sandbox, origin top left, and
screenis that screenshot’s width and height. The Mac scales them to its display, so read them from whatevermaxDimensionyou took the screenshot with.screenis required when any action has coordinates. A screenshot whose shape no longer matches the display answers 409display-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 positivedyscrolls the content down),{"type":"type","text"},{"type":"key","key"}and{"type":"wait","ms"}.key, modifier andbuttonnames 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-inputnames it. - The slot’s own session daemon posts the events to that sandbox’s session only. Input needs an app in front: 409
no-targetotherwise. 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
typeaction’s length only.
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 byscale.{"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-targetotherwise).keyis one key name, after any modifiers, joined with+:return,cmd+s,cmd+shift+t. Names are US-layout and case-insensitive:atoz,0to9,- = [ ] \ ; ' , . / `,return(orenter),tab,space,backspace(ordelete),forwarddelete,escape(oresc),left,right,up,down,home,end,pageup,pagedownandf1tof12. Nothing else: a capital isshift+a,+isshift+=, and text goes in atypeaction.- Modifiers are
cmd(orcommand),shift,ctrl(orcontrol),alt(oropt,option) andfn. A click’smodifiersis a list of them, like["cmd", "shift"]. buttonisleft(the default),rightormiddle;countis 1 to 5;wait’smsis 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. maxStepscounts model turns (default 30); one turn may carry several actions.maxDurationMsdefaults to 10 minutes and is at most 30.modelis one ofclaude-opus-5-5(the default),claude-sonnet-5-5,claude-haiku-5-5,claude-fable-5-1andclaude-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"}.verdictisdoneorfailedwhen the model said so, andincompletewhen its steps or time ran out or it broke first (errorthen says how). Each step is{"seq","at","action","input"?,"ok","error"?,"note"?,"frame"?}: the computer-use action (left_click,type,key,scroll,screenshot, …),finish, ornotewhen the model spoke without acting. GET /v1/runs/:id/frames/frame-0001.pngreturns a step’sframe, the screenshot it took, as a PNG.- When the sandbox records, the run carries its
replayUrltoo. The recording keeps the run’s steps against the screen after the run’s own 24 hours are up (see Recordings). - One run at a time per sandbox (409
agent-running). The sandbox bills as usual while it runs; the run adds nothing.
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.expiresAtshows the new time, andtimeoutMsin 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.
idleTimeoutMsis lowered to the new lifetime if it was larger.- A command still waiting for a place in the sandbox (see 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: 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
Paths
A filepath 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//bbecomesa/b.
- 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/Cachesand its temp folders.
- 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
localhostcan 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 itscmdor 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 409op-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:
cargoandrustcon the PATH. - Google Chrome and Safari in
/Applications. - Not there: sudo, Homebrew, wget (use
curl -fLO <url>), a Java runtime, CocoaPods and Go.
- Node:
npx <tool>, ornpm installin the project. For global installs,npm config set prefix ~/.npm-globalfirst. Another Node version: a version manager such as nvm installs into the home folder. - Python:
python3 -m venv .venv && .venv/bin/pip install <package>, orpip3 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 -- -yputs 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.
- Inspect installed Xcode versions and build numbers with
offstage toolchains list --json. Select an exact installed version and build withoffstage toolchains xcode --version VERSION --build BUILD --json, then setDEVELOPER_DIRto 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 testruns XCTest and Swift Testing suites (swift build --build-testsneeds the test target declared).xcodebuildworks 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 availablelists 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.Devicesshows 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-daemonkeyaction (the names under Take a screenshot) per lowercase letter, digit orspace;typeactions arrive as the wrong letters and modifier keys don’t reach it. - macOS app
xcodebuild testneedssession: "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 testsupport 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/capacitydistinguishes ready, busy, resetting and unavailable work; a busy or resetting desktop can queue GUI work.