How-to

Runbooks for the steps only you can do — sudo, interactive logins, and secret values. Each one is short and exact. No command here prints a secret; where a value must never be displayed, the runbook says so.

In order

Once, for a new box or a rebuilt one.

Until step 5 joins Tailscale, use the LAN. The tailnet names don’t resolve before then, so use the LAN aliases from SSH from the Mac’s ~/.ssh/config: brightroar-lan wherever a runbook says brightroar (for ssh or scp), and brightroar-agent-lan wherever it says brightroar-agent. If the Mac’s config lacks those blocks, add them first; the keys can wait for step 4, and until then you log in with your password.

Before step 1, on the Spark, as yourself: install Claude Code and uv with their official installers (the commands changelog.md records for the first setup), and tmux and gh, which step 1 uses before bootstrap installs them. Then log out and back in, so ~/.local/bin is on your PATH:

curl -fsSL https://claude.ai/install.sh | bash
curl -LsSf https://astral.sh/uv/install.sh | sh
sudo apt install tmux gh
  1. The Spark session — first, before any [Spark] task.
  2. Leak guards
  3. Bootstrap the Spark
  4. SSH from the Mac
  5. Join Tailscale
  6. Secret files
  7. Deploy the stack
  8. pi, the coding agent — agent’s Claude Code gets the secrets guard before its key.

After step 5, go back to SSH from the Mac for Keys only and the public IPv6 check, which need the tailnet name.

Then ongoing, not once: Updates — apt any time, and upgrade day on Saturdays.

On the Mac, if you use it: Orca on the Mac — your Claude Code and pi in Orca’s panes.

Every runbook

Title Description
A scratch model to tinker with Temporary: build llama.cpp in your home folder, serve one model, and use it from the Mac through an SSH tunnel — until Phase 1’s stack replaces it.
Bootstrap the Spark Bounce the wired NIC, run make bootstrap, check the results, and set up agent’s SSH and Claude Code login.
Deploy the stack The first deploy on the Spark, the web UI over tailscale serve, and every later change.
Join Tailscale Install, MagicDNS and HTTPS, the ACL grants that act as the firewall, and the rebuild trap.
Leak guards Install gitleaks and shellcheck, create your denylist, turn the hooks on, prove they bite, see what they check, scan before every push, and read a red CI leaks job.
Orca on the Mac Your Claude Code and pi in Orca’s panes on the Mac, pi reaching the Spark over the tunnel: Orca’s two settings, what it changes, and how to remove it.
SSH from the Mac A key for you and a key for agent, a block in the Mac’s ~/.ssh/config for each way in, where NVIDIA Sync fits, then keys-only SSH and a one-time public IPv6 check.
Secret files Every Phase 1 secret file, step by step, generated so no value is ever displayed.
The Spark session Before any [Spark] task: the Mac’s rules and secrets guard on the Spark, then Claude Code in tmux with the Mac’s plugins, a GitHub token for this repository only, and this project’s private context.
Updates What you can run any time, what updates by itself, what waits for upgrade day, and how to check everything is back afterwards.
opencode and Hermes on the Mac The Spark’s models in opencode and Hermes: one command writes both providers from the registry, with your key by reference.
pi, the coding agent pi on the Mac through an SSH tunnel, and as agent in tmux on the Spark, once agent’s Claude Code has the secrets guard.
No matching items