What the playbook does
Every part of a box, what it is for, what it does not protect against, and one command that checks it. Read this when you want to understand a part, change it, or confirm it is still doing its job.
Build a boxOn this page
The recipe folder #
Everything about a box lives in one folder on your workstation. It holds no secrets, only references to them.
| Path | What it is |
|---|---|
inventory.ini |
The box's name and how to reach it |
group_vars/all.yml |
Every setting that differs between boxes |
autoinstall.yml |
Renders the unattended-install answers for the settings stick |
site.yml |
The playbook. Runs the roles below, in order. |
roles/ |
One folder per role |
agent-context/ |
Optional. Your instructions and skills for the agents. |
out/ |
Files the playbooks write for you: the install answers, the disk-header backup |
Running site.yml again is always safe. It changes only what differs from the recipe. Each role's name is also a tag, so --tags network runs one part, and --check --diff shows what a run would change.
Three users #
The box separates who administers it, who works on it, and who holds its secrets.
| User | Role | Can |
|---|---|---|
ops (your operator_user) |
You | Use sudo. Administer the box. |
agent |
The agents | Run sessions, containers and its own services. No sudo, no password, none of your credentials. |
broker |
A service-only user | Read the long-lived secrets and write short-lived tokens for agent. Nobody logs in as it. |
Your SSH key logs in as either ops or agent. Lingering is on for agent, so its services run with nobody logged in. You never clone repos or sign in to GitHub as yourself on the box; your own reviews and merges happen on your workstation.
Check it. This must print agent and then a refusal:
ssh agentbox-agent 'whoami; sudo -n true 2>&1 | head -1'
The token broker #
Agents need to push branches and call GitHub. They never hold a credential that lasts.
The GitHub App's private key sits in /etc/agent-broker/, readable only by broker. Every 20 minutes a timer runs a small minter as broker: it signs a nine-minute assertion with the key, exchanges it for a one-hour installation token, and writes only the token to /run/agent-tokens/github, which agent can read. The token in the file always has at least 40 minutes left.
Three things read that file, each time they need it:
- Git. Repos are cloned over HTTPS, and Git's credential helper reads the current token on every push and fetch.
- Commands in a session. A
SessionStarthook writes a rule into the session's environment so thatGH_TOKENis read fresh before every command. A token value is never baked into a session. nucleate, for its check on merged pull requests.
Check it. The first line should print ghs_; the second must be refused:
head -c 4 /run/agent-tokens/github; echo
cat /etc/agent-broker/github-app.pem
Two limits. A single command that runs for more than 40 minutes and only reaches GitHub at the end can meet an expired token. And a long-lived process that is not a shell command, such as an MCP server started hours earlier, does not re-read the environment; it should read the file itself.
Other credentials #
- The packages token is in
agent's~/.npmrc. Agents can read it, so it has the single scoperead:packages. - The signing key is
~/.ssh/id_ed25519_signingforagent, with no passphrase so agents can sign without a prompt. It is registered on GitHub as a signing key only. It can mark a commit as yours; it cannot log in or push. - Terraform credentials are optional and off by default (
hcp_mode: none).
What this buys you #
Pull requests show the app as their author, so you can formally review and approve them as yourself, and that approval means something. Retiring a box is deleting its private key on GitHub. Nothing on the box has a fortnightly expiry to rotate.
Disk encryption and the TPM #
The disk is encrypted with LUKS. The playbook binds the disk key to the TPM with Clevis, so the box unlocks itself at boot as long as its Secure Boot state has not changed. Your passphrase keeps working as a fallback.
The other pieces:
- The boot-menu password means editing a boot entry needs a password, while normal boots stay unattended.
- The disk-header backup is the copy of the first megabytes of the partition that you attached to the passphrase in 1Password. Without it, a damaged header makes the passphrase useless.
- TRIM is passed through the encryption layer, so the SSD does not slow down as it fills.
Check the binding and note the slot number it shows:
sudo clevis luks list -d /dev/nvme0n1p3
When the box asks for the passphrase at boot, the Secure Boot state changed: usually a firmware update or a Secure Boot database update. Type the passphrase at the console, then bind again with the slot number from the list:
sudo clevis luks regen -d /dev/nvme0n1p3 -s 1
That prompt appears at a console you cannot reach remotely, and it appears exactly when you are least likely to be standing next to it. Decide now how you would type a passphrase from elsewhere. A small network KVM plugged into the box and joined to your tailnet works whatever the system uses to build its boot image.
The network #
Tailscale is the only way in. The box joins with the tag tag:agent-box, and your access rules let people's devices start connections but not tagged ones. So the box accepts connections and cannot open any to your other devices. Tagged machines have no key expiry, so the box never drops off the tailnet, and Tailscale keeps itself updated.
SSH refuses passwords, keyboard-interactive logins and root.
The firewall refuses incoming connections by default and allows three things:
| Rule | Why |
|---|---|
| Everything outgoing | Agents fetch packages and push branches |
| Everything incoming on the Tailscale interface | You, your phone, and a dev server an agent started |
SSH from lan_ssh_cidr |
A fallback from your home network. Set lan_ssh_cidr: "" to remove it once Tailscale is proven. |
Check it:
sudo ufw status verbose
And check the tag holds. From the box, this must fail to connect; use any other device's Tailscale name:
nc -zv -w 3 your-laptop 22
The base system #
- Every package is updated, and security updates install daily without a reboot, including for the outside package sources the recipe adds.
- Sleep, suspend and hibernate are masked. A box does not sleep.
- File-watcher limits are raised, because many agents running build tools and test watchers at once exhaust the defaults.
- With an Ubuntu Pro token, Livepatch applies most kernel security fixes without a reboot.
When a full reboot is still needed, /var/run/reboot-required exists. Reboot at a quiet moment; sessions end, and everything comes back by itself.
The UPS #
NUT watches the UPS over USB. When the battery gets low it shuts the box down cleanly, then tells the UPS to switch its outlets off. When mains power returns the UPS powers back on, and the box starts by itself because of the firmware setting.
| Setting | Default | Meaning |
|---|---|---|
ups_charge_low |
40 |
Shut down at this battery percentage |
ups_runtime_low |
600 |
Or when this many seconds of runtime are left, whichever comes first |
ups_offdelay |
60 |
Seconds after the shutdown starts before the outlets switch off |
ups_ondelay |
120 |
Seconds after the shutdown starts before they may switch back on |
The thresholds are set in the recipe instead of waiting for the UPS's own low-battery signal, which leaves a safety margin. The delays are set explicitly because many UPS models count them in whole minutes and ignore anything shorter.
One line matters more than the rest: NUT's power-down flag. It is what makes NUT tell the UPS to switch off at the end of the shutdown. Without it the outlets stay on, the box never sees power return, and it stays off.
Check it. The last line should print your ups_charge_low:
upsc ups && upsc ups battery.charge.low
Claude Code and the sandbox #
The playbook installs Claude Code for agent and one settings file, ~/.claude/settings.json, that applies to every session on the box. The part that keeps twelve sessions answerable is the sandbox:
{
"autoUpdatesChannel": "stable",
"sandbox": {
"enabled": true,
"autoAllowBashIfSandboxed": true,
"failIfUnavailable": true,
"excludedCommands": ["podman"],
"network": {
"allowedDomains": [
"github.com", "api.github.com", "*.githubusercontent.com",
"npm.pkg.github.com", "registry.npmjs.org",
"proxy.golang.org", "sum.golang.org", "go.dev",
"app.terraform.io", "registry.terraform.io", "releases.hashicorp.com"
]
}
},
"permissions": {
"deny": [
"Bash(terraform apply *)",
"Bash(terraform destroy *)",
"Bash(terraform force-unlock *)"
]
}
}
| Setting | What it does |
|---|---|
sandbox |
Confines shell commands to the session's folder and the listed sites, and lets confined commands run without a prompt. You are asked only about what steps outside. |
failIfUnavailable |
Makes a broken sandbox an error, not a silent return to unconfined commands. |
excludedCommands |
Containers cannot start inside the sandbox, so podman asks for permission instead. |
allowedDomains |
A starting list. When a command is blocked from a site it needs, you get a prompt; add the site if it is a regular one. |
permissions.deny |
Stops a local terraform apply at the prompt. This is accident-proofing, not a boundary. |
autoUpdatesChannel |
Keeps Claude Code about a week behind the newest release. |
The same file registers the hooks: the one that keeps GH_TOKEN fresh, and the ones that tell nucleated what each session is doing. The hook entry point covers those.
Check the sandbox works for agent. It should print sandbox-ok:
bwrap --ro-bind / / true && echo sandbox-ok
The workspace #
The workspace role installs nucleate and builds the nucleus at /home/agent/workspace:
- Each repo in
reposis cloned bare into.repos/, over HTTPS, with remote-tracking refs so a fetch never rewrites a branch that a session has checked out. - The worktree hooks are registered at the nucleus root, so the agent server asks
nucleateto create and remove session folders. - The
nucleateMCP server is registered for the user, so every session haslist_repos,add_repo,remove_repoandworkspace_status.
There is no shared main checkout, on purpose. Nothing exists for an agent, or you, to edit by accident.
Check it. This lists the repos sessions can add:
nucleate available
The agent servers #
Each environment in your settings gets one agent server: Claude Code's Remote Control server, started in the nucleus with one worktree per session.
It runs as a systemd user unit, agent-server@<environment>.service, one instance of a single template. The unit waits for the internet before starting, because after a power cut the box boots faster than the router. It restarts the server whenever it exits, which the server does by design after about ten minutes without a connection. The server is a terminal program, so the unit runs it inside tmux: tmux -L agent-main attach shows its screen.
All agent servers run inside one slice, agents.slice, which carries a memory ceiling for every session together. A runaway build is stopped inside that group, and the system, SSH and Tailscale keep running.
| Setting | Default | Meaning |
|---|---|---|
capacity, on each environment |
12 |
Sessions that environment's server runs at once. A ceiling, not a reservation. |
agents_memory_high |
48G |
Where the kernel starts pushing back on the agents as a group |
agents_memory_max |
56G |
The hard ceiling for the group, on a 64 GB box |
Raise both memory numbers if you add a second memory stick, then run --tags agent_servers.
Check them:
systemctl --user list-units 'agent-server@*' --no-pager
systemctl --user show agents.slice -p MemoryHigh -p MemoryMax
nucleated #
The day2 role installs nucleated, its config file and its unit. The daemon does the jobs that keep a box healthy without you:
- It sends a heartbeat and forwards what each session is doing, to Watch once the box is signed in, and to nowhere until then.
- It fetches every repo hourly and drops branches deleted on GitHub.
- It removes the folders of finished sessions that hold nothing unsaved.
- It snapshots uncommitted work to a hidden ref on the remote hourly, so a dead SSD does not take an afternoon's work with it.
The daemon watches the agent servers. It does not run them: if it stops, sessions carry on.
Check it:
nucleated check
The nightly backup #
Repos and work in progress are on GitHub. What exists only on the box is the agents' session transcripts, the seed files, and the configuration the playbook built. If you fill in the restic_* references, a nightly timer backs those up, encrypted, to object storage, and keeps seven daily and eight weekly snapshots.
The broker's secrets and the Claude sign-in are left out on purpose. They live in 1Password and in a browser.
A backup you have not restored from is not one yet. Pull one file back and compare it:
sudo bash -c 'set -a; . /etc/restic/env; restic restore latest --target /tmp/restore-test --include /home/agent/workspace/AGENTS.md'
sudo diff /tmp/restore-test/home/agent/workspace/AGENTS.md /home/agent/workspace/AGENTS.md && echo restore-ok; sudo rm -rf /tmp/restore-test
Seed files can hold secrets. The backup is encrypted with the restic password, so that password is as sensitive as they are, and without it nobody can read the backup, including you.
Every setting #
All of these are in group_vars/all.yml.
| Setting | Default | What it sets |
|---|---|---|
operator_user, agent_user |
ops, agent |
The two login users |
timezone |
Etc/UTC |
The box's time zone |
lan_ssh_cidr |
192.168.1.0/24 |
Home network allowed to SSH in. Empty for Tailscale only. |
tailscale_tag |
tag:agent-box |
The tag the box joins with |
git_user_name, git_user_email |
Identity on agents' commits | |
github_org, repos |
your-org, web, api |
Repos cloned into the nucleus |
github_app_client_id, github_app_installation_id |
The GitHub App the broker mints tokens for | |
go_version, node_version |
Toolchain versions | |
environments |
One, main |
The agent logins on this box, each with a name, a capacity and, from the second on, a config_dir |
watch_target |
hosted |
hosted reports to Watch once the box is signed in; none reports nowhere |
nucleate_version, nucleate_sha256 |
0.3.0, pinned |
The release of nucleate and nucleated to install, and the SHA-256 published beside its archive. Each release of the recipe pins the release it was tested with, and the playbook refuses a download that does not match. Change both together to install another release. |
agents_memory_high, agents_memory_max |
48G, 56G |
The memory ceiling on all agent servers together |
nut_enabled and the ups_* settings |
true |
UPS monitoring. False on a box with no UPS. |
hcp_mode |
none |
Terraform credentials |
secret_refs |
1Password references. An empty value skips that feature. |
What stays manual #
Some steps need a person, a console or a browser, and always will: assembling the hardware and setting the firmware, booting the installer, typing the first passphrase, creating the GitHub App, signing in to Claude and answering the agent server's two first-run prompts, registering the signing key, and pulling the plug to test the UPS.
An honest rebuild is therefore: install Ubuntu, run the playbook, do the sign-ins, run the proof steps.
That is the box. The next section is nucleate, the tool that gives every session its own workspace.