nucleated configuration

One TOML file says what the machine is called, which agent servers to watch, and when to tidy up. Every key is optional.

On this page

Where the file lives #

nucleated reads ~/.config/nucleated/config.toml, or the file named by the NUCLEATED_CONFIG environment variable. The daemon notices when the file changes and picks the change up by itself: there is nothing to restart. Check an edit before you rely on it:

Boxas agent
nucleated check

With no file at all the daemon runs with no environments and no target.

A complete example #

This is a box with two agent logins:

Boxas agent~/.config/nucleated/config.toml
machine = "agentbox"
target = "hosted"

[heartbeat]
interval = "60s"

[[environment]]
name = "client-a"
root = "/home/agent/workspace"
unit = "agent-server@client-a.service"
agent = "claude-code"
config_dir = "/home/agent/.claude"

[[environment]]
name = "client-b"
root = "/home/agent/workspace-b"
unit = "agent-server@client-b.service"
agent = "claude-code"
config_dir = "/home/agent/.claude-client-b"

[housekeeping]
refresh = "hourly"
cleanup = "weekly"
snapshot = "hourly"
cleanup_min_age = "7d"

[spool]
max_age = "7d"
max_events = 10000

Most of that is the defaults written out. The smallest useful file is one [[environment]] with a name and a root.

Top level #

Key Default Meaning
machine The hostname The name suggested for this box when you sign it in to Watch. You can change it when you approve the sign-in.
target See below Where to report: "hosted" or "none".

Leave target out and the daemon does the obvious thing: it reports to Watch once the box is signed in, and to nothing until then. Set target = "none" to keep a signed-in box from sending anything. Targets covers both.

[heartbeat] #

Key Default Meaning
interval "60s" How often to report.

Watch answers every heartbeat with the interval your account expects, and the daemon uses the longer of that and this. On the free plan Watch asks for five minutes, whatever this file says, because a faster heartbeat is one of the things the paid plans pay for. Deadlines explains what follows from the interval.

[[environment]] #

One table per agent server on the box. The double brackets are TOML for "a list of these".

Key Default Meaning
name Required The environment's name on the box and its first label in Watch: lower-case letters, digits, ., _ and -, at most 64 characters, unique on this machine.
root Required The nucleus this agent server works in.
unit agent-server@<name>.service The systemd user unit that runs the agent server. The server counts as alive while this unit is active.
check None Instead of unit: a command that exits 0 while the agent server is alive. For a box with no unit to ask.
agent "claude-code" Which agent runs here.
config_dir ~/.claude That login's own agent config folder. It is how a hook knows which environment it belongs to when several logins share one user.
github_token_file nucleate's setting A file holding a GitHub token for this environment's merged-pull-request checks.
branch_prefix nucleate's setting The prefix of this environment's session branches.

You never register an environment in Watch. It appears there the first time a heartbeat names it.

Renaming an environment here makes a new environment in Watch, because the name is how Watch knows it. To change only what the console shows, rename it in the console and leave this file alone.

Removing a table stops the daemon reporting that environment. Watch then treats its agent server as not alive, and after the usual deadline shows it as down, until you delete it in the console.

The daemon asks whether an agent server is alive. It never starts, stops or restarts one.

[housekeeping] #

Key Default Meaning
refresh "hourly" Fetch every repo in every nucleus and drop branches deleted on the remote.
cleanup "weekly" Remove finished sessions that hold nothing unsaved.
snapshot "hourly" Save each session's uncommitted work to a hidden ref on the remote.
cleanup_min_age "7d" A session that has changed more recently than this is never cleaned up.

Each schedule takes "hourly", "daily", "weekly" or "off". Housekeeping says exactly what each job touches.

[spool] #

Key Default Meaning
dir ~/.local/state/nucleated/spool Where notes wait to be sent.
max_age "7d" A note older than this is dropped unsent.
max_events 10000 The most notes the spool will hold.

See The spool.

[watch] #

You do not need this table. nucleate login records where the box signed in, and the daemon uses that.

Key Default Meaning
token_file ~/.config/nucleated/token Where the machine token is kept.
url None A Watch API on this same machine, for people developing Nucarium. Plain http is refused for any other host.

Durations #

A duration is a number and a unit: "45s", "10m", "6h", "7d".

Environment variables #

Variable Meaning
NUCLEATED_CONFIG Use this config file instead of the default.
XDG_CONFIG_HOME Moves the config file, the token and login.json.
XDG_STATE_HOME Moves the spool and the daemon's own records.

Files the daemon keeps #

Its credential lives beside the config. nucleate login writes both files; you never edit them:

File Mode Holds
~/.config/nucleated/token 600 The machine token and nothing else.
~/.config/nucleated/login.json 600 No secret: the API address, the machine's id and name, the account's name, and when the box signed in.

Neither nucleate nor nucleated will use a token file that its group or anyone else can read. They say so, and behave as if the box were not signed in. Housekeeping and local status carry on.

Everything else is under ~/.local/state/nucleated/, readable by the agent user only:

Path Holds
spool/<event_id>.json One note waiting to be sent.
spool/rejected/ Notes Watch refused for good.
sessions/<environment>/<session_id>.json What the box knows about each session: status, since when, repos, branch. nucleated status reads these.
daemon.json The last heartbeat, what has been sent, and when each housekeeping job last ran.