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

# Tasks

> Fire-and-forget work: clone a repository, run a command, keep the artifacts.

A task is fire-and-forget macOS work. A Mac slot clones `repo`, runs `command` (or an `agent` program) in the clone, uploads the artifacts the task promised, and reports the outcome. The task bills from start to end, at most its `timeoutMs`. Time spent queued is free.

Tasks clone public repositories only, for now: the clone URL is stored and shown on the task, so it may not carry a token. To build private code, use a sandbox and send the code in (see the setup guide at `https://api.offstage.cloud/SKILL.md`).

### Create a task

`POST /v1/tasks`

| Field | Type | |
| - | - | - |
| `repo` | string, required | The `https://` clone URL of a public repository, with no credentials in it, at most 2048 characters |
| `kind` | `build` \| `test` \| `screenshot` \| `agent`, required | |
| `command` | string | The shell command line to run in the clone, at most 64 KiB. Required for every kind except `agent`, which must not have one |
| `agent` | string | Only for `kind: "agent"`: the agent program the fleet runs inside the slot |
| `artifacts` | string\[] | Up to 32 distinct file names in the clone's root that the task promises to upload, each at most 100 MiB; `[]` by default. Nothing else is kept. See the [artifact name rules](https://offstage.cloud/docs/api/tasks.md#artifacts). A bad name is refused at create with 400 `bad-artifact-name` |
| `session` | `headless` \| `gui` | Defaults by kind: `screenshot` runs `gui`, and `build`, `test` and `agent` run `headless` |
| `timeoutMs` | integer | Wall-clock cap on the whole task, clone included. 30 min by default, 24 h at most |
| `record` | boolean | A `gui` task is recorded unless this is `false`: its screen every 5 s and its log, played back at its `replayUrl`. See [Recordings](https://offstage.cloud/docs/api/recordings.md) |
| `secrets` | string\[] | Select 1–16 existing team secret names; values are never part of the task spec |
| `queueTimeoutMs` | integer | How long the task may wait for a free slot. 15 min by default, 24 h at most. A task that has waited this long fails, with an outcome event whose `data` starts `no-capacity:`. Time it spends behind its own team's earlier tasks, while the team has its 4 tasks running, does not count: the wait counts from the last moment the team held it back |

```bash theme={null}
curl -s -X POST https://api.offstage.cloud/v1/tasks \
  -H "authorization: Bearer $OFFSTAGE_API_KEY" -H 'content-type: application/json' \
  -H "idempotency-key: $(uuidgen)" \
  -d '{"repo": "https://github.com/org/app", "kind": "build", "command": "set -o pipefail; swift build 2>&1 | tee build.log", "artifacts": ["build.log"], "timeoutMs": 1800000}'
```

Any other field is 400 `unknown-field`. In particular there is no `env`, `ref` or `branch` field: see [What a task runs](https://offstage.cloud/docs/api/tasks.md#what-a-task-runs).

The answer is `201` with the task in state `queued`. The task's worst case (`timeoutMs` at \$1.10/h) is reserved against the available credit and the budget until it ends (see [Billing](https://offstage.cloud/docs/api/billing.md)). Refusals: 400 (validation), 402 (billing), 409 `no-capacity` when Macs are online but none of their slots takes this `session`, 429 `task-backlog` when the team already has 16 tasks queued, and 429 `queue-full` (with `Retry-After`) when the plane already has 500 queued across every team. If no Mac is online at all, the task queues and `queueTimeoutMs` decides.

### What a task runs

1. The Mac clones `repo` into a fresh directory with `git clone --depth 1`: the default branch, with no credentials and no prompts. A failed clone fails the task.
2. It runs `command` (or, for `kind: "agent"`, `agent`) as `zsh -lc "<command>"`, with the clone as the working directory and `CI=1` in the environment. Both output streams become `log` events, one per line, starting with the clone's own output.
3. It uploads the promised artifacts from the clone's root. If the command exited 0, every promised artifact must exist, or the task fails saying which one is missing. A failed or timed-out task uploads the ones that exist, so a failed build still returns its log.
4. It wipes the slot's account. The task's files, processes and caches never reach the next task, so every task starts cold.

There is no `ref`, `branch` or `env` field. Put those in the command:

* **Another branch, tag or commit**: `git fetch --depth 1 origin <ref> && git checkout FETCH_HEAD && swift build`.
* **Environment variables**: `FOO=bar swift build`, or `export FOO=bar; …`. A task command is stored and shown on the task, so never put a secret in it.

`kind` labels the task and picks its default `session`. `screenshot` defaults to `gui`, because a screenshot needs a screen. `build`, `test` and `agent` default to `headless`. GUI tasks require a ready desktop slot. Use `headless` for work that needs no screen.

### The task object

```json theme={null}
{
  "id": "task_…",
  "spec": { "repo": "…", "kind": "build", "command": "…", "artifacts": ["build.log"], "session": "headless", "timeoutMs": 1800000, "queueTimeoutMs": 900000 },
  "state": "running",
  "createdAt": 1793000000000,
  "boxId": "box_…", "slot": 2,
  "startedAt": 1793000001000,
  "attempts": 0,
  "requeued": false,
  "events": [{ "at": 1793000000500, "type": "claimed", "data": "box_… slot 2" }, { "at": 1793000001000, "type": "started" }],
  "costUsd": 0.02,
  "createdBy": { "keyName": "ci" },
  "exitCode": null,
  "droppedLogLines": 0,
  "failureReason": null
}
```

* `state`: `queued → claimed → running → succeeded | failed | timed_out`, or `cancelled` from any state before those.
* `replayUrl`, on a recorded `gui` task only: the console page that plays its screen and log back. See [Recordings](https://offstage.cloud/docs/api/recordings.md).
* `events` tells the whole story in order. The types are `claimed`, `started`, `log` (one line of output in `data`), `artifact` (a name in `data`), and the outcome event `succeeded`, `failed`, `timed_out` or `cancelled`, whose `data` gives the reason (for example `exit 1`, or `cancelled by key ci`).
* The log keeps the last 500 lines, because a build's error is at its end. When lines were dropped, `droppedLogLines` counts them and the first `log` event reads `… N earlier log lines not kept`. A line is cut at 16,384 characters.
* `exitCode` is the command's exit status once the Mac reports it, and `null` before then or when there was none (timed out, cancelled, lost).
* `failureReason` says why a task ended `failed` or `timed_out`, and is `null` in every other state. See [Why a task failed](https://offstage.cloud/docs/api/tasks.md#why-a-task-failed).
* `boxId` and `slot` say which Mac and slot ran it. Fields that do not apply yet (`boxId`, `slot`, `startedAt`, `endedAt`, `runtimeSeconds`) are absent, not null.
* `costUsd` is accrued so far while the task runs, and final once it ends. A task the fleet itself lost is not billed.
* `createdBy` is `{"keyName"}` for a key or `{"email"}` for the console.

Lifecycle rules:

* At most 4 of a team's tasks are claimed or running at once, and at most 16 wait `queued` (429 `task-backlog` past that). Its fifth waits for one of its first four to end, however many slots are free.
* A free slot goes to the team with the fewest tasks claimed or running, then to the team served longest ago, and then to that team's oldest task. One team's backlog does not hold other teams behind it.
* The Mac enforces `timeoutMs`. It kills the work and reports `timed_out`.
* On failure and on timeout, the task still uploads whatever promised artifacts exist, so a failed test run still returns its log.
* A task that a slot claimed but never started goes back to `queued`, up to 3 attempts in all, with `requeued: true`.
* A task no slot takes within its `queueTimeoutMs` fails with `failureReason: "no-capacity"`. It never ran, so it costs nothing. Waiting behind the team's own earlier tasks is not waiting for a slot, so that time does not count against `queueTimeoutMs`.
* A task that started is never run twice. If its Mac goes silent it fails, and if it runs 2 minutes past its timeout with no report it becomes `timed_out`.

### Why a task failed

`failureReason` is what CI should branch on, never the event text:

| `failureReason` | State | Meaning | Billed |
| - | - | - | - |
| `null` | any but `failed` and `timed_out` | It succeeded, or is still going, or was cancelled | |
| `exit` | `failed` | The command exited non-zero (`exitCode` says how). The build or tests are broken | Yes |
| `setup` | `failed` | The Mac could not get to running the command (for example, the clone failed), or the command exited 0 without a promised artifact, or with one the plane would not store (see [Artifacts](https://offstage.cloud/docs/api/tasks.md#artifacts)) | Yes |
| `timeout` | `timed_out` | It ran past `timeoutMs` | Yes |
| `no-capacity` | `failed` | No Mac took it within `queueTimeoutMs`. It never ran | No |
| `box-lost`, `plane-restart`, `never-started` | `failed` | The fleet lost it: its Mac went silent, the service restarted while it ran and its Mac did not come back with it (rare: a restart carries running tasks through), or no Mac managed to start it in 3 attempts. Submit it again | No |

### Read and list tasks

| Call | Answer |
| - | - |
| `GET /v1/tasks/:id` | The task |
| `GET /v1/tasks/:id?wait=<seconds>` | The task, once it ends or after `wait` seconds, whichever is first. `wait` may be 0 to 60, but the server never holds more than 50 s |
| `GET /v1/tasks?state=&kind=&limit=&cursor=` | `{"tasks": [...], "nextCursor"}`, newest first. Each item is the task without `events`; `GET /v1/tasks/:id` has them. `state` is one of the seven states, `kind` one of the four kinds or `runner` (GitHub Actions jobs, see [GitHub Actions](https://offstage.cloud/docs/api/tasks.md#github-actions)) |

An ended task is kept for 30 days, or less when the team's ended tasks pass 4 MiB of records, or every team's together pass 32 MiB. The oldest go first. After that `GET /v1/tasks/:id` answers 404 `not-found`, and the list no longer shows it.

To wait for a task, call `GET /v1/tasks/:id?wait=50` in a loop until `state` is `succeeded`, `failed`, `timed_out` or `cancelled`. Each call returns as soon as the task ends, so this is about one request a minute rather than a poll loop. No hold passes 50 s, so it stays under the 60 s idle timeout of most proxies and load balancers.

```bash theme={null}
curl -s "https://api.offstage.cloud/v1/tasks/task_…?wait=50" -H "authorization: Bearer $OFFSTAGE_API_KEY"
```

### Cancel a task

`POST /v1/tasks/:id/cancel` (no body) ends the task wherever it is, and answers with it `cancelled`.

* A `queued` task never runs and costs nothing.
* A `claimed` or `running` task is stopped on its Mac within about 15 s, and is billed up to the cancel. Artifacts it had not uploaded are lost.
* A task that had already ended is 409 `already-ended`.

```bash theme={null}
curl -s -X POST https://api.offstage.cloud/v1/tasks/task_…/cancel -H "authorization: Bearer $OFFSTAGE_API_KEY"
```

### Fleet capacity

`GET /v1/capacity` (key or session) reports current readiness. `tasks` and `sandboxes` contain ready-now counts for `headless` and `gui`. `availability.tasks` and `availability.sandboxes` break each session down into `ready`, `busy`, `resetting` and `unavailable`. A report older than 45 seconds cannot make work look ready. `queued.sandboxes` counts this team's pending sandboxes by session; `boxesOnline` counts Macs heard from recently.

Busy or resetting capacity can queue work. `409 no-capacity` means no current report accepts that kind of work. A temporary operator access pause can also refuse GUI work with `gui-paused`. Capability counts overlap: headless and GUI counts are not additive.

### GitHub Actions

For a repository in a GitHub organization, an offstage Mac can be the job's runner itself: no script, and no offstage key in the repository.

1. In the offstage console, open **CI** and click **Connect GitHub**. It takes someone who owns both the offstage team and the GitHub organization: GitHub asks you to sign in to the offstage app, and to install it on the organization if it isn't there yet. The app asks for the organization's self-hosted runners, its members (to check you are an owner) and repository metadata, nothing else.
2. In the workflow, change the job's `runs-on`:

```yaml theme={null}
jobs:
  test:
    runs-on: offstage-macos
    steps:
      - uses: actions/checkout@v4
      - run: swift test
```

* `runs-on: offstage-macos-gui` runs jobs in a logged-in desktop slot. Use `offstage-macos` for headless jobs.
* The job may also list `self-hosted`, `macos` and `arm64`. Any other label (`macos-15`, `xcode-16`, …) makes it not offstage's job, and it waits for some other runner. The Mac's runner carries exactly the job's labels, so if a job lists `[self-hosted, macos]` too, another job in that organization asking only for `[self-hosted, macos]` could land on an offstage Mac. `runs-on: offstage-macos` alone avoids that.
* Each job gets a fresh Mac account that runs GitHub's own runner program for that one job, then is wiped. A job runs up to 60 minutes.
* Billed like a task once GitHub hands the Mac its job: per second from when the Mac started, $1.10/h. GitHub gives a job to any idle runner whose labels fit, so a Mac can end up with no job (another runner took it): that Mac costs nothing and is stopped. While it runs, a job reserves an hour ($1.10) under [the reservation rule](https://offstage.cloud/docs/api/billing.md#the-reservation-rule), like any other work.
* Private repositories work: `actions/checkout` uses the job's own token.
* Organization repositories only, for now. An installation on a personal GitHub account is shown as unsupported, and its jobs don't run.
* A job the team can't run (insufficient credit, a budget reached, paused GUI access, or no Mac that takes it) gets no runner. It stays "Waiting for a runner" on GitHub, and the console's CI page says why. Fix that, then re-run the job.
* Each job shows on the console's CI page, and in `GET /v1/tasks?kind=runner`, as a task of kind `runner` with a link to the job on GitHub. No client creates one: `POST /v1/tasks` refuses `kind: "runner"`.

A `runner` task's spec has no `command` and no artifacts, its `createdBy` is `{"keyName": "GitHub Actions"}`, and it carries `github`:

```json theme={null}
"github": { "org": "acme", "repo": "acme/app", "workflowJobId": 7001, "runId": 900001, "runUrl": "https://github.com/acme/app/actions/runs/900001/job/7001", "jobName": "test", "workflowName": "CI", "jobStartedAt": 1761868800000, "runnerName": "offstage-task_…", "conclusion": "success" }
```

`runnerName` appears once GitHub says a runner picked the job up, and `conclusion` (GitHub's verdict: `success`, `failure`, `cancelled`, …) once the job completed. The task's own `state` is the Mac's side: `succeeded` means GitHub's runner exited cleanly, whatever the job's verdict. An ephemeral runner takes whichever waiting job of its organization its labels cover, which need not be the one it was registered for: `jobStartedAt` is set when GitHub says this task's runner took a job, and from then on `github` describes that job. A runner task is billed only once `jobStartedAt` is set (its `costUsd` is 0 until then), and one left with no job it could take is cancelled, unbilled.

Before submitting a workflow, call `GET /v1/github/installations` with the team API key. It returns `configured`, `appSlug`, `connectUrl`, `lastRefusal` and this team's linked `installations`. Each installation includes `account`, `accountType`, `supported`, `repositorySelection`, `repositories`, `suspended` and `linkedAt`. `repositories` lists accessible full names; it is null for a suspended installation. If the organization or repository is absent, open `connectUrl` and have an owner connect it first. GitHub cannot deliver job events for an installation that has never been connected, so offstage cannot cancel or explain that job from a webhook it never receives. Connection changes still require an owner in the console. A GitHub lookup failure returns 502 rather than an incomplete access list.

### Artifacts

An artifact name is a plain file name in the clone's root:

* 1 to 128 characters: letters, digits, `.`, `_` and `-`;
* it starts with a letter or digit, and does not contain `..`;
* it does not end in `.meta.json`;
* it has no `/`, so copy nested outputs to the top of the clone first, for example `cp .build/debug/app.log app.log`.

A task promises at most 32. An artifact may not be empty.

Stored artifacts have shares: 256 MiB for all of one task's together, 512 MiB for all of a team's, and a ceiling for every team together. The plane refuses an upload past any of them with 413 `artifact-quota`, which the Mac sees, not you. If the command exited 0, the task then fails with `failureReason: "setup"`, and its outcome event names the artifact and quotes the refusal. A task that had already failed keeps its own reason, and the refused artifact is simply not there.

Artifacts are deleted 7 days after their task ends, which frees the team's share.

`GET /v1/tasks/:id/artifacts/:name` returns the artifact's raw bytes as a download, with the content type it was uploaded with. The answer is 404 `not-found` until the Mac uploads it, and for a name the task did not promise. After the 7 days it is 404 `not-found` with a message saying the artifact was deleted.

```bash theme={null}
curl -s https://api.offstage.cloud/v1/tasks/task_…/artifacts/build.log -H "authorization: Bearer $OFFSTAGE_API_KEY" -o build.log
```


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