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.

On this page

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:

Boxas agent
nucleate login

With no Watch account, the same view is on the box:

Boxas agent
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:

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

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

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

Boxas agent
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:

Boxas agent
nucleate status --session fix-login

Deal with what it names, then remove the session:

Boxas agent
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:

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

Boxas agent
systemctl --user restart agent-server@main.service

To look at the server's own screen (Ctrl+B then D leaves it running):

Boxas agent
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.

  1. 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
    
  2. Apply it:

    Workstation
    cd ~/nucarium-box && ansible-playbook site.yml --tags claude,workspace,agent_servers,day2
    
  3. Sign in under the new config folder, and authorise its connectors with /mcp:

    Boxas agent
    CLAUDE_CONFIG_DIR=/home/agent/.claude-second claude
    
  4. 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-chrome
    
    Boxas 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:

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

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

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