The guide
The kit’s own guide, in short. The full version, with every command, ships with the kit.
What you need
Before you start, have four things ready: a Telegram bot token from BotFather, your Telegram user id, a Surplus key with credit, and your Claude and ChatGPT plans.
- One Fedora Workstation VM under VMware, VirtualBox, Hyper-V or KVM, on a Mac, Windows or Linux host. Size it for one build box at a time beside the desktop: we run Fedora 44 on x86-64 with four CPUs, 16 GB of memory and a 100 GB disk. An arm64 image on Apple silicon is untried.
- Claude Code and Codex, signed in on their plans. The play installs both command-line tools.
- A Surplus API key with credit: the model provider for Hermes and the workshop’s builder key.
- Hermes with a Telegram bot and your own Telegram chat id. Every scheduled job reports to that chat; without Telegram you can still run cards by hand.
- Paid separately, by you: a Claude plan that includes Claude Code, a ChatGPT plan that includes Codex, and Surplus credit. The kit charges nothing of its own.
- Optional: a second machine for backups, which stay off until you turn them on.
The first hour
- 1Clone the bundle you received to ~/src/fedora-devvm.
- 2Bootstrap the VM with one script and sudo.
- 3Answer kit-init’s questions, which write your private overlay, then run the provisioning play it prints.
- 4Set up Hermes: the Telegram bot, the Surplus key and the gateway.
- 5Sign Codex in with your plan.
- 6Apply the loop one script at a time, reading each before you run it: the control plane, the two workshop secrets, the loop itself, the deadman, the reviewer, the morning brief and health alert, and the loop board. The Telegram bridge and the merge pass are optional.
- 7Write the first card, against the kit itself, and let a tick build it.
What runs when
| What | When |
|---|---|
| The tick: one card claimed and built | every 15 minutes |
| The spend governor | every 5 minutes |
| The deadman, which alerts if the scheduler stops | every 10 minutes |
| The Claude reviewer | 06:15 daily |
| The morning brief, and the health alert | 07:00 daily, and every 5 minutes |
| The merge pass, if you apply it | every 60 minutes, preparing only until you switch installs on |
| Backups | never, until you activate them |
How drops arrive
Personal and Team copies get the kit’s updates for 12 months, as drops. Each drop arrives by email as a git bundle packed on top of the one you have. You pause the schedule, merge it, re-run whatever it changed, and resume; the full guide lists each step. The drops so far.
What is not included
- Your accounts, keys and tokens, and the Telegram bot itself.
- A hosted service: everything runs on your VM.
- The original install’s status documents and validation records. The research behind the picks is on the notes pages instead.
- Backup activation: the policy and scripts ship; the decision and the backup host are yours.