> ## Documentation Index
> Fetch the complete documentation index at: https://docs.outerlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run work on your own machines

> outerlayer runner takes work from your factory's queue and runs it on a machine you control.

A host is a machine you control that builds your factory's items. The
runner, `outerlayer runner`, is the process on that host. It 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. A host that uses the
built-in hooks writes no script at all.

## What happens to one build

```mermaid theme={"system"}
flowchart LR
    C[Claim] --> P[Provision] --> R[Command]
    R --> K["Host checks<br/>(exit 0 only)"] --> S[Sync] --> L[Cleanup]
    L --> V["Verdict<br/>(exit 0 only)"] --> E[Report] --> F[Release]
```

1. **Claim.** The runner claims an item someone asked a host to build, 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
   host. 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. **Host checks.** When the command exits 0, the runner runs the
   repository's [host checks](/reference/cli-runner#host-checks) and
   records their results.
5. **Sync.** The runner runs `outerlayer sync`, so the build's sessions
   upload.
6. **Cleanup.** The cleanup hook runs, however the command ended.
7. **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](#when-the-command-exits-0).
8. **Report.** If a report hook is set, it runs again with
   `OUTERLAYER_PHASE=end` and the outcome the release carries.
9. **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 host takes the
item again until a person asks for another build. To ask, run
`outerlayer work build --item <n>`, or select **Build again on a host** in
the item page's **Last build** block. The control appears only when the build
ended with no open pull request, and only for a member who can run
`outerlayer work build`.

A gateway too old to return a verdict is read as passing. A gateway that
refuses `incomplete` is sent the release again as `ok`, with the same
reason. A runner older than runner protocol 12 releases such a build `ok`.

## 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`](/reference/cli-runner#outerlayer-runner-init).

| Hooks | What it isolates | What the host needs |
| - | - | - |
| `builtin:vm` | Each build runs in a Firecracker microVM with its own kernel and no network device. It can run Docker when its recipe asks for it. | x86\_64 Linux, `/dev/kvm` for the runner's account, Docker Engine 26 or later, Docker Buildx 0.18 or later. |
| `builtin:container` | Each build runs in a container with no host files and no network but loopback. It shares the host's kernel. | Docker Engine 26 or later and Docker Buildx 0.18 or later, on Linux or WSL2. A Mac runs it in a Linux VM. |
| `builtin:process` | Nothing. The build runs as the runner's account and can read that account's files. | Any machine. `runner init` names it only with `--allow-process-builds` or, on a Mac, `--no-vm`. |
| Your own hooks | Whatever your provision hook sets up. | Executables you write. |

## Where to go next

* [Set up your first host](/set-up-a-host): build your first item.
* [Run a host as a service](/run-a-host-as-a-service): run it unattended,
  move it, upgrade it or remove it.
* [Container and microVM builds](/container-builds): what a build gets and
  can reach.
* [Destinations and secrets](/destinations-and-secrets): private registries
  and test APIs without handing a build the secret.
* [Write your own hooks](/write-your-own-hooks): your own provision, cleanup
  and report hooks.
* [Run builds on macOS](/run-builds-on-macos) and
  [Run builds on Windows](/run-builds-on-windows).
* [Build a repository's image from its devcontainer file](/build-image-from-devcontainer).
* [Troubleshoot builds](/troubleshoot-builds).
* [Security and limits](/build-security).


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