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.
nucleatedOn 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:
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:
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. |