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.

On this page

Before you start #

  • You can run ssh ops@192.168.1.50 hostname from your workstation without a password.
  • op signin has 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 #

Workstation
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.

  1. 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.img to the passphrase's item in 1Password, then delete it from the folder.

  2. 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 30
    

    Check both. The second should print agent:

    Workstation
    ssh agentbox hostname && ssh agentbox-agent whoami
    
  3. Remove ansible_host=... from inventory.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:

Workstation
cd ~/nucarium-box && ansible-playbook site.yml --check --diff

To run one part, name its role as a tag:

Workstation
cd ~/nucarium-box && ansible-playbook site.yml --tags workspace

Next, sign in and start the agents.