Capture and restore
SetOFFSTAGE_API_KEY in your environment and install the SDK.
snapshot.mjs
Local and durable captures
The SDK waits for local capture before it returns. Use the immutable ID at that point. If the source Mac loses its copy before the upload completes, the snapshot may become unavailable. Readawait Snapshot.getInfo(id) with Snapshot imported from offstage-cloud. When durableAt is present, Offstage has verified the encrypted remote copy. A new sandbox can then restore on another compatible Mac. The saved session type (headless or GUI) and macOS major version must match. Downloading the files and starting a desktop can take time. Wait for ready() before running commands.
A name such as test-baseline selects the latest verified snapshot saved with that name. When you reuse a name, the previous snapshot remains available until the replacement becomes durable, then Offstage removes the old snapshot. Give captures distinct names to keep both.
Use agent tools
Give Codex or another coding agent the sandbox ID and ask it to save the sandbox and wait for the verified upload. The SDK installed above includes the snapshot CLI. For example, with a ready sandbox ID inSANDBOX_ID:
npx --no-install offstage-cloud snapshot show SNAPSHOT_ID to check durableAt, and npx --no-install offstage-cloud snapshot restore SNAPSHOT_ID to create a new sandbox. The restore prints its ID. Wait for readiness in the SDK before running work, and close that sandbox when finished.
These MCP tool names require an Offstage MCP server that includes snapshot tools (version 0.5.1 or later).
What carries over
- Project files and tools. The working directory and supported home files carry over. Recognized Python virtual-environment paths are adjusted for the new home. Flush writes and save open documents before capture. Launch apps and processes again after restore.
- Browser data. GUI snapshots include the standalone default keychain Offstage sets up for the sandbox. A restored Chrome profile can use encrypted cookies backed by that keychain. A website can still expire a session or require another sign-in.
- Fresh on restore. Safari data, protected app containers, native login and iCloud keychains, device-bound keys, user LaunchAgents and login startup settings are excluded. Headless captures exclude keychains entirely.
- Secrets. Select any required Offstage-managed secrets again when creating the restored sandbox. A token copied into a project file or saved in a supported app profile can travel with the snapshot. Treat the contents as accessible to your team.
Limits and retention
Your team can keep 10 snapshots totaling 20 GB, with a 5 GB limit per snapshot. These sizes are measured before compression. A successful restore renews the 30-day retention period. Offstage sends a warning before deleting an unused snapshot. ReadexpiresAt for its current expiry.
List captures with await Snapshot.list(), or filter by sourceSandboxId. Delete a capture with await Snapshot.delete(id) when you no longer need it. For HTTP response codes and polling, see the Sandbox API reference.