Docs › Waking and sleeping workers

Waking and sleeping workers

Spare machines are often asleep. Sparehand can wake them when there's work, keep them awake while it runs, and (on Macs and Linux machines, if you want) send them back to sleep afterwards.

Waking (Wake-on-LAN)

sparehand wake gaming-pc     # wakes it and waits until it answers

• While a worker is on, each status check notes the hardware (MAC) address, network and current address of its adapters. That's what a wake-up ("magic packet") is sent to, on every network it was seen on.
• Woke up somewhere else: a machine can wake on one adapter while the one its ssh alias points to is down (the cable unplugged, so it answers on Wi-Fi only). When the usual address stays silent, Sparehand tries a login at the address each adapter had when the machine was last seen (same user and key, the host key checked against the usual one) and tells you where it is: myworker is awake on en0 (192.168.1.20); its usual address 10.0.0.2 doesn't answer: check that cable or network, or point Host myworker in ~/.ssh/config at the address that answers. sparehand wake then exits 0. Jobs still go through the alias, so a job that woke the machine runs elsewhere until the cable or the alias is fixed; Sparehand never changes your ssh config itself.
• Automatic: when sparehand run finds no free worker and a suitable one is asleep, it wakes it and waits up to SPAREHAND_WAKE_WAIT seconds (90) before running the job here. SPAREHAND_WAKE=0 turns that off.
• The machine must allow it: Wake-on-LAN (or "Wake on Magic Packet") on for its network adapter, and often in its firmware settings. A cable works far more reliably than Wi-Fi. On a Mac: System Settings → Energy → "Wake for network access".

Staying awake during a job

A job that runs longer than a minute keeps its machine from going to sleep until it ends: caffeinate on a Mac, Windows' "system required" state on a Windows PC, systemd-inhibit on Linux. Short jobs don't need it and don't start it.

Sleeping

sparehand sleep macbook-air        # now

Automatically, with SPAREHAND_SLEEP_IDLE_MIN=30 in ~/.config/sparehand/sparehand.conf: after a job, a worker checks again 30 minutes later and goes to sleep only if no Sparehand job ran since, nobody used its keyboard or mouse, and its GPU isn't busy (a game played with a controller doesn't count as keyboard or mouse use).

That applies to Macs and Linux machines. A Windows PC never goes to sleep this way: the commands Sparehand runs there can't see whether someone is using it, so Windows' own power settings decide.

Restarting

sparehand restart macbook-air --check       # what speaks for a restart now
sparehand restart macbook-air               # now (refused while a job runs there)
sparehand restart macbook-air --when-free   # once its jobs end; no new jobs go there meanwhile
sparehand restart macbook-air --cancel      # take that back
sparehand restart macbook-air --no-unlock   # a Mac with FileVault: don't ask for its password (below)
sparehand restart hub                       # this computer, the hub itself (below)

The dashboard's cards and the Mac app (the panel and Settings → Machines) have the same Restart, Restart when free and Don't restart. They also say when a restart is recommended, and why:

• an installed update waits for one (Windows' pending restart, Linux's /var/run/reboot-required);
• the NVIDIA driver was updated under the running one (CUDA fails until a restart);
• a Windows PC's GPU path has degraded (see adding a worker);
• it has been up SPAREHAND_RESTART_DAYS days (30; 0 turns that one off).

Sparehand never restarts a machine by itself for these (the GPU path's heal auto aside). How it restarts, with no password asked:

• Windows (WSL): shutdown.exe /r /t 30, with Windows' countdown and a message on screen.
• Mac: a notification, then System Events' restart 30 seconds later. Apps are asked to quit first, so one with unsaved work can hold the restart up: the Activity tab says when it didn't restart. It needs the Automation permission for System Events there, as worker mode does; without it (an SSH login that was never allowed, say) it restarts with sudo shutdown -r +1 when it has the password (below) or a passwordless sudo, and apps aren't asked to save first. With FileVault on, a Mac waits at its login screen for the password after a restart, and Sparehand can't reach it until someone types it there, unless you give its password with Restart (below).
• Linux: shutdown -r +1 as root or through passwordless sudo (for a server, an admin there can allow just that: echo "you ALL=(root) NOPASSWD: /usr/sbin/shutdown" | sudo tee /etc/sudoers.d/sparehand-restart).

A Mac with FileVault, coming back by itself: the dashboard's and the app's Restart ask for that Mac's password (your user's there, an admin's). With it, Sparehand arms macOS's authenticated restart (fdesetup authrestart -delayminutes -1, which needs that password for sudo and for FileVault) and then restarts: the Mac skips the unlock screen this once and answers again by itself. The password goes to that Mac on stdin, is used there once and is kept nowhere; a wrong one restarts nothing. Leave it empty to type it at its screen instead. sparehand restart macbook-air in a terminal asks for it the same way (not shown as you type; --no-unlock doesn't ask). From a script, on stdin:

read -rs "pw?Password: " && print -r -- "$pw" | SPAREHAND_PASSWORD_STDIN=1 sparehand restart macbook-air; unset pw   # zsh; not shown as you type

macOS keeps an unlock key in memory until that restart (fdesetup's own warning: FileVault protections are reduced meanwhile), so if an app holds the restart up, the next restart of that Mac skips the unlock too. It can't wait for jobs to end (--when-free): the password isn't kept that long.

A cloud worker is stopped instead (sparehand cloud stop): the next job starts it fresh. A machine with a file ~/.sparehand/no-restart is never restarted by Sparehand.

A worker that also starts Windows (dual boot) is restarted into its other system with sparehand switch NAME windows|linux, or Restart into Windows / Restart into Linux on its card (adding-a-worker.md).

The hub itself

sparehand restart hub (or the hub's name) restarts this computer, the same way as a worker of its kind, and only when no job runs here or on a worker (each one's sparehand run waits here, and would stop). --check says how long it has been up and what a restart would do.

With FileVault on, a Mac hub that restarts the usual way comes back to its unlock screen with no network: no Tailscale, SSH or dashboard, so nobody away from it can reach it again until someone types the password at it. So with FileVault on it restarts only with its password, which skips that screen this once:

• In a terminal on it, sparehand restart hub asks for the password (from another computer: ssh -t to it first, so the question reaches you). From a script: SPAREHAND_PASSWORD_STDIN=1, with the password on stdin, as above.
• Without a terminal (Claude's Remote Control, say) and without a password on stdin, it isn't restarted, and it says how instead.
• --no-unlock restarts it anyway, and it then waits at its unlock screen. A Mac that can't skip that screen (fdesetup supportsauthrestart says false) restarts only this way.

The Apple menu (or the Mac app's Restart…, which opens macOS's restart dialog) still works, but with FileVault on the hub then waits at its unlock screen. After a power cut it always does: an authenticated restart only covers a restart that was asked for.