Skip to content
Guides

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

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

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."