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.

On this page

Run the installer #

On your Mac or Linux computer:

Workstation
curl -fsSL https://nucarium.sh | sh

It gets this computer ready to build a box. It does not touch the box. In order, it:

  1. 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 sudo is never run on a default answer.
  2. Downloads one pinned release of the box recipe from its repository and checks its SHA-256.
  3. Unpacks it into a folder you choose. The default is ~/nucarium-box. Use one folder per box.
  4. Installs the two Ansible collections the recipe uses, and passlib, which hashes the login password for the install media.
  5. Asks about each setting in the recipe's own settings file, one at a time, and writes your answers to group_vars/all.yml and inventory.ini in that folder.
  6. 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:

Workstation
curl -fsSL https://nucarium.sh -o install.sh

Try it without changing anything. This prints every action and installs, downloads and writes nothing:

Workstation
sh install.sh --dry-run

Then run it:

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

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

Tailscale admin console, Access controls
{
  "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.

  1. Go to the organisation's Settings → Developer settings → GitHub Apps → New GitHub App.

  2. Name it so its authorship is legible, for example your-org-agent.

  3. Untick Active under Webhook. Leave the callback and setup URLs blank.

  4. 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
  5. Set it installable only on this account, and create it.

  6. Note the Client ID. It starts with Iv.

  7. Under Private keys, generate a key. It downloads a .pem file once.

  8. 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:

Workstation~/nucarium-box/inventory.ini
[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:

Workstation~/nucarium-box/group_vars/all.yml
environments:
  - name: main
    capacity: 12

Where the box reports. watch_target is hosted or none: Nucarium Watch, or nowhere.

Workstation~/nucarium-box/group_vars/all.yml
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:

Workstation~/nucarium-box/group_vars/all.yml
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:

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

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