nucleate configuration

nucleate needs to know one thing, where the nucleus is, and it can usually work that out. Two more settings name the session branches and let it ask GitHub about private repositories.

On this page

Where the nucleus is #

Every command needs the nucleus root. nucleate takes it from the first of these that is set:

  1. The --root <path> option.
  2. The NUCLEATE_ROOT environment variable.
  3. root in the config file.
  4. The nearest folder at or above the current one that contains a .repos folder.

The last step is why commands run inside a session, or anywhere inside the nucleus, need no configuration at all. The config file matters for commands run from elsewhere: a timer, a script, or nucleate status --session fix-login from your home folder.

If nothing is found:

Output
nucleate: no workspace root: pass --root, set NUCLEATE_ROOT, set `root` in the config file, or run inside a folder that contains .repos

If the root that was found is not a folder:

Output
nucleate: workspace root is not a directory: /home/agent/work

The config file #

The file is ~/.config/nucleate/config.toml. nucleate init writes it; you can also write it by hand. Every key is optional, and a missing file is not an error.

Boxas agent~/.config/nucleate/config.toml
# The nucleus: the folder holding .repos, .worktrees and .seeds.
root = "/home/agent/workspace"

# A file holding a GitHub token, for the merged-pull-request check on
# private repositories.
github_token_file = "/run/agent-tokens/github"

# Session branches are named <branch_prefix>/<session>.
branch_prefix = "workspace"
Key Default Meaning
root None The nucleus root. Used when neither --root nor NUCLEATE_ROOT is set.
github_token_file None A file whose contents are a GitHub token. Read each time the token is needed, so a file that is rewritten with a fresh token keeps working.
branch_prefix workspace The first part of every session branch. The session fix-login works on workspace/fix-login.

Changing branch_prefix affects sessions created afterwards. A session that already exists keeps the branch recorded in its manifest.

A file that is not valid TOML stops every command, with the file and the position of the mistake:

Output
nucleate: parsing /home/agent/.config/nucleate/config.toml: TOML parse error at line 1, column 8

Where the file is looked for #

Order Location
1 The file named by NUCLEATE_CONFIG.
2 $XDG_CONFIG_HOME/nucleate/config.toml, when XDG_CONFIG_HOME is set.
3 ~/.config/nucleate/config.toml.

Environment variables #

Variable Meaning
NUCLEATE_ROOT The nucleus root. Beats the config file; loses to --root.
NUCLEATE_CONFIG The config file to read, in place of the default location.
NUCLEATE_GITHUB_TOKEN_FILE The token file. Beats github_token_file in the config file.
GH_TOKEN, GITHUB_TOKEN A GitHub token itself. See below.

The GitHub token #

nucleate asks GitHub one question: is this commit the head of a merged pull request? It is part of the safety rule, and it is what lets a squash-merged session clean up after itself.

For a public repository the question needs no token. For a private one it does. The token is taken from the first of these that has a value:

  1. The GH_TOKEN environment variable.
  2. The GITHUB_TOKEN environment variable.
  3. The file named by NUCLEATE_GITHUB_TOKEN_FILE, or by github_token_file in the config file.

The token only needs to read pull requests on the repositories in the nucleus. nucleate does not use it for anything else: cloning, fetching and pushing are done by git with git's own credentials.

If there is no token, or the token is wrong or expired, nothing breaks. GitHub's refusal counts as "not merged", and the worktree in question is kept.

On a box built with the recipe #

The box recipe writes this file for the agent user:

Boxas agent/home/agent/.config/nucleate/config.toml
root = "/home/agent/workspace"
github_token_file = "/run/agent-tokens/github"
branch_prefix = "workspace"

/run/agent-tokens/github holds a short-lived token that the box replaces every 20 minutes. Because nucleate reads the file each time, it always has a current one. Agent sessions on the box also have GH_TOKEN set from the same file, which takes precedence and comes to the same thing.

Check what nucleate sees:

Boxas agent
nucleate available

If that lists your repos from any folder, the root is configured. If it works only inside ~/workspace, the config file is missing or has no root.