# offstage cloud > Real Macs for AI agents and CI, over an API: sandboxes, tasks and GitHub Actions runners on Apple silicon. > ## 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. - [A Mac for your agent](https://offstage.cloud/docs/index.md): offstage cloud gives your code and your agents a real Mac over an API. - [Quickstart](https://offstage.cloud/docs/quickstart.md): Run your first command on a real Mac in a few minutes. - [Set up from your agent](https://offstage.cloud/docs/agents.md): One prompt, and your coding agent sets itself up to run builds and tests on a real Mac. - [Sandboxes](https://offstage.cloud/docs/sandboxes.md): A whole macOS user account that you drive one call at a time. - [Use a computer-use model on a Mac desktop](https://offstage.cloud/docs/computer-use.md): Connect a computer-use agent to a real macOS desktop. Take screenshots, click and type with the Offstage helper, with a tested OpenAI Codex example. - [Snapshots](https://offstage.cloud/docs/snapshots.md): Save a sandbox’s home files and start the next run from the same point. - [Tasks](https://offstage.cloud/docs/tasks.md): Fire-and-forget CI: clone a repository, run a command, keep the artifacts. - [GitHub Actions](https://offstage.cloud/docs/github-actions.md): Run your workflows on a Mac by changing runs-on. - [What's on the Mac](https://offstage.cloud/docs/the-mac.md): The hardware, the OS and the tools a sandbox starts with. - [Errors and retries](https://offstage.cloud/docs/errors.md): Every failure has a stable code and says what to do. - [Pricing and limits](https://offstage.cloud/docs/pricing.md): $1.10 an hour, billed by the second, with no minimum. - [API overview](https://offstage.cloud/docs/api/index.md): The base URL, ids, times and money: what every call shares. - [Authentication](https://offstage.cloud/docs/api/authentication.md): Team API keys and console sessions, and what each may do. - [Errors](https://offstage.cloud/docs/api/errors.md): One error shape with a stable code, and what to do about each code. - [Pagination](https://offstage.cloud/docs/api/pagination.md): Lists come newest first, a page at a time, with a cursor. - [Idempotency](https://offstage.cloud/docs/api/idempotency.md): Retry a create safely with an Idempotency-Key. - [Limits](https://offstage.cloud/docs/api/limits.md): Every limit the API enforces, in one table. - [Health](https://offstage.cloud/docs/api/health.md): A public check of the service and its fleet. - [Sandboxes](https://offstage.cloud/docs/api/sandboxes.md): Hold a Mac and drive it one call at a time: commands, files, screenshots and goals. - [Tasks](https://offstage.cloud/docs/api/tasks.md): Fire-and-forget work: clone a repository, run a command, keep the artifacts. - [Recordings](https://offstage.cloud/docs/api/recordings.md): Every GUI sandbox and task leaves a replay: its screen, commands and agent steps. - [Secrets and signing](https://offstage.cloud/docs/api/secrets.md): Write-only team secrets, and signing and notarizing a Mac app in a workload. - [API keys](https://offstage.cloud/docs/api/keys.md): Make, list and revoke team API keys from the console. - [Team and account](https://offstage.cloud/docs/api/team.md): Sign-in, members, invites and organizations. - [Usage](https://offstage.cloud/docs/api/usage.md): What your team ran and spent, day by day. - [Pricing](https://offstage.cloud/docs/api/pricing.md): The public price sheet, with no key needed. - [Billing](https://offstage.cloud/docs/api/billing.md): Credit, the reservation rule, budgets, cards and invoices. - [Spending limits](https://offstage.cloud/docs/api/spending-limits.md): Cap your team's monthly spend. - [JavaScript SDK](https://offstage.cloud/docs/api/sdk.md): The offstage-cloud package: sandboxes, tasks, errors and retries. - [List sandboxes](https://offstage.cloud/docs/api-reference/sandboxes/list-sandboxes.md): Lists the team's sandboxes, newest first. Filter by `state`; page with `limit` and `cursor`. - [Create a sandbox](https://offstage.cloud/docs/api-reference/sandboxes/create-a-sandbox.md): Creates a sandbox: one macOS user account on a fleet Mac, held for you until it closes. It is `pending` until a slot takes it and then `ready`, and bills per second from `ready` until it closes. An empty body gives a default headless sandbox; its worst case (`timeoutMs` at the hourly price) is reser… - [Save a sandbox snapshot](https://offstage.cloud/docs/api-reference/sandboxes/save-a-sandbox-snapshot.md): Capture supported home files while the source sandbox keeps running. Follow a 202 response by reading the snapshot ID. - [List snapshots](https://offstage.cloud/docs/api-reference/sandboxes/list-snapshots.md): List the snapshots that belong to the authenticated team, optionally filtering by source sandbox. - [Read a snapshot](https://offstage.cloud/docs/api-reference/sandboxes/read-a-snapshot.md): Read the capture state, remote durability and expiry of a snapshot by its immutable ID. - [Delete a snapshot](https://offstage.cloud/docs/api-reference/sandboxes/delete-a-snapshot.md): Remove this snapshot from the team and schedule its stored copies for deletion. - [Get a sandbox](https://offstage.cloud/docs/api-reference/sandboxes/get-a-sandbox.md): Returns a sandbox: its state, its Mac and slot, when it expires, and what it has cost so far. - [Kill a sandbox](https://offstage.cloud/docs/api-reference/sandboxes/kill-a-sandbox.md): Closes the sandbox with `closeReason: deleted`: the Mac kills everything still running in it, deletes its root and frees the slot, and billing stops. Killing a closed sandbox is a no-op that returns it. - [Rename a sandbox](https://offstage.cloud/docs/api-reference/sandboxes/rename-a-sandbox.md): Changes the sandbox's `name` and returns it. Only the name: its lifetime has `POST /v1/sandboxes/{sandboxId}/timeout`. A closed sandbox can be renamed too. - [Set the timeout](https://offstage.cloud/docs/api-reference/sandboxes/set-the-timeout.md): Makes the sandbox close `timeoutMs` from now, sooner or later than before, like E2B's `setTimeout`, and returns it; the answer's `timeoutMs` is the new lifetime counted from creation, and `idleTimeoutMs` is lowered to it if it was larger. A sandbox lives at most 24 hours from its creation, and lengt… - [Run a command](https://offstage.cloud/docs/api-reference/sandboxes/run-a-command.md): Runs a shell command line as `zsh -lc` in the sandbox, as the slot's macOS user. The answer comes within about 50 s whatever the command does: 200 with the result if it ended by then, else 202 with a `commandId` to follow with `getCommand`. A non-zero exit is still 200, so check `exitCode`; on a `pe… - [Follow a command](https://offstage.cloud/docs/api-reference/sandboxes/follow-a-command.md): Follows a command that answered 202. Holds until the command ends or `wait` seconds pass (never more than 50 s), then answers 200 with the result, 202 while it still runs, or the command's own error with the status it would have had. A finished command's answer stays readable for 10 minutes, so a lo… - [Read a file](https://offstage.cloud/docs/api-reference/sandboxes/read-a-file.md): Returns the bytes of the file at `path` under the sandbox root, exactly, as `application/octet-stream` with its `content-length`. A file may be up to 2 GiB. One over 4 MiB is copied into a hidden `.offstage-download-…` folder at the sandbox root in 4 MiB parts when the read starts, so the answer is… - [Write a file](https://offstage.cloud/docs/api-reference/sandboxes/write-a-file.md): Writes the raw request body to `path` under the sandbox root, creating its directories and replacing any existing file (it never appends). A file may be up to 2 GiB, refused on the declared `content-length` before any upload. The body goes on to the Mac in 4 MiB parts as it arrives, and the answer c… - [Take a screenshot](https://offstage.cloud/docs/api-reference/sandboxes/take-a-screenshot.md): Returns a PNG of the slot's screen; only `gui` sandboxes have one. Click coordinates for `sendInput` are read in this PNG's pixels, with its width and height as `screen`, whatever `maxDimension` it was taken with. - [Click, type and press keys](https://offstage.cloud/docs/api-reference/sandboxes/click-type-and-press-keys.md): Performs the actions on a `gui` sandbox's screen, in order, and answers once the Mac has performed all of them. Coordinates are pixels in a screenshot of the sandbox (`getScreenshot`), origin top left, and `screen` is that screenshot's width and height; the Mac scales them to its display. `screen` i… - [Hand the screen a goal](https://offstage.cloud/docs/api-reference/sandboxes/hand-the-screen-a-goal.md): Hands a `gui` sandbox's screen a goal, which Claude carries out on the Mac itself: a harness inside the slot screenshots, asks the model what to do, and clicks and types there, until the model calls the goal done or failed, or `maxSteps` or `maxDurationMs` runs out. The model is called with the Anth… - [Follow a run](https://offstage.cloud/docs/api-reference/sandboxes/follow-a-run.md): A run's state, verdict and every step so far. `?wait=N` (up to 60 s; the plane holds at most 50) holds the answer until the run ends or the time passes: 200 once it has ended, 202 while it runs. A finished run is kept for 24 hours. - [Get a run's screenshot](https://offstage.cloud/docs/api-reference/sandboxes/get-a-runs-screenshot.md): A screenshot the run took, as a PNG: name it by a step's `frame`. Kept with the run's other artifacts. - [List tasks](https://offstage.cloud/docs/api-reference/tasks/list-tasks.md): Lists the team's tasks, newest first, as summaries without `events` (`GET /v1/tasks/{taskId}` has them). Filter by `state` and `kind`; page with `limit` and `cursor`. - [Submit a task](https://offstage.cloud/docs/api-reference/tasks/submit-a-task.md): Queues fire-and-forget macOS work: a Mac slot clones `repo` (`git clone --depth 1` of the default branch), runs `command` (or the `agent` program, for `kind: agent`) as `zsh -lc` in the clone with `CI=1`, uploads the promised `artifacts`, and reports the outcome. The task's worst case (`timeoutMs` a… - [Get a task](https://offstage.cloud/docs/api-reference/tasks/get-a-task.md): Returns a task with its event log. With `wait`, holds the request until the task reaches a terminal state or `wait` seconds pass (never more than 50 s), so calling `?wait=50` in a loop follows a task with about one request a minute. - [Cancel a task](https://offstage.cloud/docs/api-reference/tasks/cancel-a-task.md): Ends a task that has not ended yet and returns it in state `cancelled`; no body is needed. A queued task never runs and costs nothing; a claimed or running one is stopped on its Mac within about 15 s and billed up to the cancel, and artifacts it had not uploaded are lost. - [Download an artifact](https://offstage.cloud/docs/api-reference/tasks/download-an-artifact.md): Returns an artifact the task's Mac uploaded, as its raw bytes with the content type it was uploaded with, served as a download. It is 404 until the Mac uploads it, for a name the task did not promise, and once it is deleted, 7 days after its task ends. - [Get a recording](https://offstage.cloud/docs/api-reference/recordings/get-a-recording.md): The timeline so far, or all of it once it has ended. To follow one live, use `GET /v1/recordings/{recordingId}/live`. - [Get a recording's picture](https://offstage.cloud/docs/api-reference/recordings/get-a-recordings-picture.md): A picture the timeline names, by an entry's `frame`: a JPEG the plane took, or a PNG an agent run's harness took. It never changes, so it may be cached. - [Follow a recording live](https://offstage.cloud/docs/api-reference/recordings/follow-a-recording-live.md): Server-sent events: an `entry` event (an id of its `seq`, and a RecordingEntry as data) for each entry after `after`, then each new one as it happens; then an `end` event (the Recording without its entries) and the stream closes. A comment every 15 s keeps it open, and a stream lasts at most 10 minu… - [Fleet capacity](https://offstage.cloud/docs/api-reference/capacity/fleet-capacity.md): Current readiness from authenticated reports no older than45seconds. Counts break down ready, busy, resetting and unavailable by work kind/session. queued.sandboxes counts only this team. Busy/resetting work may queue. Counts overlap and must not be added. - [Health](https://offstage.cloud/docs/api-reference/capacity/health.md): Says the plane is up, with the number of queued tasks and of sandboxes waiting for a slot. Public: no credential needed. - [The price sheet](https://offstage.cloud/docs/api-reference/billing/the-price-sheet.md): The public price sheet: dollars per hour, minute and second of a sandbox or task, billed per second with no minimum, and the free credit. No credential needed. - [Usage](https://offstage.cloud/docs/api-reference/billing/usage.md): The team's metered usage over the last `days` UTC days: totals, one row per day (zeros included), and one row per API key, most expensive first. Work counts on the day it ended, and work still running counts up to now; a `byKey` row with `keyId: null` is work started from the console. - [Billing state](https://offstage.cloud/docs/api-reference/billing/billing-state.md): The team's billing state: the card on file, the free credit, this month's spend and what in-flight work holds, the budget and its alerts, the credit ceiling a card is held to, and whether new work is paused (`status: past_due`). - [Set the budget](https://offstage.cloud/docs/api-reference/billing/set-the-budget.md): Sets the team's monthly budget (`limitUsd`, or null for none) and whether it is enforced, and returns the billing object; an enforced budget refuses work that could pass it. A new amount re-evaluates this month's alerts. Owners only. Console session only: an API key gets 403 `console-only`. - [Start adding a card](https://offstage.cloud/docs/api-reference/billing/start-adding-a-card.md): Starts adding a card and returns the checkout `url` to send the browser to: Stripe Checkout, or the plane's own stand-in in test mode. The browser comes back to `returnUrl` with `?checkout=success&session_id=…` (then call `completeCheckout`) or `?checkout=cancelled`. Owners only. Console session onl… - [Finish adding a card](https://offstage.cloud/docs/api-reference/billing/finish-adding-a-card.md): Attaches the card from a finished checkout and returns the billing object with it. If the team is `past_due`, its failed invoices are charged again at once. Owners only. Console session only: an API key gets 403 `console-only`. - [Start buying credit](https://offstage.cloud/docs/api-reference/billing/start-buying-credit.md): Starts buying `amountUsd` of credit, from $5 to $2,000, and returns the checkout `url` to send the browser to: Stripe Checkout in payment mode (which handles 3-D Secure and Apple Pay), or the plane's own stand-in in test mode. The card paid with is saved for auto-reload and becomes the card on file.… - [Finish buying credit](https://offstage.cloud/docs/api-reference/billing/finish-buying-credit.md): Grants the credit a finished checkout paid for, if Stripe's webhook has not already, and returns the billing object with it. Calling it again, or after the webhook, grants nothing more. A team that was `postpaid` is on prepaid credit from then on. Owners only. Console session only: an API key gets 4… - [Turn auto-reload on or off](https://offstage.cloud/docs/api-reference/billing/turn-auto-reload-on-or-off.md): With `enabled: true`, whenever the balance (credit left, less what work in flight holds) falls below `thresholdUsd`, the card on file is charged off-session for what brings it back to `targetUsd`. `targetUsd` must be at least $5 above `thresholdUsd` and at most $2,000. At most 5 reloads a UTC day, o… - [List credit bought](https://offstage.cloud/docs/api-reference/billing/list-credit-bought.md): Every payment that became credit, newest first: when, how much, whether auto-reload charged it, and Stripe's receipt when Stripe gave one. - [Remove the card](https://offstage.cloud/docs/api-reference/billing/remove-the-card.md): Removes the card on file and returns the billing object. Without a card, new work must fit in the remaining free credit. Owners only. Console session only: an API key gets 403 `console-only`. - [Open the customer portal](https://offstage.cloud/docs/api-reference/billing/open-the-customer-portal.md): Returns a `url` to the payment provider's customer portal, which comes back to `returnUrl`. Test mode has no portal. Owners only. Console session only: an API key gets 403 `console-only`. - [List invoices](https://offstage.cloud/docs/api-reference/billing/list-invoices.md): The team's monthly invoices, newest first, all at once (not paginated). Each UTC month that had usage gets one, charged to the card on file. - [Sign up](https://offstage.cloud/docs/api-reference/account/sign-up.md): Creates a user and a team they own, signs them in by setting the `oc_session` cookie, and returns both. It emails a link that verifies the address; until the owner opens it, the team cannot create sandboxes, tasks or API keys (`team.verified` is false). Invites already sent to the email take effect… - [Sign in](https://offstage.cloud/docs/api-reference/account/sign-in.md): Checks the email and password, sets the `oc_session` cookie for the user's own team (or their first team), and returns the user and that team. No credential needed. - [What the sign-in page offers](https://offstage.cloud/docs/api-reference/account/what-the-sign-in-page-offers.md): The Clerk publishable key the console's GitHub and Google buttons load Clerk with, and which of the two buttons to show, or null when this plane offers email sign-in alone; and the API address the console gives agents. Public: the key is meant for browsers. No credential needed. - [Sign in with GitHub or Google](https://offstage.cloud/docs/api-reference/account/sign-in-with-github-or-google.md): Trades the token of the Clerk session the console's GitHub or Google sign-in just made for this plane's session cookie. The token is checked against the Clerk instance's keys, issuer, this site and its lifetime; the email comes from Clerk and must be one Clerk verified. Signs in the account at that… - [Sign out](https://offstage.cloud/docs/api-reference/account/sign-out.md): Ends the console session, if the request carries one, and clears the cookie. It always answers 204. - [Verify an email](https://offstage.cloud/docs/api-reference/account/verify-an-email.md): Spends the token from the link emailed at signup and marks its user's email verified, which lets their team run work and make keys. A token works once and lasts 24 hours; verifying spends every link the user holds. It does not sign in. No credential needed. - [Send the verification email again](https://offstage.cloud/docs/api-reference/account/send-the-verification-email-again.md): Emails the signed-in user a new verification link. Earlier links keep working until they expire or one is used. At most 3 an hour per user. - [Ask for a password-reset link](https://offstage.cloud/docs/api-reference/account/ask-for-a-password-reset-link.md): Mails a link to `/reset-password#token=…` if the address has an account. The link works once and lasts 1 hour. The answer is the same whether or not an account exists, so it says nothing about which addresses have one. No credential needed. - [Choose a new password](https://offstage.cloud/docs/api-reference/account/choose-a-new-password.md): Spends the token from the reset link and sets the new password. Every other session the user had ends, every reset link they hold is spent, and their email counts as verified. Pending invites to the address are joined. Every personal API key the user made, on every team, is revoked; service keys are… - [The signed-in user](https://offstage.cloud/docs/api-reference/account/the-signed-in-user.md): Returns the signed-in user, the team the session acts for, their role on it, and every team they belong to. Console session only: an API key gets 403 `console-only`. - [Switch teams](https://offstage.cloud/docs/api-reference/account/switch-teams.md): Points the session at another team the user belongs to; everything after acts for that team. An invited address is on the team only once it is verified. Console session only: an API key gets 403 `console-only`. - [The team](https://offstage.cloud/docs/api-reference/account/the-team.md): Returns the caller's team and its limits. - [Rename the team](https://offstage.cloud/docs/api-reference/account/rename-the-team.md): Renames the team and returns it. Owners only. Console session only: an API key gets 403 `console-only`. - [List members](https://offstage.cloud/docs/api-reference/account/list-members.md): Lists the team's members, oldest first, and the invites not yet taken up. Console session only: an API key gets 403 `console-only`. - [Invite a member](https://offstage.cloud/docs/api-reference/account/invite-a-member.md): Adds an existing user whose email is verified to the team at once as a `member` (answering `{member}`), or records an invite (answering `{invite}`) that takes effect when that address is proven: by opening its verification link, resetting its password, or signing in with GitHub or Google. Signing up… - [Remove a member](https://offstage.cloud/docs/api-reference/account/remove-a-member.md): Removes a member from the team, and revokes the personal API keys they made on it; service keys are the team's and stay. Anyone may remove themselves (leave); only an owner may remove someone else, and the last owner cannot be removed. Console session only: an API key gets 403 `console-only`. - [Change a member's role](https://offstage.cloud/docs/api-reference/account/change-a-members-role.md): Makes a member an owner, or an owner a member, and returns the membership. Owners only; a team keeps at least one owner. Console session only: an API key gets 403 `console-only`. - [Withdraw an invite](https://offstage.cloud/docs/api-reference/account/withdraw-an-invite.md): Withdraws a pending invite, so whoever later signs up with or proves that address does not join the team. Owners only. Console session only: an API key gets 403 `console-only`. - [List API keys](https://offstage.cloud/docs/api-reference/account/list-api-keys.md): Lists the team's live API keys, oldest first, by mask only: a key's secret is shown once, when it is created. Each says its `kind`: `personal` or `service`. Console session only: an API key gets 403 `console-only`. - [Create an API key](https://offstage.cloud/docs/api-reference/account/create-an-api-key.md): Creates an API key for the team and returns its secret in `key`, the only time it is ever shown; the plane keeps only its hash. Usage groups by the key's `name`. A person's key is `personal` (it goes when they leave the team or recover the account) unless an owner asks for `kind: "service"`, a key t… - [Revoke an API key](https://offstage.cloud/docs/api-reference/account/revoke-an-api-key.md): Revokes a key; it stops working at once. A revoked key cannot be restored, so make a new one. Console session only: an API key gets 403 `console-only`. - [Create an organization](https://offstage.cloud/docs/api-reference/account/create-an-organization.md): Creates an organization owned by the signed-in user and returns it. The session stays on its current team; switch with POST /v1/me/team. An organization has no free credit: it runs work once it has a card. Console session only: an API key gets 403 `console-only`. - [The team's GitHub connection](https://offstage.cloud/docs/api-reference/github/the-teams-github-connection.md): Whether this plane runs GitHub Actions jobs at all (`configured`), the GitHub App installations linked to this team, and the last job that got no runner, with why. Any member may read it. Console session only: an API key gets 403 `console-only`. - [Start connecting a GitHub organization](https://offstage.cloud/docs/api-reference/github/start-connecting-a-github-organization.md): Returns the `url` of GitHub's sign-in page for the offstage app, and sets a cookie holding a signed state that names this team and the signed-in owner, good for 30 minutes. GitHub sends the browser back to `/v1/github/setup` on the console with a code; the plane learns from it who the person is on G… - [Disconnect a GitHub installation](https://offstage.cloud/docs/api-reference/github/disconnect-a-github-installation.md): Unlinks the installation from this team: none of its organization's jobs runs here any more, and the ones still waiting for a Mac are cancelled (their runner registrations deleted). The app stays installed on GitHub until an organization owner uninstalls it there; connecting again links it again. Ow… - [Read this team’s GitHub connection and repository access](https://offstage.cloud/docs/api-reference/github/read-this-team’s-github-connection-and-repository-access.md): Team-key preflight before runs-on:offstage-macos. Missing organization/repository requires an owner to open connectUrl. Unconnected installations send no job webhook; their waiting jobs cannot be cancelled by offstage. Connection changes still require an owner console session. - [List team secret metadata](https://offstage.cloud/docs/api-reference/secrets/list-team-secret-metadata.md): Manage only the verified caller’s team secrets. Values are write-only; selected workloads receive owner-only files. Missing vault configuration fails closed. - [Create or replace a write-only team secret](https://offstage.cloud/docs/api-reference/secrets/create-or-replace-a-write-only-team-secret.md): Manage only the verified caller’s team secrets. Values are write-only; selected workloads receive owner-only files. Missing vault configuration fails closed. - [Delete a team secret](https://offstage.cloud/docs/api-reference/secrets/delete-a-team-secret.md): Manage only the verified caller’s team secrets. Values are write-only; selected workloads receive owner-only files. Missing vault configuration fails closed. ## OpenAPI Specs - [openapi](/docs/openapi.json) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.