Day to day
The things you do with a box once it is built, each with the command or the click that does it. Keep this page.
Build a boxOn this page
- Start or steer an agent
- Hear when a session needs you
- Work from Claude Desktop
- Use a plain terminal
- Look at what an agent built
- Make another repo available
- Resume a finished session's work
- Clear out old sessions
- Keep the repos current
- Allow agents another website
- Restart the agent server
- Add a second login
- Update the recipe
- Rebuild the box, or build another
- Two things not to do
Start or steer an agent #
Open claude.ai/code or the Claude phone app, signed in as the box's account, and start a session on agentbox.
Each new session starts in an empty folder. Tell it which repos it needs in your first message ("include web and the API") and it adds them. Up to 12 sessions run at once; that ceiling is agents_capacity in your settings. All of them share the login's usage limits.
A new worktree has no installed dependencies. The agent installs them itself in each repo it adds.
Hear when a session needs you #
That is what Watch is for. A box that reports to Watch tells you once when a session has been waiting on you, and once when the box itself goes dark.
If the box is not signed in yet, sign it in. It prints a short code to approve on your phone:
nucleate login
With no Watch account, the same view is on the box:
nucleated status
Work from Claude Desktop #
Desktop can run a session on the box over SSH while you sit at your workstation. Give it a session folder of its own first, so its work has its own branch and the same cleanup rules as every other session:
ssh agentbox-agent 'nucleate create-session desk web'
Then, in Desktop's Code tab, add an SSH environment for agentbox-agent and pick the folder /home/agent/workspace/.worktrees/desk.
Two things differ from a session started from your phone. It runs under the account Desktop is signed in to, not the box's login. And Desktop has to keep renewing its sign-in, so keep the workstation awake for a long task. For work that should survive a closed laptop, start it from the phone or claude.ai/code.
Use a plain terminal #
ssh agentbox-agent
Then run claude in a session folder.
Look at what an agent built #
The firewall lets your tailnet in. A dev server started with --host 0.0.0.0 is reachable from your workstation or phone at http://agentbox:<port>.
Sessions share the machine's ports. Two that each start a dev server on a fixed port collide, which is why the box's AGENTS.md should tell agents to let tools pick a free port.
Make another repo available #
A repo is available to sessions when its bare clone exists in the nucleus. There are two ways to add one.
Through the recipe, so a rebuild includes it. Add the repo to repos in group_vars/all.yml, add it to the GitHub App's selected repositories, then:
cd ~/nucarium-box && ansible-playbook site.yml --tags workspace
Directly on the box, for a quick addition. The app still has to be installed on the repo.
nucleate clone https://github.com/your-org/docs.git
Either way there is no server restart. The next session's list_repos sees it.
Resume a finished session's work #
A finished session's folder is gone, but its work is on the remote branch workspace/<name> and in its pull request. Start a new session and ask it to add the repo on that branch. It resumes the branch where it was pushed.
Clear out old sessions #
Nothing to do, most of the time. nucleated removes a session's folder once the session has ended and nothing in it is unsaved. See Housekeeping.
A session folder that outlives its session is a to-do, not litter: something in it is uncommitted, or committed and neither pushed nor part of a merged pull request. To see what:
nucleate status --session fix-login
Deal with what it names, then remove the session:
nucleate remove-session fix-login
Keep the repos current #
Nothing to do. Every add_repo fetches first, and nucleated fetches every repo hourly and drops branches deleted on GitHub. A long-running session still has to git fetch before it rebases.
Allow agents another website #
Commands in a session can reach only the sites on the sandbox's list. For a one-off, approve the prompt. For a site agents need regularly, add it to allowedDomains in roles/claude/files/settings.json in the recipe folder, then:
cd ~/nucarium-box && ansible-playbook site.yml --tags claude
Restart the agent server #
Restarting ends the sessions that server is running, so pick a quiet moment.
systemctl --user restart agent-server@main.service
To look at the server's own screen (Ctrl+B then D leaves it running):
tmux -L agent-main attach
The playbook never restarts an agent server for you, for the same reason.
Add a second login #
Each login on the box is an environment: one more agent server, with its own entry in Watch. Logins on one box share the nucleus, the GitHub App and its tokens, so they should all work for the same company. A different company gets its own box.
-
Add the environment to your settings, with a config folder of its own:
Workstation~/nucarium-box/group_vars/all.yml environments: - name: main capacity: 12 - name: second config_dir: /home/agent/.claude-second capacity: 6 -
Apply it:
Workstation cd ~/nucarium-box && ansible-playbook site.yml --tags claude,workspace,agent_servers,day2 -
Sign in under the new config folder, and authorise its connectors with
/mcp:Boxas agent CLAUDE_CONFIG_DIR=/home/agent/.claude-second claude -
Start that server once by hand to answer its two prompts, stop it with
Ctrl+C, then hand it to systemd:Boxas agent cd ~/workspace && CLAUDE_CONFIG_DIR=/home/agent/.claude-second claude remote-control --spawn worktree --no-create-session-in-dir --no-chromeBoxas agent systemctl --user start agent-server@client-b.service
The new environment appears in nucleated status, and in Watch the first time a heartbeat names it.
Update the recipe #
The box keeps itself patched: security updates install daily, Tailscale updates itself, and Claude Code follows its stable channel.
To move to a newer release of the recipe, run the installer again and give it the same folder:
curl -fsSL https://nucarium.sh | sh
It asks before replacing the recipe's files and keeps your two settings files as they are. The new release's default settings go in .nucarium/defaults/ so you can compare them with yours. Then see what would change on the box before changing it:
cd ~/nucarium-box && ansible-playbook site.yml --check --diff
Rebuild the box, or build another #
A rebuild is the pages from Make the two USB sticks to Sign in and start the agents again, with the same recipe folder. Work that was pushed is on GitHub. Uncommitted work that nucleated snapshotted is on the remote under refs/wip/; Housekeeping says how to get it back.
Another box gets its own folder. Run the installer with a different one:
curl -fsSL https://nucarium.sh | sh -s -- --dir ~/nucarium-box-2
Generate a new private key for the GitHub App, so each box has its own.
Two things not to do #
When something goes wrong, Troubleshooting is organised by what you see. To understand or check one part of the box, go on to What the playbook does.