Docs › Configuration

Configuration

Everything lives in ~/.config/sparehand/ on the hub (or the folder in SPAREHAND_CONFIG).

The hub's activity log is ~/.local/state/sparehand/log (jobs started and finished, fallbacks, pauses, switches); the app's Activity tab shows it.

Every run is also recorded in ~/.local/state/sparehand/jobs.tsv, one tab-separated line per job: time, machine (- = it ran on the hub), repository, checkout, exit code, seconds, seconds waited, command, and a note (why it ran on the hub, or that it was stopped or handed back). A job that ran on a worker then has where its time went, in seconds: the sync, the install (dependencies and the project's hook), the command itself, and the whole time from the start of sparehand run to its end. Lines written before these were recorded end at the note. sparehand history [DAYS] summarises it (default 30 days): jobs, success rate and average time per machine, time per project on each machine, why jobs ran on the hub, and how the workers compare with the hub (below). The app's History tab shows the same, for 7, 30 or 90 days. Delete the file to start over; the choice of worker and the comparison with the hub start over with it.

Did the worker finish sooner?

Sending a job to a worker only pays when it ends sooner than it would have on the hub, so every job that ends on a worker closes with a line saying where the time went and how it compares:

[sparehand] myworker took 1m 12s (waiting 0s, sync 4s, install 0s, command 1m 6s, the rest 2s). This Mac takes about 1m 50s for it: 38s sooner on myworker.

• waiting: for a free machine, when every worker was busy. sync: copying the checkout. install: dependencies and the project's hook on the worker. command: the command itself. the rest: choosing the machine, starting the job there and bringing --get paths back.
• The worker's side of the comparison is the whole time, with all of those in it, not the command alone.
• The hub's side is measured, never estimated: the average of the last 3 times this exact command ran on the hub in this repository (any of its checkouts) and ended with exit code 0. Those runs are the ones Sparehand makes on the hub itself: sparehand run --or-local (and run at a terminal) when no worker could take the job, and sparehand run --here <command>, which runs the command on the hub on purpose, timed, to have something to compare with.
• When the command has never run on the hub, the line says so and gives the run --here command; no number is shown. When the worker was slower, the line says by how much ("20s slower on myworker this time").
• Only jobs that ended with exit code 0 are compared (a failing run ends early). A job a script or an agent's hook ran itself after exit 255 isn't timed: Sparehand doesn't see it run.

sparehand history adds these up ("They finished 4m 10s sooner in all than the hub would have (2 were slower on a worker, by 40s)"), counting only jobs whose command has a time on the hub. The dashboard shows the same per job on the Jobs tab (the jobs finished in the last day) and the History tab, with a line for the last 7 days and a tile for the period. The hub's time is a run under whatever else the hub was doing then, so measure it (run --here) when the hub is as busy as it usually is while you work.

Rename a worker with sparehand rename NAME NEW (a switched-off worker stays off; its history keeps the old name), or the hub with sparehand rename hub NEW, which sets SPAREHAND_HUB_NAME. Worker names use letters, digits, - and _ (up to 32); the hub's name may also contain spaces. Both can also be done in the app's Edit form.

The app's Settings

The Settings button at the top of the app (or the , key) gathers everything you can change from the dashboard. Type in its search box to find a setting by name.

• Appearance: light, dark or the same as the device; a larger text size; less motion. These are kept per device, in the browser.
• Tips and start: the one-line tip under each tab, the tab the app opens on, and the Help button.
• Notifications on this device, and answering your sessions' permission prompts from here (the same switches as on the Sessions tab).
• Each part: a button to each part's own settings: adding a machine or an AI model, Crew's agents and how the Master works, Studio's keys, voices, brand kits and YouTube, and the Helper's AI model.

Keys: 1–9 open a tab in the order shown, ←/→ move between tabs when one is focused, ? opens the Helper and / searches your sessions. The browser's Back and Forward buttons go through the tabs you opened.

Settings

Set them in sparehand.conf, or as environment variables for one command (SPAREHAND_MIN_MEM=20 sparehand run make); the environment wins over the file.

Per command only:

See also: GPU jobs, forwarding ports, file sharing, Android emulators, mobile builds and GitHub Actions runners (their own settings).

How a worker is chosen

For each worker that is enabled, reachable and not paused: it needs SPAREHAND_MIN_MEM% memory free, a free job slot (a job that was chosen and is still syncing holds its slot too, for up to 10 minutes), CPU under SPAREHAND_MAX_CPU% and GPU under SPAREHAND_MAX_GPU% (unless the GPU is busy with a Sparehand GPU job). A GPU job also needs a worker with an NVIDIA GPU that no other GPU job is using. Among those, the lowest score wins (CPU busy fraction + 0.15 per running job). The job history counts too: when two or more machines have run this exact command in this repository before, a slower one gets a worse score (0.2 per "times slower", up to 0.6), so the fastest free machine is preferred; SPAREHAND_HISTORY=0 switches that off. If the hub itself is clearly less busy (by 25 points) and has the memory, the command runs on the hub: at a terminal Sparehand does that itself and says so (SPAREHAND_LOCAL_FALLBACK), and a script, a pipe or an agent's hook gets exit 255 instead, which means "run it locally".

On a Mac (the hub and macOS workers), memory "free" is counted the way Activity Monitor counts memory used: app memory, wired memory and compressed memory are in use, the rest (cached files, free pages) is free. macOS's own "free percentage" counts compressed memory as free, so a Mac with 10 GB in swap read 22% in use. While a macOS worker reports memory pressure, swap in use counts as used too. The watchdog that stops the newest job below SPAREHAND_KILL_MEM still uses macOS's own figure: it is there for a machine about to run out, and a healthy Mac often sits at 80–90% used.

Besides CPU, memory and job slots, a worker takes no new job while it is strained: its memory pressure is at warning or worse (macOS's own level; on Linux, the kernel's pressure figures where it has them, counted only while memory is also low: below 30% available for warning, 15% for critical, since loading a big model file stalls memory for a while without running out), a Mac reports its thermal state as serious or critical, or its GPU is at SPAREHAND_MAX_GPU_TEMP (not from Sparehand's own GPU job). sparehand status, the dashboard and the menu bar show it ("Hot", "Memory pressure"; each card has a Health line all the time), and the app and the dashboard's notifications say when a machine comes under strain or a job was stopped, with the reason. The last day's alerts are on the machine's card until it has been fine for 10 minutes (up, not strained, at least 30% memory free; alertClearSeconds in app.json changes the wait).

A worker that lacks one of the tools workers should have (bash, rsync, git, zsh: zsh for Sparehand's own commands there, such as Crew's) says so in sparehand status and on its card, with the command that installs it there (sudo apt-get install -y zsh). One missing bash, rsync or git takes no job (every job would fail at the sync); one missing only zsh still does. Sparehand doesn't install them by itself: that needs an administrator's password. New workers get them when they join.

sparehand doctor NAME checks one machine end to end: that it answers over SSH, that this computer's key is accepted and the machine's own key is still the one trusted, the tools (node is optional: node isn't installed: fine unless you use the AI features), the free disk, and one small file sent there and back the way a job's checkout travels. sparehand doctor does it for every worker. sparehand doctor NAME --check prints the same as lines the app reads, one per item, check<TAB>ITEM<TAB>ok|warn|bad<TAB>message (items: reachable, key, hostkey, tools, disk, roundtrip), then result<TAB>ok|warn|bad<TAB>summary; it exits 1 when something is bad.

What happens on a run

1. The checkout is synced with rsync to ~/.sparehand/runs.noindex/<repo>-<id>/<checkout> on the worker, skipping everything git ignores. (The exclude list is generated from git ls-files --ignored because macOS ships openrsync, which ignores .gitignore filter rules when deleting and would wipe node_modules on every run.) --with fixtures,gen/api.ts (or SPAREHAND_WITH) sends those git-ignored paths too: test fixtures, generated code. Paths are relative to where you ran the command and stay inside the checkout; a folder goes with what is in it, but an ignored folder around it doesn't, and .env files never do (not by name, not inside). What it sent stays in the worker's copy afterwards, as git-ignored files there do.
2. The .git folder isn't copied (security.md). When the checked-out commit or branch changed, git is set up in the folder there: the commits it lacks arrive as a git bundle in a store shared by the repository's checkouts on that worker (.gitcommon), and the folder's own .git points HEAD at the same commit and branch name, with no hooks and a config of a few lines. Changes you haven't committed show there as not staged.
3. On the worker: dependencies are installed when the lockfile changed (pnpm, yarn, bun, npm; uv, Poetry with its virtualenv in the checkout, or a requirements.txt into a .venv of its own that the job then runs in, made with uv when the worker has it; without a way to make one the job runs with the worker's own python3 and says so; cargo fetch for a Cargo.lock, go mod download for a go.sum, into the machine's own caches, only where cargo or go is installed and never stopping the job), each keyed by its lockfile's hash, then your hook runs, then the command, in the same subdirectory you ran sparehand run in.
4. A watchdog checks every 2 s and stops the job if the worker is paused or its GPU stays busy for 3 checks (someone started a game). When the worker is about to run out (memory below SPAREHAND_KILL_MEM free or its pressure critical, a Mac at a critical thermal state, the GPU at SPAREHAND_KILL_GPU_TEMP), only the newest job there stops, the one that most likely pushed it over, and the next newest only if it is still too much. Then sparehand run exits 255, the reason goes into the job history, and the app sends a notification. It also stops the job when the hub's connection drops (you pressed Ctrl-C, an agent timed out, the hub went to sleep), so nothing keeps running on a worker that nobody is waiting for.
5. Output streams back live; the command's exit code is passed through. A job stopped with sparehand stop (or the app's Stop button) exits 130. Exit 127 ("command not found": a tool the job needs isn't installed on that worker) becomes 255, so the caller runs it locally; so does a folder you ran it in that the worker hasn't got (only git-ignored files in it). Every other code is the job's own, 2 and 254 included. The worker says why it handed a job back in a note (~/.sparehand/ended.TOKEN), not in the exit code alone, so a job whose own exit code is 254 or 255 is reported as that, --or-local doesn't run it a second time, and the output says it was the job's own result. ssh also exits 255 when the connection drops; without the worker's note the job is handed back (exit 255, run it locally) and the job history says "connection lost", even when the worker answers again by then.
6. --get coverage,dist (or SPAREHAND_GET): when the job ends, those paths are copied back from the worker to the same places here, each replaced whole, whatever the exit code (a failed run's report is the useful one). Paths are relative to where you ran the command and must stay inside the checkout. A path the job didn't make is mentioned, not an error. A path that is a symlink here (or leads through one) isn't replaced; .git, .claude, .vscode and .idea folders and symlinks pointing outside what is copied don't come back.
7. One job per checkout per worker at a time: a second job from the same checkout waits for the first (its sync would otherwise rewrite the folder under the running job) and says so. Use another worker, or another checkout (a git worktree), to run two at once.

Moving to a new Mac

Everything Sparehand knows lives in your home folder: ~/.config/sparehand (workers, settings, forwards, app.json, hooks), ~/.local/state/sparehand (history, markers) and your SSH key in ~/.ssh, which is what the workers trust. Migration Assistant copies all of it, and the Keychain (file-sharing sign-ins, the licence) comes along with your login keychain, so on the new Mac you install the app and carry on: the workers, the shared folders and the tunnels are there.

Setting the new Mac up by hand instead: copy those two folders and the SSH key pair, or pair each worker again from the new Mac (Add a machine → Pair with a code). A licence key is activated per Mac: on the old Mac, Settings → Licence → Use the licence on another Mac… releases it first (or deactivate it from the email the key came in). The old Mac's run folders on the workers are reused by the new one, since they are named after the project, not the hub.

Two hubs, one worker

Each hub has an id (~/.config/sparehand/hub-id, random, made once). A worker's run folders are named with it and record it, so two hubs that share a worker keep separate folders and the daily clean-up of one never removes the other's. sparehand remove NAME leaves that machine as it is while another hub's run folders are there; sparehand remove NAME --clean is the exception: it removes the whole ~/.sparehand on that machine, the other hub's folders included.

Files on a worker