Skip to main content
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
Any other field is 400 unknown-field. In particular there is no env, ref or branch field: see 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). 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

  • 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.
  • 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.
  • 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:

Read and list tasks

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.

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.

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:
  • 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, 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:
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.