Skip to main content
A host is a machine you control. The runner, outerlayer runner, is the process on that host that builds your factory’s items. Together they are a self-hosted runner: the platform stays at app.outerlayer.ai, and each build and its code stay on your machine. Self-hosting the platform itself is a different thing, and is coming soon.
Setting up your first host? Start at Set up your first host. This page explains what a runner does with each build.
The runner takes items from two queues:
  • implement builds an item from its issue.
  • amend answers the review threads on an item’s open pull request.
For each item, the runner sets up a place to work, runs your agent, and cleans up. You decide two things on the host: how each build is isolated (the hooks) and which command starts your agent for each queue. With the built-in hooks, you write no script at all.

​
What happens to one build

One build, top to bottom: Claim, Provision, Command, Judge, Host checks, Sync, Cleanup, Verdict, Report and Release, each labelled with who runs it. The judge runs only for a judge check. A command that exits non-zero skips the judge, the host checks and the verdict, and is released failed. The verdict decides between ok and incomplete.One build, top to bottom: Claim, Provision, Command, Judge, Host checks, Sync, Cleanup, Verdict, Report and Release, each labelled with who runs it. The judge runs only for a judge check. A command that exits non-zero skips the judge, the host checks and the verdict, and is released failed. The verdict decides between ok and incomplete.
  1. Claim. The runner claims an item someone queued with outerlayer work build or Build on the Work page. An item added with outerlayer work build --local or Build locally is never queued for a runner. If a report hook is set, it runs now with OUTERLAYER_PHASE=start.
  2. Provision. The provision hook makes the working directory, such as a clone inside a container of its own.
  3. Command. Your command starts the agent in that directory. The runner renews its claim while the build runs. A claim it stops renewing expires after fifteen minutes.
  4. Judge. When the command exits 0 and the repository has a judge check, the runner starts a fresh agent to judge the criteria. See The judge stage.
  5. Host checks. When the command exits 0, the runner runs the repository’s host checks and records their results.
  6. Sync. The runner runs outerlayer sync, so the build’s sessions upload.
  7. Cleanup. The cleanup hook runs, however the command ended.
  8. Verdict. When the command exited 0, the runner reads the item’s checks to decide between ok and incomplete. See When the command exits 0.
  9. Report. If a report hook is set, it runs again with OUTERLAYER_PHASE=end and the outcome the release carries.
  10. Release. The runner releases the claim with the outcome.
An item another claim holds, such as a person’s own session, is refused. Linked sessions and pull requests never stop a build by themselves.

​
When the command exits 0

An exit of 0 says only that the agent’s session ended normally. So after the checks, the sync and the cleanup, the runner reads the item’s evidence verdict, the evaluation that GET /v1/work-items/{workItemId} returns. It reads it before the report hook, so that hook sees the outcome the release carries.
  • The item has a pull request and passes, or waits only on a person’s review: the release is ok.
  • The item has no pull request: a build that opens no pull request is released incomplete, saying so, whatever the checks say. A runner build opens its pull request with outerlayer work open-pr.
  • A check failed or has no result: the release is incomplete. Its reason names each such check and marks the ones with no result, for example checks not passing: Migration must run: Migrations ran against a local database (no result). While the build held the claim, a required check with nothing recorded was only waiting. The build has ended, so the runner counts it as missing.
  • The item has no verdict yet, or still waits on session links to be confirmed: the release is incomplete, and its reason says so.
  • The read fails: the release is incomplete, and its reason says the item’s status could not be read.
The verdict is computed again after the build’s sessions and checks arrive, so it can lag them. A verdict that is not passing is read again every 30 seconds, for up to 5 minutes. The runner decides on the last read. A passing verdict is believed at once. incomplete uses up the build request, as ok does. No runner takes the item again until a person asks for another build. To ask, run outerlayer work build --item <n>, or select Rerun on a host in the item page’s Last build block. The control appears when the build ended with no open pull request. It also appears when the build ended with one whose review waits on an agent. Then the rerun starts an amend. It appears only for a member who can run outerlayer work build. With an older gateway or runner, the verdict can be skipped; see Mixed versions.

​
Give a build instructions

A person starting a build often knows something the issue does not say. Instructions are text for the agent that runs that one build. It reads them as guidance from the person who asked. They never change which issue is built or which checks run, and the issue’s criteria win if the two disagree. The agent names any conflict, and what it did about it, in the pull request description. You can give instructions, up to 2000 characters, in three places:
  • Add work. Select Build on an issue. A step opens with an Instructions for the agent field. Build locally has no field, because you build that item in your own session.
  • Rerun. Select Rerun on a host in the item page’s Last build block. A dialog opens with an empty field, and the rerun starts when you select Rerun. When the item has an open pull request, the rerun is an amend, and the dialog says it does not use instructions.
  • CLI. Pass --instructions <text> to outerlayer work build. See the CLI reference.
Instructions belong to one build request. A rerun without instructions gives its build none. They cannot be edited after the request is recorded. An amend, which answers review notes on an open pull request, does not read them. The item page shows them on the Activity tab, in the entry for the request, beside who asked and when. The /build skill that outerlayer init writes reads them, so a repository whose skill is older needs outerlayer init --update.

​
Choose how a build is isolated

The hooks you name decide what a build can reach on the host. outerlayer runner init picks the strongest isolation the machine supports: builtin:vm on x86_64 Linux whose account can open /dev/kvm, else builtin:container. The full rule is in outerlayer runner init.

​
Where to go next