Shards

A shard is smaltid on a machine you do not sit at: a build box, a server, a Linux VM. It joins your Mac's fleet, so its sessions, load and permission prompts show up in Smalti, and you approve its prompts from the Mac or your phone.

What a shard is

The same smaltid binary the Mac app ships, with a shard profile: a fleet name, a stricter resource governor, and a reader for the Commitwell pool client's load. There is no window and nothing to configure by hand. The Mac (the hub) shows each shard under Machines with its CPUs, free memory, running agents and pool jobs.

Adding a machine

  1. In Smalti, click + next to Machines in the sidebar (or Add a Machine in the palette). Smalti shows a join code and one line to run for Linux, macOS or Windows.
  2. On the new machine, sign in to Tailscale and to gh, then paste the line. It downloads smaltid from the GitHub release, checks its SHA-256 checksum, unpacks it and runs smaltid join with the code.
  3. The machine appears under Machines within a few seconds.

smaltid join copies smaltid to a stable place (~/.local/bin), writes the shard profile, and runs smaltid at login: a systemd user unit on Linux, a launchd agent on macOS, a logon task on Windows. On a Linux server, loginctl enable-linger keeps it running when nobody is logged in.

How joining stays safe

  • A join code works once and expires after 10 minutes. Only the Mac's owner can make one, and only on the Mac itself.
  • The hub checks the code before it does anything else, then calls the new machine back over Tailscale to confirm it, and only then uses the code up. A failed attempt leaves the code valid, so you can fix the problem and run the same line again.
  • The hub receives a peer token for the shard. That token can read the shard's sessions, inbox and load and answer its permission prompts. It cannot open a terminal, send signals, pair devices or make join codes. The shard receives nothing from the hub.
  • Everything travels over Tailscale. A shard URL that is not a Tailscale address is refused.
  • The install line never pipes a download into a shell: gh fetches the release over an authenticated connection and the checksum is checked before anything runs.

Sharing a machine with CI

Build machines often also run the Commitwell pool client. A shard reads the pool client's status every 15 seconds. While the pool is running jobs, new agent launches wait in the queue (agents already running keep going), and the shard keeps a quarter of its memory free for the pool's bursts. Both limits are in the shard's config.json as pool_busy_max_agents and reserve_memory_pct. See Resource governor.

Removing a machine

Right-click the machine under Machines and choose Remove from the Fleet. The hub forgets the machine and its token. To stop smaltid on the machine itself, remove its login service (systemctl --user disable --now smaltid on Linux).