Run the playbook
By the end of this page the box is hardened, on your tailnet, unlocking its own disk, and has every tool the agents need. One command does it; you watch one reboot.
Build a boxBefore you start #
- You can run
ssh ops@192.168.1.50 hostnamefrom your workstation without a password. op signinhas been run in this terminal, or the 1Password app's CLI integration is on.- You are near the box's monitor. Partway through, the playbook reboots the box to prove the disk unlocks by itself, and you want to see that happen.
Run it #
cd ~/nucarium-box && ansible-playbook site.yml
The first run takes 30 to 45 minutes. It reads each secret from 1Password as it needs it, and works through eleven roles in this order:
| Role | What it does |
|---|---|
base |
Updates every package, installs the base packages, sets the time zone, disables sleep, turns on automatic security updates, raises file-watcher limits, lets TRIM reach the SSD, and attaches Ubuntu Pro if you gave a token. |
tpm |
Binds the disk key to the TPM, saves a backup of the disk header to out/ in the recipe folder, sets the boot-menu password, and reboots. |
network |
Joins Tailscale with the tag, hardens SSH, and turns on the firewall: Tailscale in, and SSH from your home network as a fallback. |
nut |
UPS monitoring and the low-battery shutdown. Skipped when nut_enabled is false. |
users |
Creates agent and broker, the short-lived token folder, and checks the command sandbox works. |
toolchain |
GitHub CLI, Go, Node and pnpm, the commit-signing key and the Git identity. |
broker |
Installs the GitHub App key where only broker can read it, and the timer that mints a fresh GitHub token every 20 minutes. |
claude |
Claude Code and, for each login, its settings file: the sandbox, the GitHub token hook and the nucleated hook entries. Also your agent-context/ files. |
workspace |
Downloads the pinned release of nucleate and nucleated, checks its SHA-256, and installs both for the agent user. Creates the nucleus at /home/agent/workspace with nucleate init, makes each repo available with nucleate clone, and registers the worktree hooks and the MCP server. |
agent_servers |
One agent-server@<name>.service per environment, under one shared memory cap. Enabled, not started. |
day2 |
nucleated: its config, generated from environments, its unit, and the sign-in to Watch if you gave a token. Also a weekly cleanup of container images, the package store and the journal, and the nightly backup if you configured one. |
What the playbook does explains each of these.
Watch the reboot #
During the tpm role the box restarts. Watch its console: it should boot straight through without asking for the passphrase. That is the test of the TPM binding.
If it asks, type the passphrase, let the playbook finish, and see Troubleshooting.
If it stops #
If the playbook stops with an error, fix the cause and run the same command again. It only redoes what is not done.
The two usual causes on a first run:
| It stops at | Cause |
|---|---|
| "Read secrets from 1Password" | The CLI is not signed in, or a reference in group_vars/all.yml does not match an item. Test one by hand with op read. |
| The very first task, unreachable | ansible_host in inventory.ini is wrong, or SSH to the box asks for a password. |
Afterwards #
The playbook ends by printing what is left to do by hand. Three of those are housekeeping on your workstation; do them now.
-
Keep the disk header backup, then delete the file. The first megabytes of the encrypted partition hold the keys. If they are ever damaged, the passphrase is useless without this file. Attach
~/nucarium-box/out/agentbox-luks-header.imgto the passphrase's item in 1Password, then delete it from the folder. -
Add two SSH shortcuts, one for you and one for the agents' user. The names resolve through Tailscale.
Workstation~/.ssh/config Host agentbox HostName agentbox User ops ServerAliveInterval 30 Host agentbox-agent HostName agentbox User agent ServerAliveInterval 30Check both. The second should print
agent:Workstation ssh agentbox hostname && ssh agentbox-agent whoami -
Remove
ansible_host=...frominventory.ini, so later runs go over Tailscale.Workstation~/nucarium-box/inventory.ini [boxes] agentbox ansible_user=ops
Once Tailscale is proven, you can close the home-network fallback: set lan_ssh_cidr: "" and run the network role again.
Changing anything later #
It is the same command. Edit the files in the recipe folder and run it again. To see what would change without changing it:
cd ~/nucarium-box && ansible-playbook site.yml --check --diff
To run one part, name its role as a tag:
cd ~/nucarium-box && ansible-playbook site.yml --tags workspace
Next, sign in and start the agents.