{ apiKey?, baseUrl? }, which default to OFFSTAGE_API_KEY and https://api.offstage.cloud.
Headless or gui
Useheadless 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), or let your own computer-use agent 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). 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: