Prepare your workstation
By the end of this page the box recipe is in a folder on your computer with your settings in it, and every secret it needs is in 1Password. Do this before the hardware arrives.
Build a boxOn this page
Run the installer #
On your Mac or Linux computer:
curl -fsSL https://nucarium.sh | sh
It gets this computer ready to build a box. It does not touch the box. In order, it:
- Checks for the tools the recipe needs: Ansible, the 1Password CLI, an SSH client and an SSH key. For each one that is missing it shows the command that installs it and asks before running it. A command that needs
sudois never run on a default answer. - Downloads one pinned release of the box recipe from its repository and checks its SHA-256.
- Unpacks it into a folder you choose. The default is
~/nucarium-box. Use one folder per box. - Installs the two Ansible collections the recipe uses, and
passlib, which hashes the login password for the install media. - Asks about each setting in the recipe's own settings file, one at a time, and writes your answers to
group_vars/all.ymlandinventory.iniin that folder. - Prints the commands to run next.
It never connects to your box and never runs anything on it. Everything that later happens on the box is in the playbook, which you can read in the folder it just unpacked. The one network request the installer makes is the recipe download.
Read it first #
Piping a script into a shell is a matter of trust. You can read this one before it runs. Open https://nucarium.sh in a browser to see the script and its checksum, or download it:
curl -fsSL https://nucarium.sh -o install.sh
Try it without changing anything. This prints every action and installs, downloads and writes nothing:
sh install.sh --dry-run
Then run it:
sh install.sh
What it asks #
The questions come from the recipe itself: each setting in its group_vars/all.yml, with the note the recipe has for it and its value as the default, plus the box's name and address. Press Enter to keep the value shown. --all also asks about the settings most boxes leave alone, and you can change any of them later by editing the two files. These are the ones every box needs:
| Setting | What it is | Example |
|---|---|---|
box_name |
The box's hostname and its name on your tailnet | agentbox |
box_address |
Its address on your home network. If you do not know it yet, keep the example; you set it again after the install. | 192.168.1.50 |
operator_user |
Your own user on the box | ops |
timezone |
The box's time zone | Etc/UTC |
lan_ssh_cidr |
The home network allowed to SSH in besides Tailscale | 192.168.1.0/24 |
git_user_name, git_user_email |
The identity on agents' commits. The email must be verified on GitHub. | you@example.com |
github_org, repos |
The organisation, and the repositories to make available | your-org, web api |
nut_enabled |
Whether a UPS is plugged into the box | true |
github_app_client_id, github_app_installation_id |
From the GitHub App you create below. Press Enter to fill them in later. | Iv23example, 12345678 |
vault |
The 1Password vault that holds this box's secrets | Infra |
Sign in to 1Password's CLI before you run any playbook, or turn on the desktop app's CLI integration:
op signin
Tailscale: a tag and an auth key #
Make sure Tailscale is installed and signed in on your workstation, with MagicDNS on.
A new tailnet lets every device reach every other device. That would let an agent on the box reach your laptop and phone. In the admin console, open Access controls, define a tag for agent boxes, and replace the allow-everything rule with one that only lets people's devices start connections:
{
"tagOwners": { "tag:agent-box": ["autogroup:admin"] },
"grants": [
{ "src": ["autogroup:member"], "dst": ["*"], "ip": ["*"] }
]
}
A tagged device then accepts connections but cannot open any. If your policy already has other rules, keep them and remove only the rule whose source is *.
Then, under Settings → Keys, generate an auth key with the tag tag:agent-box, pre-approved, not ephemeral. It lets the playbook join the box to your tailnet without a browser. You put it in 1Password below.
GitHub: an app for the agents #
Agents push branches and open pull requests through a GitHub App. Pull requests show the app as their author, so you review them as yourself, and nothing on the box holds a credential that can act as you.
An organisation admin does this once per organisation.
-
Go to the organisation's Settings → Developer settings → GitHub Apps → New GitHub App.
-
Name it so its authorship is legible, for example
your-org-agent. -
Untick Active under Webhook. Leave the callback and setup URLs blank.
-
Set these repository permissions and no others:
Permission Level For Contents Read and write Cloning and pushing branches Pull requests Read and write Opening and updating pull requests Metadata Read-only (automatic) Repository lookups Checks Read-only Waiting on CI Issues, Actions Read and write, if used Issue comments, workflow dispatches -
Set it installable only on this account, and create it.
-
Note the Client ID. It starts with
Iv. -
Under Private keys, generate a key. It downloads a
.pemfile once. -
Choose Install App, install it on the organisation for selected repositories only, and note the Installation ID from the page's address (
.../installations/<id>).
Put the Client ID and Installation ID in group_vars/all.yml. They are plain configuration. Only the .pem is a secret.
Generate one private key per box. Retiring a box is then deleting its key.
The packages token #
If your repos install packages from GitHub's npm registry, the box needs one more credential, because that registry only accepts a classic personal access token. Create one at Settings → Developer settings → Personal access tokens → Tokens (classic) with the single scope read:packages. Agents can read this token, which is why it must be able to do nothing but download packages. Put a reminder in your calendar for its expiry.
Put the secrets in 1Password #
The installer printed a list of 1Password references. Create an item for each. The item names are up to you; what matters is that each reference in group_vars/all.yml points at a real field.
| Reference | What to store |
|---|---|
become_password |
Your login and sudo password on the box. Make up a strong one. |
luks_passphrase |
The disk passphrase. Make up a strong one. You type it at the box's keyboard twice during the install, and again whenever the TPM refuses to unlock. |
grub_password |
The boot-menu password. Make one up. |
tailscale_auth_key |
The auth key from Tailscale. |
github_app_pem |
The .pem file, attached to an item. Delete the download afterwards. |
npm_token |
The read:packages token. |
watch_machine_token |
Optional. A machine token from Watch, if you want the playbook to sign the box in. See above. |
Optional references, each of which switches a feature on: an Ubuntu Pro token (kernel fixes without a reboot), and the repository, password and keys for the nightly backup. Leave a reference empty to skip that feature.
Check the settings #
The installer wrote two files. Read them both once.
inventory.ini names the box and how to reach it for the first run:
[boxes]
agentbox ansible_host=192.168.1.50 ansible_user=ops
group_vars/all.yml holds everything that differs between boxes. The installer filled in what it asked about. Three parts are yours to check by hand.
The environments. An environment is one agent login running one agent server. A new box has one, called main. The name is what Watch shows, and capacity is the most sessions it runs at once:
environments:
- name: main
capacity: 12
Where the box reports. watch_target is hosted or none: Nucarium Watch, or nowhere.
watch_target: hosted
With hosted, nothing is sent until the box is signed in, and you can leave that until the box is built: signing in afterwards is one command on the box. To have the playbook sign the box in for you, add the machine in Watch now, mint a token for it, store the token in 1Password, and point secret_refs.watch_machine_token at it. With none the box reports nowhere even if it is signed in, and nucleated status on the box shows the same view.
The secret references. Every value under secret_refs is a 1Password reference, read on your workstation when a playbook runs:
secret_refs:
become_password: op://Infra/agentbox/sudo-password
luks_passphrase: op://Infra/agentbox/disk-passphrase
grub_password: op://Infra/agentbox/boot-menu-password
tailscale_auth_key: op://Infra/agentbox/tailscale-auth-key
github_app_pem: op://Infra/agentbox/github-app-private-key.pem
npm_token: op://Infra/agentbox/npm-read-packages-token
watch_machine_token: ""
Test one reference by hand. It should print the secret:
op read "op://Infra/agentbox/tailscale-auth-key"
Give the agents your working rules #
Instructions and skills are files on each machine, not part of a Claude account, so a new box starts with none of yours. Anything you put in agent-context/ inside the recipe folder is copied to the agent user.
mkdir -p ~/nucarium-box/agent-context/skills
File in agent-context/ |
Goes to | Write it for |
|---|---|---|
AGENTS.md |
~/workspace/AGENTS.md |
Every session on the box. Sessions start in folders below ~/workspace, so they read this file. |
CLAUDE.md |
~/.claude/CLAUDE.md |
Rules for this box and this company's work. Keep it short. Do not copy your personal one whole. |
skills/ |
~/.claude/skills/ |
Skills you want agents here to have. |
Two lines belong in the box's AGENTS.md. Tell agents there are no main checkouts, only bare repos in ~/workspace/.repos and session folders in ~/workspace/.worktrees. And tell them to let tools pick a free port and to name containers after their session, because sessions share the machine's ports.
Next, make the two USB sticks.