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 routine 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 |
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.