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

# Follow a command

> 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 lost follow can be repeated, within caps: a team keeps at most 500 answers and 16 MiB of them, and the plane 10,000 and 128 MiB across teams. Past a cap the team's own oldest answers go first, never another team's; an answer that cannot fit is not kept, though the request waiting on it still gets it. Closing a sandbox drops its commands. Running commands are forgotten if the plane restarts.



## OpenAPI

````yaml /openapi.json get /v1/sandboxes/{sandboxId}/commands/{commandId}
openapi: 3.1.0
info:
  title: offstage cloud API
  version: 0.1.0
  summary: Real Macs for AI agents and CI, over HTTP.
  description: >-
    macOS sandboxes driven one call at a time, and fire-and-forget CI tasks, on
    Apple silicon Macs running macOS 27.


    - **Auth.** `Authorization: Bearer sk_offstage_…` (a team API key; one made
    before 2026-10-29 starts with `oc_live_` and still works), or the console's
    `oc_session` cookie. Operations marked `x-console-only: true` take only the
    cookie; an API key gets 403 `console-only`. A cookie request that changes
    something must come from this origin.

    - **Errors.** Every failure is `{"error": {"code", "message", "fix"?,
    "requestId"}}`. Switch on `code`; `fix`, when present, says what to do. Any
    operation can also answer 500 `internal` (a bug; quote the `requestId`), and
    an unknown route is 404 `no-such-route`.

    - **Request ids.** Every response carries an `x-request-id` header, repeated
    as `requestId` in error bodies.

    - **Units.** Times are Unix milliseconds, and durations end in `Ms`. Money
    is US dollars as numbers, exact to the micro-dollar (`costUsd`).

    - **Ids** are prefixed: `sbx_` sandbox, `cmd_` command, `run_` agent run,
    `task_` task, `key_` API key, `req_` request, `team_`, `usr_`, `box_` (a
    fleet Mac), `inv_`.

    - **Lists** are newest first. Pass the previous page's `nextCursor` as
    `cursor`; it is null on the last page.

    - **Bodies.** JSON, except file writes, which send raw bytes. Request
    schemas with `additionalProperties: false` refuse an unknown field with 400
    `unknown-field`.

    - **Limits.** A team may send 120 requests a minute, whatever key or session
    it uses. Every request also counts against its client address: 600 a minute,
    and far fewer on the routes that need no credential (5 sign-ups an hour, 20
    sign-ins and 20 verifications a minute). Over a window is 429 `rate-limit`
    with a `Retry-After` header.

    - **Verification.** A new account's team can sign in and look around, but
    cannot create sandboxes, tasks or API keys (403 `email-unverified`) until
    its owner opens the link emailed at signup.

    - **Holds.** No request is held longer than about 50 s, so default client
    timeouts and 60 s proxy idle timeouts are fine, except large files: a write
    answers once its upload is done, and a read streams for as long as the Mac
    takes to send it.


    The prose reference, with examples, is
    `https://api.offstage.cloud/llms.txt`. The agent setup guide is
    `https://api.offstage.cloud/SKILL.md`.
servers:
  - url: https://api.offstage.cloud
security:
  - apiKey: []
  - consoleSession: []
tags:
  - name: Sandboxes
    description: >-
      A Mac slot (a macOS user account) held for you: run commands, move files,
      take screenshots.
  - name: Tasks
    description: >-
      Fire-and-forget macOS work: clone a public repo, run a command, collect
      artifacts.
  - name: Recordings
    description: >-
      What a gui sandbox or gui task showed and did, kept by the plane: live
      while it runs, a replay after. Open one in the console at `/r/{id}`.
  - name: Capacity
    description: What the fleet can take right now, and whether the plane is up.
  - name: Billing
    description: The price, usage, the bill, the budget and the card.
  - name: Account
    description: Signing in, the team, its members and its API keys.
  - name: GitHub
    description: >-
      GitHub Actions jobs on offstage Macs: connect an organization in the
      console, then `runs-on: offstage-macos`.
  - name: Secrets
    description: Write-only team credentials selected by workload name.
paths:
  /v1/sandboxes/{sandboxId}/commands/{commandId}:
    get:
      tags:
        - Sandboxes
      summary: Follow a command
      description: >-
        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 lost follow can be repeated, within caps: a team keeps
        at most 500 answers and 16 MiB of them, and the plane 10,000 and 128 MiB
        across teams. Past a cap the team's own oldest answers go first, never
        another team's; an answer that cannot fit is not kept, though the
        request waiting on it still gets it. Closing a sandbox drops its
        commands. Running commands are forgotten if the plane restarts.
      operationId: getCommand
      parameters:
        - $ref: '#/components/parameters/SandboxId'
        - $ref: '#/components/parameters/CommandId'
        - $ref: '#/components/parameters/Wait'
      responses:
        '200':
          description: The command has ended.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandResult'
        '202':
          description: The command is still running; follow again.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandRunning'
        '400':
          description: >-
            `bad-wait`: `wait` must be a number of seconds from 0 to 60. Or the
            command's own `bad-path` from the Mac.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: >-
            `unauthorized`: no credential, an `Authorization` header that is not
            `Bearer …`, a value that is not an `sk_offstage_` (or older
            `oc_live_`) key, a revoked or unknown key, or a box token. The
            message says which.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            `not-found`: no such sandbox, or no such command in it (never
            started, finished more than 10 minutes ago, pushed out by the team's
            newer answers or not kept under the caps, or forgotten in a plane
            restart).
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            `sandbox-closed`: the sandbox has closed, and its commands went with
            it; or the command's own error, `sandbox-closed` (the sandbox closed
            under it) or `op-failed`.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '504':
          description: >-
            `op-timeout`: the Mac did not answer within the op's deadline (a
            command's `timeoutMs` plus 30 s; 90 s for each 4 MiB part of a file
            read or write, or a screenshot), counted from when it took the op;
            or no place freed in the sandbox for the op within that deadline,
            and it never ran. GET the sandbox: if it closed as `box-lost`, start
            over; otherwise retry.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKey: []
        - consoleSession: []
components:
  parameters:
    SandboxId:
      name: sandboxId
      in: path
      required: true
      description: A sandbox id, `sbx_…`.
      schema:
        type: string
    CommandId:
      name: commandId
      in: path
      required: true
      description: The `commandId` from `runCommand`, `cmd_…`.
      schema:
        type: string
    Wait:
      name: wait
      in: query
      required: false
      description: >-
        Hold the request up to this many seconds for it to end. 0 to 60 is
        accepted; the plane never holds more than 50 s.
      schema:
        type: number
        minimum: 0
        maximum: 60
        default: 0
  headers:
    RequestId:
      description: This request's id, `req_…`. Quote it when asking for help.
      required: true
      schema:
        type: string
        pattern: ^req_
  schemas:
    CommandResult:
      type: object
      description: >-
        A command that ended. The fields after `state` are the Mac's own answer,
        relayed as it sent them.
      properties:
        commandId:
          type: string
          description: '`cmd_…`.'
          pattern: ^cmd_
        state:
          const: finished
        exitCode:
          type:
            - integer
            - 'null'
          description: Null when the command was killed at its timeout.
        timedOut:
          type: boolean
        stdout:
          type: string
          description: >-
            The last 1 MiB of standard output. In a `gui` sandbox it carries
            both streams.
        stderr:
          type: string
          description: The last 1 MiB of standard error. Empty in a `gui` sandbox.
        truncated:
          type: boolean
          description: True when the start of a stream was dropped to keep its last 1 MiB.
        durationMs:
          type: integer
          minimum: 0
      required:
        - commandId
        - state
        - exitCode
        - timedOut
        - stdout
        - stderr
        - truncated
        - durationMs
      examples:
        - commandId: cmd_mh3k2f9aQ1xYz0aBcDeFgHiJ
          state: finished
          exitCode: 0
          timedOut: false
          stdout: |
            Build complete!
          stderr: ''
          truncated: false
          durationMs: 48213
    CommandRunning:
      type: object
      properties:
        commandId:
          type: string
          description: Follow it at `GET /v1/sandboxes/{sandboxId}/commands/{commandId}`.
          pattern: ^cmd_
        state:
          const: running
        startedAt:
          $ref: '#/components/schemas/Millis'
      required:
        - commandId
        - state
        - startedAt
      additionalProperties: false
      description: A command still running.
      examples:
        - commandId: cmd_mh3k2f9aQ1xYz0aBcDeFgHiJ
          state: running
          startedAt: 1793000000000
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: >-
                Stable and machine-readable, like `sandbox-closed`. Switch on
                this, not on the message.
            message:
              type: string
              description: What went wrong, for a person.
            fix:
              type: string
              description: What to do about it, when there is something to do.
            requestId:
              type: string
              description: >-
                The same as the `x-request-id` header. Quote it when asking for
                help.
              pattern: ^req_
          required:
            - code
            - message
            - requestId
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: >-
        The one error envelope: every 4xx and 5xx the plane itself sends. A
        proxy in front of it may send a 5xx whose body is not JSON.
      examples:
        - error:
            code: sandbox-closed
            message: sandbox sbx_mh3k2f9aQ1xYz0aBcDeFgHiJ is closed (idle)
            fix: create a new sandbox
            requestId: req_mh3k2f9aQ1xYz0aBcDeFgHiJ
    Millis:
      type: integer
      minimum: 0
      description: A time, in Unix milliseconds.
  responses:
    RateLimited:
      description: >-
        `rate-limit`: this team has sent more than 120 requests in the last 60
        s, or this client address more than 600 (fewer on the routes that need
        no credential). The `Retry-After` header gives the seconds left in the
        window.
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          schema:
            type: string
          description: Seconds until the window opens again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        A team API key, `sk_offstage_…`, created in the console. Everything it
        touches belongs to its team.
    consoleSession:
      type: apiKey
      in: cookie
      name: oc_session
      description: >-
        The console's session cookie (httpOnly, SameSite=Lax, 30 days), set by
        `signup` and `login`.

````

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