Install nucleated
Put the binary in place, write a config file, and run it as a systemd user service so it starts at boot and stays out of the way.
nucleatedOn this page
Before you start #
You need a Linux box where your agents run as their own user. These pages call that user agent and the box agentbox. If you built the box with the recipe, the playbook has already done everything on this page and you can skip to checking it.
nucleated needs git and a nucleus for the same user, because the housekeeping jobs work on it. The daemon runs as the agent user, never as root.
Install the binaries #
nucleated ships in the same release archive as nucleate. Install nucleate shows the download and the checksum; unpack both binaries onto the agent user's path:
mkdir -p ~/.local/bin
tar -xzf nucleate-v0.3.0-x86_64-unknown-linux-musl.tar.gz -C ~/.local/bin nucleate nucleated
nucleated --version
The binaries are static: there is nothing else to install.
Write the first config #
nucleated init writes a config file with one environment. It asks nothing; you tell it what it needs:
nucleated init --env client-a --root /home/agent/workspace
{
"config": "/home/agent/.config/nucleated/config.toml",
"created": true
}
--env is the environment's name, the one Watch will show. --root is its nucleus. Two more flags cover the rest: --unit names the systemd unit that runs the agent server (it defaults to agent-server@client-a.service), and --config-dir names that login's agent config folder (it defaults to ~/.claude).
If the file already exists, init leaves it alone and prints "created": false. A box with more than one agent login needs a second [[environment]] table, which you add by hand: Configuration explains every key.
Run it as a service #
The daemon prints its own unit file:
mkdir -p ~/.config/systemd/user
nucleated unit > ~/.config/systemd/user/nucleated.service
[Unit]
Description=nucleated: heartbeat, session events and housekeeping for this box
Documentation=https://nucarium.dev
[Service]
Type=simple
ExecStart=%h/.local/bin/nucleated run
Restart=always
RestartSec=5
NoNewPrivileges=yes
[Install]
WantedBy=default.target
Enable it and start it:
systemctl --user daemon-reload
systemctl --user enable --now nucleated.service
A user service stops when its user logs out, unless lingering is on. Turn it on once, as a user with sudo:
sudo loginctl enable-linger agent
From now on the daemon starts at every boot, before anyone has logged in.
Check it #
nucleated check reads the config, looks at each thing it names, and prints what it found as JSON:
nucleated check
{
"checks": [
{
"detail": "/home/agent/.config/nucleated/config.toml",
"name": "config",
"ok": true
},
{
"detail": "not signed in; nothing is sent. nucleate login signs this box in",
"name": "token",
"ok": true
},
{
"detail": "/home/agent/workspace",
"name": "client-a: nucleus",
"ok": true
},
{
"detail": "unit agent-server@client-a.service does not exist",
"name": "client-a: agent server",
"ok": false
}
],
"ok": false
}
It exits 0 when everything passes and 1 when anything fails. Each entry's detail says what it found, and for a failing entry what is wrong: here the agent server's unit has not been created yet. On a box that is signed in to Watch it also sends one heartbeat and reports whether Watch accepted it.
Then look at the daemon itself:
systemctl --user status nucleated.service --no-pager
journalctl --user -u nucleated.service -n 20 --no-pager
What to do next #
The daemon is running and reporting to nobody. That is a complete setup: nucleated status works, and the housekeeping runs on schedule. Two more steps make it more useful:
- Register the hooks, so the daemon knows what each session is doing and not only that the agent server is up.
- Sign the box in to Watch, so you hear about it when you are not looking.
Upgrade or remove it #
To upgrade, replace the two binaries with those from a newer archive and restart:
systemctl --user restart nucleated.service
Restarting the daemon does not touch a running session. Notes written while it was stopped wait in the spool and are sent when it comes back.
To remove it, sign the box out (nucleate logout), stop and disable the unit, and delete the unit file, the binary, ~/.config/nucleated and ~/.local/state/nucleated. Take the hooks out of the agent's settings file as well: they do no harm without the daemon, but they have nothing left to talk to.
systemctl --user disable --now nucleated.service