nucleated
A small daemon on the box. It says the machine is alive, says what each session is doing, and tidies up after finished ones. It sends what happened, never what was said.
nucleatedWhy it exists #
A session waits on a permission prompt for six hours. A login expires. The power fails and the box never comes back. From the outside each of those looks like a quiet evening, and you find out the next time you look.
nucleated is the part of Nucarium that lives on the box and speaks for it. It is one binary, in the same repository as nucleate, run as a systemd user service under the agent user. It is open source under MIT or Apache-2.0.
What it does #
| Job | What happens |
|---|---|
| Heartbeat | Every 60 seconds it reports the machine's health (disk used, load, uptime, memory pressure) and which of its agent servers are alive. |
| Event forwarding | When a session starts, asks for you, fails or ends, a hook writes a short note to a spool folder. The daemon sends routine notes in batches and a "needs input" note at once. |
| Environment discovery | It reads the agent servers it watches from its config file and reports each as an environment. You never register an environment by hand. |
| Housekeeping | On a schedule it fetches every repo, removes finished sessions that hold nothing unsaved, and saves uncommitted work to a hidden ref on the remote. |
| Local status | nucleated status prints the view Watch would show, read on the box, with no account. |
What it will not do #
It cannot break a session. The hook that writes a note exits 0 within two seconds whatever happens. If the daemon is dead, the disk is full or the network is gone, your agent carries on and never hears about it.
It does not run your agents. Each agent server is its own systemd unit. nucleated asks systemd whether that unit is active, and that is all. Stopping or crashing the daemon ends nothing.
It cannot make a healthy box look dead on purpose. If the daemon stops, heartbeats stop, and Watch reports the silence honestly as silence: last seen at a time that keeps getting older.
It sends metadata only. Every payload is built from a short list of named fields. A prompt, a reply, a tool's input or output, a file path or a diff is never copied in, because nothing in the code can copy it. What leaves the box has the whole list.
It holds a credential that can only write. The machine token sits in a file only the agent user can read. It can report on its own machine and can read nothing back.
It does not need root. It runs as the agent user and never asks for more.
Watch, or nothing #
Signed in, the daemon reports to Nucarium Watch. Not signed in, it sends nothing anywhere, and everything else still works: it runs the housekeeping and answers nucleated status. Targets covers both.
Where to go next #
- Install it as a systemd user service.
- Configure it: the environments and the schedules.
- Register the hooks, so it knows what each session is doing.
- Connect a box if you want Watch to hear from it.