# Install the desktop app

The ShipVitals desktop app runs your projects' own checks (tests, a Docker smoke, a signing verification) on your computer and sends what they proved to your workspace. It also shows the same dashboards as the web. This guide gets it installed and running its first check, with or without an account.

The Mac app comes first. The Windows app is built but not published yet: its steps below apply when it's available, and until then **Download for Windows** doesn't show. On Windows the app says **This PC** wherever a Mac says **This Mac**, and its icon sits in the tray rather than the menu bar.

## Download it

1. Open `shipvitals.com/download` (**Desktop app** in the footer of every page).
2. The page leads with the button for your system: **Download for Mac (Apple silicon)** on a Mac, **Download for Windows** on a PC, each with its size and version beneath. The others are links under it: **Mac (Apple silicon)**, **Intel**, **Windows** and **Command line**. Until the Windows app is published, a PC sees "The desktop app runs on macOS 13 or later today; Windows is built but not published yet." with the two Mac downloads, each with its size and version, instead; so does a Linux machine until the command line is.
3. Press the one for your computer. An Intel Mac can't be told apart from an Apple silicon one, so on an Intel Mac press **Intel**.

Until the first signed build is published, the page says "The first signed build isn't published yet. It appears here the day it is." in place of the buttons.

On a phone the page says "On your phone? It installs on a computer." and offers **Send yourself the link**. Signed in, **Settings → Runners** has **Email me the link** on a phone, which sends it to your own address.

## Install on a Mac

The app needs macOS 13 or later.

1. Open the downloaded `.dmg` and drag **ShipVitals** into **Applications**.
2. Open ShipVitals from **Applications**. macOS asks once whether to open an app from the internet: choose **Open**. The app is signed and notarized by Nanner Tech LLC.

Keep it in **Applications**: the command line tool runs the copy inside the app (see [Install the command line tool](#install-the-command-line-tool)).

## Install on Windows

When available (see above).

1. Run the downloaded `ShipVitals-…-x64-setup.exe`. It installs for you alone, with no administrator prompt, and opens the app.
2. Closing the window leaves ShipVitals running in the tray. The first time, a notice says **ShipVitals is still running**. Open it again from the tray icon.

## Start without an account

The app opens on **This Mac**, with nobody signed in. It asks for no account and no invite code: your own login on the computer is what protects it. Checks run here and their results stay on this machine.

1. Under **Projects**, press **Link a folder**.
2. **Where's your code?** Press **Use ~/code** (or whichever folder it suggests), or **Choose a folder…** to pick the folder that holds your projects. ShipVitals reads manifests like `package.json` and `Dockerfile`, not your source.
3. **Found 3 projects in ~/code** lists each git repo with how many checks it proposes. Untick any you don't want, then press **Link 3 projects**.
4. A linked project says how many of its checks wait for review. Press **Review**, read the exact commands, press **Approve 2 checks**, then **Approve** in the system dialog. A check runs only once you've approved it.
5. Press **Run** on the project. Its run opens under **Runs**, each check with a row that ticks as it goes; choose a check to see its result and log. **Run all** on **Runs** starts every linked project's approved checks.

The other tabs are the machine's: **Doctor** lists the tools your checks need and how to fix a missing one, **Background** has **Open at login**, **Notifications** and **Pause**, and **Storage** shows what the results kept here take up. **Remove link** on a project forgets its folder; nothing in the folder changes.

These projects are the same ones `vitals link` and `vitals run` use with no account (see [The vitals command line](vitals-cli.md)). They aren't sent anywhere, and signing in later doesn't upload them: a workspace's projects are linked in its own first run, below.

## Sign in

Sign in to see your workspace in the app: its dashboards, connections and alerts, and each run recorded in ShipVitals. The app signs in through your browser, never in its own window. An account needs access to ShipVitals; during the private beta, see [Join the private beta](private-beta.md).

1. Press **Sign in** at the top of **This Mac**. The app shows **Sign in to ShipVitals** and a code like **WDJB-MJHT**. (**Continue without signing in** goes back to **This Mac**.)
2. Press **Open browser**. Your browser opens **Sign in on this device?** with the code filled in. (**Copy link** copies the address instead. On another device, open the address the app names and type the code.)
3. Approve it as in [Sign in on the desktop app or vitals](pair-a-device.md#approve-a-device). Leave **Run checks on this Mac for …** ticked so this computer can run checks for that workspace.
4. The app comes to the front by itself and starts setting up this computer.

A code lasts 10 minutes. If it runs out, the app says **Code expired.**: press **Get a new one**. If you cancel in the browser, it says "The sign-in was cancelled in the browser."

## Set up This Mac

After you sign in, the first run is six short steps under **Set up This Mac**; signing in was step 1, so the first one you see says "Step 2 of 6". Each starts when you press something, and if you quit halfway the app opens at the same step next time.

2. **Where's your code?** Press **Use ~/code** (or whichever folder it suggests), or **Choose a folder…** to pick the folder that holds your projects. ShipVitals reads manifests like `package.json` and `Dockerfile`, not your source, and folder paths never leave the computer.
3. **Found 3 of your projects** lists each repo whose git remote matches a project, with how many checks it proposes. A folder that matches nothing says **Not a project yet**; an owner or admin can press **New project** for it, and anyone can press **Ignore**. Projects with no folder here are listed under **Not on this Mac**. Press **Link 3 projects**.
4. **Review web's checks** shows the exact commands for one project: each check, its command, where it was found ("from Makefile:88") and what it needs. Read them. Some start unticked, such as "Off by default: it uses your local network". **Edit** changes a command. Press **Approve 2 checks**, then **Approve** in the system dialog. "2 more projects are ready when you are." says the rest wait for later.
5. **Running your first check** runs the quickest approved check, with one row that ticks as it goes. You can leave; it keeps going.
6. The result is the headline: "214 tests passed on web." with the check, commit and time, and **Now on** with its address on shipvitals.com. Before a project's first results are sent, ShipVitals shows **Before web's first upload**: read what goes, then press **Upload**. See [What leaves your machine](what-leaves-your-machine.md). Under **Next**, press **Run all 12 checks · about 38 min**, **Run in the background** or **Done**. Then the app asks two questions, one at a time:
   - "Open ShipVitals at login, so checks can run while the window is closed?": **Open at login** or **Not now**. macOS tells you it added a login item.
   - "Tell you when a run you started finishes, or a check needs you? The system asks next.": **Turn on notifications** or **Not now**. The system's own permission prompt appears only after you say yes.

The page says "Saved. You can change it in This Mac → Background."

If the first check couldn't run (a tool is missing), the headline says so and **See what's missing** opens **This Mac → Doctor**. Running checks from here on is in [Run checks](run-checks.md). Pairing more workspaces or machines is in [Pair a runner](pair-a-runner.md).

## The menu bar icon

ShipVitals keeps an icon in the menu bar (the tray on Windows) while it runs. Its tooltip says **ShipVitals · Calm**, **Running**, **Needs you**, **Paused** or **Offline**.

- Click it for the panel: "Nanner Tech · This Mac is ready", your linked projects with **Shippable**, **Not yet** or **Unproven** (or, when something needs you, that list instead, each with **Open**), and **Run all**, **Open ShipVitals**, **Settings** and **Pause**.
- Right-click it for **Pause Runner** (or **Resume Runner**), **Open ShipVitals**, **Check for Updates…** and **Quit ShipVitals**.

**This Mac → Background** turns **Open at login** and **Notifications** on or off later, and **Global shortcut** opens the panel from any app with `⌥⇧⌘V` (`Ctrl+Alt+Shift+V` on Windows).

## Updates

ShipVitals checks for updates by itself and downloads them quietly. It says nothing until one is ready.

1. When an update is ready, the panel shows **Update ready** with the new version and **Restart**.
2. Press **Restart**. If a check is running, the panel says "Restarts when this run finishes." and it restarts on its own then. The window comes back where it was.

To check now, choose **ShipVitals → Check for Updates…** (on Windows, **Help → Check for Updates…**, or the tray's menu). It says **ShipVitals is up to date.**, **An update is on its way.** or that the new version is ready, with **Restart** and **Later**.

When this version is too old for the service, the line above every page says "This version of ShipVitals is too old for the service. Update it to keep using it." with **Get the update**.

## Install the command line tool

On a Mac, the app can put `vitals` on your path, sharing the app's engine and approvals. It needs Node 24 or newer.

1. Choose **ShipVitals → Install Command Line Tool…**.
2. Read **Install the vitals command?** and press **Install**.
3. The app says where it put it: "Installed vitals at …". If that folder isn't on your `PATH`, it says which folder to add.

If ShipVitals isn't in **Applications**, it says **Move ShipVitals to Applications first.** Move it, open it from there, and choose the command again. On Windows, install `vitals` from npm instead (the **Command line** link on the download page). See [The vitals command line](vitals-cli.md).

## Sign out and quit

**Sign out:** open the **Account** menu (your avatar at the foot of the sidebar) and press **Sign out**. Signing out ends the app's sign-in and removes this computer's runner, so it stops running checks for your workspace. **Continue without signing in** on the next screen opens **This Mac** as it was before you signed in. An always-on machine asks first: see [Sign out on an always-on machine](pair-a-runner.md#sign-out-on-an-always-on-machine).

**Quit:** choose **ShipVitals → Quit ShipVitals** (`⌘Q`), or **Quit ShipVitals** in the icon's right-click menu. Closing the window doesn't quit: checks go on in the background. If checks are running, the app asks **Quit while checks are running?**: **Quit** stops the run, and the checks still running come back **Interrupted**.
