# Runners

Make any machine with bit a runner for your account or one repository, route jobs to it with labels, and drain or remove it.

A runner is a machine that takes CI jobs from Lorx and runs them. It uses the same engine as `bit run`. Any computer with bit can be one: your laptop, a server, a machine with a GPU.

## Register a runner

1. Open **Settings → Runners** (for your account), or a repository's **Settings → Runners** (for that repository only), and choose **Register a runner**. It asks for your password, then shows a one-time token that works for an hour.
2. On the machine, with bit installed:

```sh
bit runner register --token lorx_rr_…
bit runner run
```

The token is traded for the runner's own credential, kept in a file only you can read. `bit runner run` then takes jobs until you stop it:
- Ctrl-C once finishes the job in hand and stops;
- twice stops at once, and the job goes back in the queue.

Check it with `bit runner status`.

| Option | What it does |
|---|---|
| `--name <name>` | What to call it (the machine's name by default) |
| `--labels a,b` | Labels it offers. Its operating system and architecture are always added, such as `linux` and `x64`. |
| `bit runner run --once` | Run one job, then stop |
| `bit runner run --idle-exit 15m` | Stop after that long with no job |

## Which jobs a runner takes

- A runner registered on your account takes jobs from every repository you own. One registered on a repository takes only that repository's jobs. A runner never sees another account's jobs.
- A job with `runner: gpu` goes only to a runner with the label `gpu`. A job with no `runner` goes to any of your runners.

The Runners page shows each runner's state (idle, busy, draining or offline), and the routing its labels make.

## Drain or remove a runner

- **Drain** lets it finish its job and take no more. **Resume** undoes it.
- **Remove** stops its credential working at once, and a job it was running goes back in the queue for another runner.

## Keep runners to code you trust

A job runs as the user running `bit runner run`, and can read what that user can. Run runners under a dedicated user, on machines that hold nothing else you care about, and keep them to repositories whose code you trust.