hub-runner
Runs a hub workspace's Mac bots on this Mac. It runs under launchd, so no app has to be open.
npm i -g hub-runner --min-release-age=0
hub-runner login
hub-runner start
login signs in with Vercel, asks which workspace this Mac runs bots for, and stores a session of the runner's own in ~/.hub/local/credentials.json. The Vercel token is revoked once the hub has the session.
| Command | What it does |
|---|---|
hub-runner start [--take-over] | Starts the runner under launchd (~/Library/LaunchAgents/dev.hub.runner.plist). It starts again at every login and is not restarted after a crash: run start again. --take-over claims the Mac slot from another Mac. |
hub-runner stop | Stops it. |
hub-runner restart | Lets the open turns finish, then starts it again. |
hub-runner status | The runner's state, pid, version, bots, and whether launchd has it loaded. Exits 1 when it isn't running. |
hub-runner logs [-f] | The log, ~/.hub/local/runner.log. |
hub-runner logout | Stops it and deletes the stored session. |
Update
npm i -g hub-runner@latest --min-release-age=0 && hub-runner restart
restart lets the turns open now finish, so no bot is cut off.
--min-release-age=0 lets the newest release install when your npm config holds packages back for a few days (min-release-age). It applies to this one install, and hub-runner has no dependencies, so nothing else skips the wait.
Notes
- Node 24 or later, and
pnpmon your PATH when you runstart: the runner uses both to set the bots up. - The hub is
https://hosted-hub.playground-vercel.tools; setHUB_URLwhen you runloginfor another one. - The HubHosted app only shows the runner's state. Quitting, signing out of or replacing the app doesn't touch the runner.
- If the runner doesn't start,
hub-runner statusandhub-runner logssay why.