Build a box

A box is a small computer that stays on, runs your coding agents around the clock, and comes back by itself after a power cut. These pages take you from bare hardware to a first session started from your phone.

On this page

What you end up with #

One mini PC in a closet, built the same way every time by an Ansible playbook called the box recipe. When you finish:

  • Agents run as their own user, agent, with no sudo and none of your credentials. Nothing on the box can act as you on GitHub.
  • The disk is encrypted and unlocks from the TPM, so the box restarts unattended.
  • The box is reachable only over Tailscale, and it can accept connections but cannot open any to your other devices.
  • Every command an agent runs is confined by Claude Code's sandbox to its session folder and a list of allowed sites.
  • One agent server per login starts at boot, waits for the internet and restarts itself. You start and steer sessions from your phone or laptop.
  • Each session gets its own folder from nucleate, holding only the repos it asked for.
  • nucleated reports what each session is doing, keeps the repos fresh, clears out finished sessions and saves work in progress.
  • A UPS shuts the box down cleanly when the battery runs low and powers it back on when the mains returns.

The playbook does almost all of it. These pages cover the playbook and the parts only you can do: accounts and secrets, the hardware, booting the installer, signing in, and the tests that prove each recovery path.

The supported build #

The recipe is written for Ubuntu Server 26.04 LTS on an x86_64 mini PC. The reference build is an ASUS NUC. Other distributions and arm64 boards are community-supported: the playbook is plain Ansible and most of it carries over, but only the Ubuntu build is tested.

What you need #

Hardware #

Part What to get
Mini PC An x86_64 mini PC with a TPM 2.0 and Secure Boot. The reference build is an ASUS NUC with two memory slots and two M.2 slots.
Memory 64 GB runs about twelve sessions at once. One 64 GB DDR5 SODIMM leaves the second slot free.
Storage A 2 TB NVMe SSD. A session's folder takes 1 to 7 GB once its dependencies are installed.
UPS A USB HID UPS that NUT supports, with enough outlets for the box, your router and your modem.
For the install only Two USB sticks (one of 8 GB or more, one of any size; both are wiped), an HDMI monitor, a USB keyboard, an Ethernet cable, a small screwdriver.

A box with no UPS works. Set nut_enabled: false and skip the UPS steps; it still restarts after a power cut, it just does not shut down cleanly first.

Accounts #

Account Why
A Claude subscription that includes Remote Control The agent server signs in with it. Remote Control needs a claude.ai subscription sign-in; an API key does not work. On a Team or Enterprise plan an Owner turns Remote Control on first.
GitHub, with an organisation admin to hand Agents push and open pull requests through a GitHub App that an admin creates once per organisation.
Tailscale The only way in to the box.
1Password The playbook reads every secret from it on your workstation as it runs. Nothing secret is stored in the recipe folder.
Nucarium Watch (optional) To hear from the box when an agent needs you. You can connect it now or later, or not at all.

A workstation #

A Mac or a Linux computer. The playbook runs there and reaches the box over SSH. On Windows, use WSL with Ubuntu.

The order of the work #

Do the pages in order. Each one ends with something you can check.

Page What happens About how long
Prepare your workstation One command fetches the recipe and fills in its settings with you. You create the accounts and secrets it points at. An hour, most of it in other people's admin consoles
Make the two USB sticks An installer stick and a settings stick. 15 minutes
Assemble the box and set the firmware UPS, memory, SSD, four firmware settings. 30 minutes
Install Ubuntu An unattended install. You type one word. 20 minutes
Run the playbook Everything else, from one command. 30 to 45 minutes, mostly waiting
Sign in and start the agents The sign-ins and first answers that need a person. 15 minutes
Prove it works A session from your phone, then a pulled plug. 30 minutes, after the UPS has charged for 8 hours

After that, Day to day is the page you come back to, and What the playbook does explains each part for when you want to check or change one.

Start with Prepare your workstation.