Paths & Credentials

Configuration tiers

NEXUS's configuration lives under a .chainabit/ directory, resolved across four tiers. Later tiers win when the same setting is defined in more than one:

Order	Tier	Location
1	Built-in defaults	shipped with NEXUS
2	Organization policy	distributed by an organization
3	Project-local	.chainabit/ in the project
4	Personal	~/.chainabit/

NEXUS's own files live under .chainabit/nexus/, inside that same tiered tree.

Credential file naming is load-bearing

.chainabit/ is a committed, team-shared directory — most of what lives in it is meant to be checked in and reviewed like any other project file. The shipped ignore rules exclude only files matching *.local.*. That has a direct consequence:

A file holding a secret must be named *.local.json, and is created with owner-only permissions. This is not a style preference. A credential file that doesn't carry the .local. infix is not excluded by the shipped ignore rules, and will be committed to shared history the next time someone runs a executable workflow git add.

File	Holds	Lifecycle
.chainabit/nexus/agent.local.json	agent credentials	rewritten during normal operation; removed when the session closes
.chainabit/nexus/server.local.json	server credentials	rewritten during normal operation; removed when the session closes
.chainabit/nexus/mcp.local.json	MCP session credentials	rewritten during normal operation; removed when the session closes

The work-management store

Work management has one file, and it is per machine, not per workspace and not per project:

Path	Holds
~/.chainabit/nexus/work-management.json	Every project, board, stage, card, work item, and relation the Work destination shows

Three consequences follow from that one line:

• It carries no credential, so it carries no .local. infix. It is ordinary data, and a user who keeps their .chainabit/ tree in version control can track it like any other file.
• It is not scoped to a project folder. Unlike pinned rules and memory exports, which live in the project's own committed .chainabit/ directory, the work-management store sits in the personal tier and is shared by every workspace on the machine. Selecting a project inside the Work destination narrows what you are looking at; it does not move where the data is kept.
• It is the only authority. Nothing replicates it to a Chainabit account or to a second machine, and no setting turns that on — see Local-first. Two machines means two independent stores.

Telemetry files

When the optional telemetry setting is present in your version, its two off-by-default categories keep everything they work with under one directory in the personal tier:

~/.chainabit/nexus/telemetry/

Path	Holds
analytics/seg-*.jsonl, diagnostics/seg-*.jsonl	Queued events waiting to be sent, one per line; deleted when the category is turned off
sent.local.jsonl	The last 200 events sent, for the in-app Queued & sent data view
tickets.local.json	Deletion requests until the service acknowledges them, then 30 days more
epochs.json	When each category was turned on; nothing produced before that moment is sent
policy.json	The last policy received from the telemetry service
launch-marker.json	Written only while a category is on, so the next launch can tell a clean exit from a crash
crash/	Crash and hang reports awaiting processing, only while crash & error reports are on
.lock	Ensures one NEXUS process at a time writes here

The directory does not exist until a category has been turned on at least once, and it is created owner-only like a credential directory. Two files carry the .local. infix and are therefore excluded from version control by the shipped ignore rules: a deletion request holds the discarded upload token until the service acknowledges it, and the sent-events ring is personal to this machine. Nothing under this directory is read by any other feature. See Privacy & Diagnostics for what the files contain and how to inspect them from Settings.

Writes into a project when you link an agent

Linking an agent to a terminal — by dropping the agent onto the pane, or with Import here — writes into that terminal's working directory. That directory is yours, so NEXUS asks first: a preview names every destination and shows the exact text going into it, and nothing reaches disk until you choose Import.

Path	Written	Kind
.chainabit/agents/<agent>.md	always	new file
.chainabit/nexus/agents/<terminal>/imported/	on an import (not a bare link)	new file
.chainabit/teams/<stem>.json	when a local team is created or its membership changes	new file, then edited in place
A provider's own agent directory	only when Write provider files into project is on	new file
An existing CLAUDE.md or AGENTS.md	when mesh messaging is on and one of these files already exists	edited in place

A local team's definition is a file like any other, and it sits in the committed part of the tree: .chainabit/teams/<stem>.json holds the team's objective, its policies, and its member roster, so a team you create is shared with everyone who has the repository. The file stem is taken from the team name, which makes the name load-bearing — renaming a team writes a new file rather than moving the old one.

The last row of the table above is the one the preview calls out first. NEXUS appends a block describing the mesh messaging tools between <!-- nexus:mesh-tools:start --> and <!-- nexus:mesh-tools:end --> markers; re-linking replaces that block rather than adding a second one. No file is created for it — if neither file exists, nothing is appended.

Declining leaves the directory byte-identical. Nothing is written and then rolled back: the preview is built without touching the filesystem, so a refusal has nothing to undo.

Remembering a decision

The preview offers Don't ask again for this project. Ticking it records the paths you accepted, for that project only.

The grant is scoped to those paths, not to the project as a whole. If the set of files a link would write later grows — turning on Write provider files into project adds one file per provider — NEXUS asks again, because those destinations were not on screen when you accepted. A link that would write fewer files than you already accepted does not re-ask.

There is no setting that suppresses the preview everywhere. A project with no recorded decision is always asked.

Permissions

A credential file is created readable and writable by its owner only. The directory holding it is created owner-only as well — readable, writable, and listable by nobody else — rather than inheriting the usual, world-readable default. The file's own permissions already keep the contents private; restricting the directory means the names of the files in it are private too, so nothing there can be enumerated by another account on the same machine.

Why not an environment variable

A capability token never travels in an environment variable — it lives only in one of the files above. Environment variables are inherited by every child process a session spawns; a token placed there is implicitly handed to every command the agent runs, indefinitely, with no way to scope it back down afterward. A file with owner-only permissions is not inherited by anything that isn't explicitly given a path to it.