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
- Open
shipvitals.com/download(Desktop app in the footer of every page). - 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.
- 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.
- Open the downloaded
.dmgand drag ShipVitals into Applications. - 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 on Windows
When available (see above).
- Run the downloaded
ShipVitals-…-x64-setup.exe. It installs for you alone, with no administrator prompt, and opens the app. - 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.
- Under Projects, press Link a folder.
- 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.jsonandDockerfile, not your source. - 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.
- 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.
- 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). 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.
- 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.)
- 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.)
- Approve it as in Sign in on the desktop app or vitals. Leave Run checks on this Mac for … ticked so this computer can run checks for that workspace.
- 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.
- 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.jsonandDockerfile, not your source, and folder paths never leave the computer. - 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.
- 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.
- Running your first check runs the quickest approved check, with one row that ticks as it goes. You can leave; it keeps going.
- 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. 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. Pairing more workspaces or machines is in Pair a runner.
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.
- When an update is ready, the panel shows Update ready with the new version and Restart.
- 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.
- Choose ShipVitals → Install Command Line Tool….
- Read Install the vitals command? and press Install.
- 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.
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.
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.