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.

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

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

Boxas agent
nucleated init --env client-a --root /home/agent/workspace
Output
{
  "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:

Boxas agent
mkdir -p ~/.config/systemd/user
nucleated unit > ~/.config/systemd/user/nucleated.service
Boxas agent~/.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:

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

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

Boxas agent
nucleated check
Output
{
  "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:

Boxas agent
systemctl --user status nucleated.service --no-pager
Boxas agent
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:

  1. Register the hooks, so the daemon knows what each session is doing and not only that the agent server is up.
  2. 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:

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

Boxas agent
systemctl --user disable --now nucleated.service