Docs › Getting started

Getting started

Sparehand sends your heavy work (test suites, builds, local AI models) from the Mac you work on to the other computers you own, so your Mac stays fast. The Mac you work on is the hub; the others are workers. Your coding agent can hand its checks over by itself.

You got Sparehand as a disk image (a .dmg file) straight from its author, not from a store, so a few first steps are different from a normal download. This page is the first ten minutes.

What you need

• A Mac with macOS 14 or newer. The app brings everything else it needs (Node.js included); git comes with Apple's free command-line developer tools, which Setup offers to install.
• A second machine for jobs: a Mac with Remote Login turned on, a Linux machine with ssh, rsync, git and bash, or a Windows PC with WSL2. Without one, Sparehand runs everything on this Mac and tells you so, and offers to rent one by the minute: a cloud machine that runs only while a job needs it, with a spend limit.

1. Install

1. Open the disk image and drag Sparehand to your Applications folder. Then eject the disk image. Open the app from Applications, never from the disk image or Downloads: the sparehand command is a link into the app, so it would break when the app moves (the app refuses to install it from anywhere else).
2. macOS says it can't verify the app. This build isn't registered with Apple yet, so the first time you open it macOS shows "Apple could not verify 'Sparehand' is free of malware" with only Move to Trash and Done. Click Done, then open System Settings → Privacy & Security, scroll down to Security, and click Open Anyway next to Sparehand (it is offered for about an hour after that first try; macOS asks for your password or fingerprint). Sparehand opens.

Or skip the whole dance before the first launch, in Terminal:

bash xattr -dr com.apple.quarantine /Applications/Sparehand.app

1. The Keychain asks. Sparehand keeps its licence in your Keychain. When macOS asks whether Sparehand may use it, click Always Allow. (Deny doesn't lock you out: Sparehand runs as an unverified trial with a note in its menu, and asks once more a few minutes later.)

2. Setup

Sparehand lives in the menu bar (the icon with three bars). Setup opens by itself the first time and goes through its checklist; each step has a button:

• The sparehand command, installed into ~/.local/bin for Terminal and your coding agents.
• Apple's developer tools, if git isn't on this Mac yet (macOS installs them in a few minutes).
• An SSH key for this Mac, which is how the hub logs in to your workers. Only this Mac holds it.
• This Mac's name, as your workers and the dashboard will show it.
• Claude Code (optional): lets Claude Code hand its tests, typechecks and lint to your workers by itself. It can be turned on later in Settings → AI Tools.
• Open at login (optional).
• Your first worker: see below.

3. Add a worker

In the menu, Add a machine → Pair with a code. Pick what the other machine is (Mac, Linux, Windows PC, or a server), and run the one command it shows on that machine: in Terminal on a Mac or Linux, in PowerShell as administrator on Windows. That command installs what's missing, lets this Mac's key in, and shows a short code. Both screens show the same code; confirm on the hub and the machine appears in the menu with its CPU, memory and job slots.

The long way, with every command (also for servers): Adding a worker.

4. Run something

In Terminal, in a project folder that is a git checkout:

sparehand run npm test

Sparehand copies the checkout to the least busy worker that has room, runs the command there, streams the output back and returns the command's exit code. A first run installs the project's dependencies on the worker; later runs reuse them. If no worker is free, at a terminal it runs the command on this Mac itself and says so (no worker free: running on this Mac); a script, a pipe or an agent's hook gets exit 255 instead, which means "run it locally", so they decide. sparehand status shows every machine's load; the dashboard (in the menu) shows jobs, activity and history.

When the job ends, a last line says where its time went and whether it finished sooner than this Mac would have. This Mac's time is only ever a measured one: sparehand run --here npm test runs the command here once so there is something to compare with (Did the worker finish sooner?).

Claude Code: with Settings → AI Tools turned on, a hook rewrites the tests, typechecks and lint that Claude Code runs to go to your workers, and they run here when none is free. Builds, installs, git and dev servers stay on this Mac. The hook tells Claude Code about Sparehand once; nothing in your projects changes.

5. Your licence

The app comes with a 14-day free trial. Buying isn't open yet: you get an invite code instead.

A code came with the disk image? Open Settings → Licence, paste it into the Licence key or invite code box and click Activate. That's all.

No code yet?

1. Open Settings → Licence and click Copy next to This Mac's ID.
2. Send that ID back to whoever gave you Sparehand ([email protected]). The code is then made for this Mac alone; a new Mac has a new ID, so ask for another code.
3. Paste the code you get back into the Licence key or invite code box in the same tab and click Activate.

Updates and problems

• This build doesn't update itself. When there is a new version you get a new disk image; install it over the old one the same way (drag to Applications, replace). Your machines and settings are kept.
• Something isn't working? Settings → Advanced → Diagnostics → Copy puts the versions and the state of every machine on the clipboard (no keys or passwords). Paste it into an e-mail to [email protected] with what you tried. The dashboard's log is in ~/Library/Logs/Sparehand/.
• Uninstall: quit Sparehand and delete it from Applications. Your settings stay in ~/.config/sparehand (delete that folder to forget your workers); on each worker, jobs ran in ~/.sparehand/, which you can delete too.

Next: Adding a worker for the hand-made way and locking a machine down, AI coding agents, Security model.