# Pair a runner

A runner is a machine paired to a workspace so it can run checks there: your laptop with the ShipVitals app, or a headless box with `vitals`. One approval in the browser signs the machine in and pairs it. This guide covers pairing, the machine's role, who may start runs on it, and removing it again.

Who can pair: owners and admins, and editors (for the projects they edit). A viewer can sign in to the app or `vitals`, but the machine doesn't run checks for them.

## Pair from the desktop app

1. Install the app and sign in as in [Install the desktop app](install-the-desktop-app.md#sign-in).
2. On the approval page, leave **Run checks on this Mac for …** ticked. Press **Change** to pick another workspace. The browser side is in [Sign in on the desktop app or vitals](pair-a-device.md#approve-a-device).
3. Press **Sign in on this device**. The page says "MacBook Pro is signed in, and can run checks for Nanner Tech."
4. The app sets up the machine: **Where's your code?** and the rest of the first run.

If you untick the box, the app is signed in but runs no checks.

## Pair with vitals

1. Run `vitals login`. It prints **Sign in to ShipVitals**, an address and a code like **WDJB-MJHT**, and in a terminal a QR code to scan with your phone.
2. Open the address (or scan the code) and approve it as in [Sign in on the desktop app or vitals](pair-a-device.md#approve-a-device), with **Run checks on this machine for …** ticked (**Run checks on this Mac for …** on a Mac).
3. `vitals` says "Signed in. Studio Mac mini runs checks for Nanner Tech."

If the code runs out it says "Code expired. Get a new one: run vitals login again." More commands are in [The vitals command line](vitals-cli.md).

## Pair a machine with no browser

For a Mac mini over SSH, an image or a CI-managed box, issue a runner token instead. Owners, admins and editors can issue one.

1. Open **Settings** in the sidebar, then **Runners**.
2. Press **Issue a token**.
3. Under **Machine name**, type what it's called here, like "Studio Mac mini". **It's always on** is ticked, for a machine that should never be offline: untick it for one that sleeps, like a laptop.
4. Press **Issue token**. ShipVitals may ask you to **Confirm it's you** first.
5. "Copy it now: you won't see this token again." Press **Copy token**. **On the machine** shows the command to run.
6. On the machine, run `vitals login --token -` and paste the token at **Runner token:**. What you type isn't shown. In a script, pipe it in: `vitals login --token - < token.txt`.
7. `vitals` says "Studio Mac mini runs checks for Nanner Tech." and that the machine runs what the web sends it.
8. Back in the browser, press **I've stored it**. The machine is in the list.

Don't put the token after `--token` on the command line: it stays in your shell history. A token that wasn't accepted says "That token wasn't accepted. Issue a new one in Settings → Runners."

## Laptop or always on

Each machine has a role:

- **Laptop**: "Runs while the app is open and conditions allow, and waits for power unless you start a run." When it sleeps, it's **Asleep**, which is normal.
- **Always on**: "Runs whenever scheduled. Offline for 30 minutes becomes an incident." The **Runner offline** rule on [Alerts](alerts.md#rules) raises it.

To change it in the desktop app, open **This Mac → Background** and choose **Laptop** or **Always on** under **This machine is a**. The page says **Saved.** A token-paired machine is always on when **It's always on** was ticked.

## Let editors start runs

By default only the person who paired a machine starts runs on it from the web. Schedules run either way.

1. Open **Settings → Runners** and press **Details** on the machine.
2. Tick **Let editors of these projects start runs**. The page says "Editors of its projects can start runs on it."

Only the machine's owner or an admin can change this; others see "Only its owner or an admin can change it."

## When the plan's machines are all paired

Each plan covers a number of machines, laptops and always-on alike. When they're all paired, the approval page and **Issue a runner token** say so, for example "Free covers one machine. Studio Mac mini is paired."

- Choose the machine to replace under **Machine to replace** (or tick **Replace it** on the approval page). "Studio Mac mini stops running checks when the token is issued."
- Or press **See plans**.
- If the paired machines are other people's, the page says "Your plan's machines are all paired, by other people." Ask an admin to free one.

`vitals login` signs in without pairing in that case and says "Your plan's machines are all paired. Replace one in Settings → Runners, then sign in again."

## See the workspace's runners

Open **Settings → Runners**. Owners and admins see every runner; an editor sees their own and the ones that run checks for their projects.

Each row shows the machine's name, whose it is (**Yours** or "Ana's"), its system, **Laptop** or **Always on**, its version ("ShipVitals 0.5.0"), "Can run: Node, Docker, Xcode", "Projects: …" and "Last result: Passed 5 min ago". Its state is one of:

- **Ready**
- **Running 3 checks**
- **Paused until 14:00** or **Paused until resumed**
- **Asleep · last seen 8:14**
- **Offline since 02:10**
- **Waiting for its first check-in**
- **Needs an update to run checks**: update the app or `vitals` on that machine.

**Details** opens the machine: when it was paired, **What it can run** (Doctor's last report: tool names and versions only), **Name** with **Rename**, and **Let editors of these projects start runs**.

With no runner yet, the page says "No machine runs checks here yet" with **Download for Mac** (or **Get the app**) and **Issue a token**.

### Revoke a runner

1. Press **Details** on it, then **Revoke**.
2. Read **Revoke Studio Mac mini?** ("It stops running checks at once, and the machine says so at its next check-in.") and press **Revoke**.
3. The page says "Studio Mac mini is revoked." It moves to **Revoked in the last 7 days**.

Revoking a runner here leaves the person's sign-in on that machine working. In the desktop app on that machine, **This Mac** says "This Mac was removed by Ana on Nov 5." with **Pair again** and **Quit**. Pairing again makes a new runner.

## Your devices

**Account settings → Devices** lists every desktop app and `vitals` signed in as you, and **Runners on their own**: machines you paired that run checks with nobody signed in, such as one paired with a token. **Revoke** there signs a device out and stops its checks at once. See [Sign in on the desktop app or vitals](pair-a-device.md#see-and-revoke-your-devices).

## Sign out on an always-on machine

Signing out of the app normally removes the machine's runner as well. An always-on machine may be serving other people, so the app asks first.

1. Open the **Account** menu and press **Sign out**.
2. The app asks **Sign out of Studio Mac mini?** "It's an always-on runner. Keep it running checks, or remove it too?"
3. Press **Sign out and keep the runner** to keep it running checks, **Sign out and remove it** to remove it, or **Cancel**.

With `vitals`, `vitals logout --keep-runner` keeps the runner and `vitals logout` removes it. Either says "Signed out. Local results stay on this machine."
