Connect a box to Watch
Sign the box in from your phone, watch its first heartbeat arrive, and say where alerts should go. About ten minutes, and nothing on the box changes how your agents work.
WatchOn this page
What you need #
- A Linux box that runs your agent sessions, and a shell on it as the user they run under. These pages call that user
agent. - A Nucarium account. Sign in with GitHub and you have one, with an organisation of your own; the first environment is free and needs no card.
If the box was built with the recipe, nucleate and nucleated are already installed and running. Skip to Sign the box in.
Install the two tools #
On a box you set up yourself, three short pages get you there:
- Install nucleate, which also gives you the
nucleatedbinary. - Install nucleated as a service.
- Register the hooks, so Watch hears what each session is doing.
Sign the box in #
A box has no browser, so you approve the sign-in on your phone or laptop. On the box:
nucleate login
It prints an address and a short code, drawn large enough to read across a room, and waits:
Sign this box in to Nucarium Watch
On your phone or laptop, open
https://app.nucarium.com/activate
and enter this code:
WDJB-MJHT
Or open this link, which already carries the code:
https://app.nucarium.com/activate?user_code=WDJB-MJHT
Waiting for you to approve. The code lasts 15 minutes. Ctrl-C cancels.
Open the address, sign in to Watch if you are not already, and enter the code. Watch asks which machine this is: pick one you have already added, or name a new one. The name it suggests is the box's hostname. Approve.
The box says what was just granted, in one line:
agentbox can now report to Your Org. It can read nothing.
That line is the whole of the permission. The box now holds a machine token: it can report on this one machine, and it can read nothing back, from this machine or any other. It is stored at ~/.config/nucleated/token, readable by the agent user only, and no command ever prints it.
See the first heartbeat #
The daemon notices the token within a few seconds and sends a heartbeat. In Watch, the machine changes from pending to online, and each environment in the daemon's config appears under it. You did not register them: an environment exists from the first heartbeat that names it.
From the box, the same thing in one command:
nucleated check
Its output has one entry per thing it checked. On a signed-in box one of them is the heartbeat it just sent, and whether Watch accepted it. Or ask who the box is signed in as:
nucleate whoami
{
"account_name": "Your Org",
"api_url": "https://api.nucarium.com",
"logged_in": true,
"logged_in_at": "2026-11-19T02:40:12.000Z",
"machine_id": "mac_7h2k9m4q1x8z5b6n",
"machine_name": "agentbox",
"scope": "ingest",
"token": "valid",
"token_file": "/home/agent/.config/nucleated/token"
}
Then start a session from your phone the way you always do. It shows up in the inbox as Working, and as Idle when the turn ends.
Say where alerts go #
Watch can show you everything and still be no use at three in the morning unless it can reach you. Add at least one alert destination in the console: Alerts walks through it, and its test button sends a sample so you know it arrives.
Add the link to your vendor's app #
Watch never acts on a session. When one needs you, you answer in the agent vendor's own app. Each environment can carry one link there: open the environment in the console and set its link to the address you use for that login. It then sits beside every session in that environment, one tap from the alert.
A box with nobody at it #
nucleate login needs a person. To set up a box without one, mint a token in the console (open the machine, then its tokens, and add one) and pipe it in:
printf '%s' "$TOKEN" | nucleate login --token-stdin
The token is shown once, when it is minted. --token-stdin stores it without contacting Watch. This is what the box recipe does, with the token read from your password manager.
More than one box, more than one login #
Each box signs in once and becomes one machine. Sign the next box in the same way and it appears beside the first.
Each agent login on a box is an environment: one [[environment]] table in the daemon's config file. Add the table and the environment appears in Watch at the next heartbeat. Your plan sets how many machines and environments an account shows; Plans and limits has the numbers and says what happens beyond them.
Rotate or revoke the token #
To rotate it, sign in again. The new token is stored first, then the old one is revoked:
nucleate login
To take a box out of Watch, sign it out. The token is revoked at Watch and deleted from the box:
nucleate logout
If the box is gone or you cannot reach it, revoke its token in the console instead: open the machine and its tokens. A revoked token stops working at once.
| Exit code | From | Means |
|---|---|---|
| 0 | Any | Done. |
| 1 | Any | Watch could not be reached, or a file could not be written. |
| 3 | login |
You denied the request in the console. |
| 4 | login |
The code expired before anyone approved it. |
| 5 | whoami |
This box is not signed in. |
| 6 | whoami |
Watch rejected the stored token. |
What you have now #
A box that says it is alive once a minute, sessions that say when they start, stop and need you, and one place that notices when any of that goes quiet. Next: what the inbox shows.