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

# Click, type and press keys

> 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` is required when any action has coordinates. The slot's own session daemon posts the events to that sandbox's session only. The call does not wait for the app to react: take another screenshot to see what happened. At most 100 actions, 4,096 typed characters and 10 s of `wait` per call. A list with one bad action performs nothing. A recording lists each action, with a `type` action's length only, never its text.



## OpenAPI

````yaml /openapi.json post /v1/sandboxes/{sandboxId}/input
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}/input:
    post:
      tags:
        - Sandboxes
      summary: Click, type and press keys
      description: >-
        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` is required when any action has coordinates. The
        slot's own session daemon posts the events to that sandbox's session
        only. The call does not wait for the app to react: take another
        screenshot to see what happened. At most 100 actions, 4,096 typed
        characters and 10 s of `wait` per call. A list with one bad action
        performs nothing. A recording lists each action, with a `type` action's
        length only, never its text.
      operationId: sendInput
      parameters:
        - $ref: '#/components/parameters/SandboxId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InputRequest'
      responses:
        '200':
          description: Every action was performed.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InputResult'
        '400':
          description: >-
            `not-an-object`, or `bad-input`: `screen` or an action is wrong,
            coordinates are missing their `screen` or fall outside it, or the
            call asks for more than 100 actions, 4,096 typed characters or 10 s
            of waits. The message names the action and field. Nothing was
            performed.
          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 it belongs to another team.'
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            `sandbox-not-ready`: the sandbox was still `pending` after waiting
            30 s for a slot; nothing ran, so retry, or GET the sandbox until it
            is `ready`. `sandbox-closed`: the sandbox has closed; the message
            gives the reason. `headless-sandbox`: a `headless` sandbox has no
            screen; create one with `"session": "gui"`. `display-changed`:
            `screen` is not the shape of the sandbox's display; take a new
            screenshot and read the coordinates from it. `no-target`: no app is
            in front to deliver to; open or click one first. `op-failed`: the
            Mac reported another error; the message starts with the Mac's own
            code and says how many actions were performed first.
          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 (5 s
            plus the call's waits and typing, plus 30 s), counted from when it
            took the op. GET the sandbox: if it closed as `box-lost`, start
            over; otherwise take a screenshot to see what was done.
          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
  schemas:
    InputRequest:
      type: object
      properties:
        screen:
          $ref: '#/components/schemas/InputScreen'
        actions:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/InputAction'
      required:
        - actions
      additionalProperties: false
      examples:
        - screen:
            width: 1280
            height: 800
          actions:
            - type: click
              x: 640
              'y': 400
            - type: type
              text: hello
            - type: key
              key: cmd+s
    InputResult:
      type: object
      properties:
        performed:
          type: integer
          minimum: 0
          description: 'How many actions the Mac performed: all of them.'
      required:
        - performed
      additionalProperties: false
    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
    InputScreen:
      type: object
      description: >-
        The size of the screenshot an input call's coordinates were read from,
        in pixels.
      properties:
        width:
          type: integer
          minimum: 1
          maximum: 8192
        height:
          type: integer
          minimum: 1
          maximum: 8192
      required:
        - width
        - height
      additionalProperties: false
    InputAction:
      description: >-
        One input action. Key, modifier and button names: `key` is one key after
        any modifiers, joined with `+`, like `return`, `cmd+s` or `cmd+shift+t`.
        Keys are US-layout and case-insensitive: `a` to `z`, `0` to `9`, `` - =
        [ ] \ ; ' , . / ` ``, `return` (or `enter`), `tab`, `space`, `backspace`
        (or `delete`), `forwarddelete`, `escape` (or `esc`), `left`, `right`,
        `up`, `down`, `home`, `end`, `pageup`, `pagedown` and `f1` to `f12`.
        Modifiers are `cmd` (or `command`), `shift`, `ctrl` (or `control`),
        `alt` (or `opt`, `option`) and `fn`.
      oneOf:
        - type: object
          title: move
          description: Move the pointer.
          properties:
            type:
              const: move
            x:
              type: number
              minimum: 0
              description: A pixel in the screenshot, less than its width or height.
            'y':
              type: number
              minimum: 0
              description: A pixel in the screenshot, less than its width or height.
          required:
            - type
            - x
            - 'y'
          additionalProperties: false
        - type: object
          title: click
          description: Click at a point.
          properties:
            type:
              const: click
            x:
              type: number
              minimum: 0
              description: A pixel in the screenshot, less than its width or height.
            'y':
              type: number
              minimum: 0
              description: A pixel in the screenshot, less than its width or height.
            button:
              type: string
              enum:
                - left
                - right
                - middle
              default: left
            count:
              type: integer
              minimum: 1
              maximum: 5
              default: 1
              description: 2 is a double click.
            modifiers:
              type: array
              items:
                type: string
              description: Modifiers held during the click, like `["cmd"]`.
          required:
            - type
            - x
            - 'y'
          additionalProperties: false
        - type: object
          title: drag
          description: Press at one point, move to another and release.
          properties:
            type:
              const: drag
            fromX:
              type: number
              minimum: 0
              description: A pixel in the screenshot, less than its width or height.
            fromY:
              type: number
              minimum: 0
              description: A pixel in the screenshot, less than its width or height.
            toX:
              type: number
              minimum: 0
              description: A pixel in the screenshot, less than its width or height.
            toY:
              type: number
              minimum: 0
              description: A pixel in the screenshot, less than its width or height.
            button:
              type: string
              enum:
                - left
                - right
                - middle
              default: left
          required:
            - type
            - fromX
            - fromY
            - toX
            - toY
          additionalProperties: false
        - type: object
          title: scroll
          description: Scroll at a point.
          properties:
            type:
              const: scroll
            x:
              type: number
              minimum: 0
              description: A pixel in the screenshot, less than its width or height.
            'y':
              type: number
              minimum: 0
              description: A pixel in the screenshot, less than its width or height.
            dx:
              type: integer
              minimum: -1000
              maximum: 1000
              default: 0
              description: Lines to scroll sideways.
            dy:
              type: integer
              minimum: -1000
              maximum: 1000
              default: 0
              description: >-
                Lines to scroll; positive scrolls the content down. One of `dx`
                and `dy` must be non-zero.
          required:
            - type
            - x
            - 'y'
          additionalProperties: false
        - type: object
          title: type
          description: Type text.
          properties:
            type:
              const: type
            text:
              type: string
              minLength: 1
              description: Text to type, as typed characters, whatever the keyboard layout.
          required:
            - type
            - text
          additionalProperties: false
        - type: object
          title: key
          description: Press one key with optional modifiers, like `cmd+s`.
          properties:
            type:
              const: key
            key:
              type: string
              minLength: 1
              maxLength: 64
          required:
            - type
            - key
          additionalProperties: false
        - type: object
          title: wait
          description: Wait before the next action.
          properties:
            type:
              const: wait
            ms:
              type: integer
              minimum: 0
              maximum: 10000
          required:
            - type
            - ms
          additionalProperties: false
  headers:
    RequestId:
      description: This request's id, `req_…`. Quote it when asking for help.
      required: true
      schema:
        type: string
        pattern: ^req_
  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.