#How set-up works

• versions/<version> is a staging folder until it passes validation: package identity, native kernel loading, a real event-stream round-trip.
• Then current is re-pointed atomically and bin/rerail (re)written; the npx copy is never used again.
• An install that fails later removes the empty folders it made.
• Skipped when set-up runs from the version current points at. Once any version is installed, answer runs (--answer, --repo) and /rerail-start skip it too: OMP and Pi run those from the session's own package, which may be older than current.

• The question comes before set-up reads a repository or connects an agent. A yes also lets Rerail show the sessions' events in the dashboard.
• A yes is kept with the run's folder (--repo). Reading that folder is still asked.
• A no connects and starts nothing new, and clears an earlier yes so the next set-up asks again. Agents connected before stay until rerail install --remove. rerail stays on PATH; the screen says rerail install --remove takes it off the computer.
• rerail start in a repository not set up asks too; an update's health check does not.

• Each fit shows its rule count, why it matched and the folder it would be added in.
• The agents to connect ("Will connect to: …"; --agents names others).
• Pack rules that start off or take options from the repository's own lint config (The repository's own lint config).
• With no match, no pack is offered; the repository can still start and add packs in the dashboard later.

Set-up connects all agents found, unless --agents names others. It starts every checkout of the repository not stopped on its own, this one included.

Registrations point at ~/.rerail/current, so hooks follow an update unchanged. rerail update re-registers only agents already connected, to bring the new version's commands and skills.

• OMP: link ~/.omp/agent/extensions/rerail → current; rerail MCP server in ~/.omp/agent/mcp.json. An OMP plugin install of Rerail is left alone; the summary says to remove it.
• Pi: packages entry in ~/.pi/agent/settings.json, replacing any gallery npm:@neralabs/rerail entry but keeping its filters.
• Claude Code: hooks, status line (wrapping any you had) and sandbox and permission denies in ~/.claude/settings.json; commands in ~/.claude/commands/. Windows hooks run without Git Bash.
• Codex: hooks in ~/.codex/hooks.json (trusted once with /hooks in Codex); one skill per command in ~/.codex/skills/<name>/SKILL.md, invoked as $rerail, $rerail-manage and so on.
• Cursor: hooks in ~/.cursor/hooks.json, commands in ~/.cursor/commands/, permission denies in ~/.cursor/cli-config.json if the Cursor CLI has written that file.

• Other tools' entries are kept, though the file is rewritten as JSON indented by two spaces.
• Rerail's own entries, from any install of this package (even one that is gone), are replaced, not duplicated.
• A config that is not plain JSON (a comment, a trailing comma) is left alone. Set-up still connects the other agents and starts the repository; the summary names the file, the reason and what to do.
• A <file>.<timestamp>.bak is written only on change. Re-running is a no-op.

• The packs added by name ("TSLint in web" when added in one folder), rules on, other repositories Rerail is on in, the dashboard link (#rules, its Overview, scoped to repository and checkout), and agents that could not be connected.
• Commands show as $rerail-show-me when Codex is the only agent, and in Codex's form beside the others' when it is one of several. Once Codex's hooks are written, a line says to trust them with /hooks in Codex.
• With no agent found, it says so, names the supported ones, and says to rerun rerail setup once one is installed.
• The daemon is the active install's and serves every repository; one from another version or port is replaced (--port picks the port).
• The browser opens unless BROWSER=none, the session is over SSH, or Linux has no display.

• Set-up never turns a sandbox on or off, or changes other sandbox or permission settings.
• A Rerail home that is your home folder, or above it, is skipped, since denying it would deny every project. The cache is still denied.
• rerail install --remove takes out exactly what it added; entries you already had stay.
• Re-running set-up with another RERAIL_HOME moves the denies to it.

• Sandbox filesystem.denyRead and filesystem.denyWrite name both folders. filesystem.allowRead reopens current and versions in the Rerail home, so commands can read the installed package but no data.
• permissions.deny covers the file tools, which the sandbox does not: Edit(...) for both folders; Read(...) for the whole cache and the Rerail home's data files (*.json*, *.sqlite*, *.log*, *.lock, access-token*, active-profile*, device-secrets/, profiles/). The installed package, bin/ and packs/ stay readable: /rerail-create reads its skill there, and a deny cannot be reopened for one folder.
• sandbox.excludedCommands holds Rerail's CLI as Rerail commands run it (<node> <root>/dist/cli/cli.js *), the launcher (~/.rerail/bin/rerail *) and rerail *. These run unsandboxed under your normal permission rules: what a Rerail command pre-approves runs, anything else asks. A Rerail command with a redirect, a cd or a $(...) stays sandboxed and cannot read Rerail's files.
• Hooks, the status line and MCP servers run outside the sandbox, so Rerail's hooks are unaffected.
• The sandbox is off until you turn it on (/sandbox). While off, only the file-tool denies apply, and shell commands can read and change Rerail's data. On native Windows Claude Code has no sandbox; only the file-tool denies are written.

• Codex: no stable user setting denies a path; permission profiles can, but are in beta and replace the sandbox_mode settings. The default workspace-write sandbox lets commands write only to the workspace and temporary folders, network off: they cannot change Rerail's data but can read it, access token included.
• Cursor editor: sandbox.json can only add paths, and the editor's agent has no path deny. Sandboxed commands by default write only to the workspace and temporary folders, loopback blocked, but can read Rerail's data. "Read Access: Workspace" in Cursor's settings makes the agent ask before reading outside the workspace; it covers every path, so set-up leaves it alone.
• Cursor CLI (cursor-agent): Write(...) denies for both folders and Claude Code's Read(...) denies, for its file tools only. Written only when the CLI has written that file, and not on Windows.
• OMP and Pi have no sandbox: their agents can read and change all of Rerail's data.

• "Skip for now" (no repository) connects the agents found and starts Rerail nowhere.
• In a set-up repository, it connects the agents found since ("Now also connected" in the summary), then shows the summary, or says Rerail is stopped there.
• ~/.rerail/coding-agents.json lists every agent set-up or rerail install has seen, except one that could not be connected, so the next set-up retries it. Without the file, every agent found counts as new.

On macOS and Linux, a block between # >>> rerail >>> and # <<< rerail <<< goes into the startup file $SHELL (else the account's login shell) reads:

The block adds the directory only when PATH lacks it, so a file sourced twice adds it once. On Windows the directory is appended to the user Path (HKCU\Environment), keeping that value's registry kind. The Windows launcher is rerail.cmd, with an sh launcher rerail beside it for Git Bash, which runs neither .cmd nor .bat files by bare name.

• Ownership. Set-up records that it handled PATH in ~/.rerail/launcher-path.json; from then on PATH is yours. A block you take out stays out until rerail setup runs again. rerail update adds the entry only when that record is missing.
• When nothing changes. Set-up says what it changed. It changes nothing when the running PATH already has the directory, the entry is in place, or RERAIL_MODIFY_PATH=0. A block written for another Rerail home is replaced.
• Backup. A changed startup file keeps one <file>.rerail.bak beside it: the file before Rerail last changed it. Each change replaces it; rerail install --remove deletes it once the block is out.

The block is in the file an interactive shell reads, so zsh -c, ssh host rerail … to a zsh account, and scripts miss it. There, call ~/.rerail/bin/rerail by its full path, or add the directory to PATH yourself in a file every such shell reads (~/.zshenv for zsh).

Rerail does not write ~/.zshenv: every zsh reads it, scripts included, and on macOS /etc/zprofile reorders PATH after it. Coding agents run Rerail by its full path, so they need neither.

In the menu, ↑/↓ (or k/j) move the ❯, wrapping around; a digit moves it to that answer; Enter takes it, so 2 then Enter still works. Ctrl-C restores the terminal and stops set-up; Ctrl-D cancels it. The folder and rule-pack prompts read a typed line.

Without a terminal (stdin or stdout is not a TTY, as under a coding agent), the agent relays each question as written, with one command per answer. Answer flags:

• --answer <allow|decline|yes|other-folder|pick-myself|start|choose|not-now|folder|skip>
• --repo <folder>
• --agents <ids> (omp,pi,claude-code,codex,cursor): works on its own or with any answer; no question asks for it.
• --packs <id@version,…>: the exact versions an answer installs; a third party's pack by its package name (@acme/rerail-pack-sql@1.0.0); none for none.

Each answer run starts from what it is told, so running one twice repeats no earlier step's side effect. Claude Code's, Cursor's and Codex's /rerail-start runs rerail start --relay, and every answer command carries --relay, so an agent running commands in a terminal gets these questions, not a prompt waiting on input.

The JSON object is the only thing on stdout.

• step: sessions, read-repo, confirm-packs, pick-packs or no-repo at a question, else done, stopped, or error (exit 1).
• screen: plain text for the person.
• question: each option carries its answer key, label, detail, and the arguments that give it (next.args, starting with setup and carrying --json). An answer that needs a folder or agent ids also carries input, the value to ask for first (append [flag, value]).

rerail start --json in the home folder asks which project to start with. The side effects are the agent lane's. --database <file> names the database an extension was configured with.

In OMP and Pi, /rerail-start always runs this picker through the launcher's rerail start --json. Each question's text shows as a notice, then the question as a select (a text box for a folder or agent ids); the summary shows when set-up ends. In a set-up repository the first step starts Rerail and says so. Closing a picker stops set-up and turns nothing on. Without a UI (print mode) it shows rerail start's text. Claude Code, Codex and Cursor relay the questions as text.

Rerail reads every repository through the first git on PATH (git.exe on Windows). It skips relative entries, and entries inside the repository it runs in (the nearest folder above with a .git) or a node_modules folder, so a repository's own bin/ cannot put its git first. As a shell does, it passes over a folder named git or a git without its execute bit.

With none on PATH, it falls back to the usual install locations: Homebrew, Linuxbrew and Nix on macOS and Linux; Git for Windows and scoop on Windows. On macOS the /usr/bin/git stub counts only with the Command Line Tools or Xcode installed.

Set-up records the Node that ran it for the launcher, the hooks and the Claude Code status line. Homebrew's is recorded by the link brew upgrade keeps (/opt/homebrew/bin/node), not its versioned Cellar folder. Once the recorded Node is gone (after nvm uninstall, say), each falls back to node on PATH, except the status line on Windows.

On a Node older than 24, the CLI and the daemon stop with set-up's message, the hooks do nothing, and the status line says needs Node 24 or newer.

The commands are /rerail, /rerail-manage, /rerail-create, /rerail-start, /rerail-stop, /rerail-update, /rerail-uninstall, /rerail-help, /rerail-show-me and /rerail-bug-report ($rerail, $rerail-manage, and so on in Codex). In Claude Code and Cursor, /rerail-manage opens the dashboard as a tab in the Orca or Cursor window it runs in, else in the system browser.

After activating a version, rerail update runs that version's rerail install --refresh: each connected agent gets its commands, skills and hooks and loses retired ones; an agent never connected is left alone. Generated command files and skills are replaced without a .bak copy.

@neralabs/rerail is published only to npmjs (https://registry.npmjs.org/). Rerail adds no registry configuration: setup and rerail update run the npm next to their Node, with your normal npm configuration.

If your npm token for npmjs is invalid or expired, npm-backed commands such as rerail update report that the npm registry credentials are missing or expired; sign in again with npm login, or remove the token. Rerail redacts _authToken and _password values from any npm output it prints.

rerail update asks for the latest version from an empty temporary folder, so a repository's own .npmrc cannot choose the registry; your ~/.npmrc still applies. It installs without running any install scripts, then checks registry signatures and provenance attestations of everything installed with npm audit signatures, before running any of it.

A signature that does not verify stops the update with nothing installed. A registry that publishes no signing keys, as some private mirrors do, gets a warning naming it, and the update goes on.

• Managed installation (a package under ~/.rerail/versions/<version>/ or $RERAIL_HOME/versions/, normally loaded through current): owns the machine-wide ~/.cache/rerail/content-v1.sqlite.
• Any build from a Git checkout (source, dist/, tests, benchmarks, every worktree): <checkout>/.rerail/content-v1.sqlite (.rerail/ is gitignored), so a checkout on a newer store schema never changes the store the installed version reads.
• Neither (say, an npx copy): no store, reported on its first scan.

The file name follows the store's compatibility floor (v1 today) and changes when the floor rises.

The daemon holds an exclusive OS lock (flock / LockFileEx) on ~/.cache/rerail/main-instance.lock for its whole life, and records its pid, version, package root and start time beside it in main-instance.json. The OS drops the lock however the daemon ends, kill -9 included, so there is never a stale lock to clear.

A second main daemon can come from another $RERAIL_HOME, or be an orphan its daemon.json no longer names. rerail daemon start prints its exit message from daemon.log.

Everything else goes through the daemon, not in-process evaluation. The Claude Code, Codex and Cursor hooks, OMP and Pi sessions, and rerail events streams (in internal testing) send events to it, starting it when it is not running, after a reboot too (unless RERAIL_AUTOSTART=0). CLI commands such as rerail settings and rerail scan (in internal testing) use its API.

Any other process opening the machine-wide store gets an error and a failed policy run, not a second writer. Development builds never take the lock and never open that store.

Updates hand over without overlap. rerail update only activates the new version. The next hook or session from it stops the old daemon, waits until that process has exited and the OS has released its lock, then starts the new daemon, which takes the lock. rerail setup replaces a stale daemon the same way. A rerail events stream (in internal testing) that outlives an update sends to whichever daemon is running and never brings its own version back.

A newer Rerail that first opens the file (the daemon, rerail start, set-up, or a command, hook or status line that only reads) runs the pending migration steps in one transaction. A failing step leaves the file as it was. A process that cannot write the file gets an error naming those steps, and the file is left as it was.

Most steps add a column or a table, which older versions read correctly: the floor stays, an older Rerail still opens the file, and a hook or the status line runs such steps itself. A step an older version would misread raises the floor. It waits for the new version's daemon or a command that writes; until then a hook or the status line says to run rerail daemon start.

An update that finds nothing newer, or fails, keeps the copy from the last version change. One that changes the version but cannot take a copy removes the old one, which no longer holds the database before the now-active version.

• Unregisters everything naming this installation, leaving other tools' entries alone. Each changed file gets a <file>.<timestamp>.bak beside it. Removed:
  • harness hooks, and the Claude Code status line and commands;
  • the sandbox and permission denies set-up added to ~/.claude/settings.json and ~/.cursor/cli-config.json;
  • the Cursor commands, the Codex skill, and the OMP extension symlink and MCP entry;
  • the Pi package entry (an npm:@neralabs/rerail one too, when it removes the managed install);
  • a folder that held only what it removed: each ~/.codex/skills/rerail* (and ~/.codex/skills when those were all it held), and ~/.omp/agent/extensions when the link was all it held.
• Backs up the database: stops the daemon and moves rerail.sqlite (with its -wal/-shm) into ~/.rerail-clean-YYYYMMDD/rerail-home/ (-YYYYMMDD-HHMMSS when one from today exists).
• Removes the PATH entry set-up added from every shell startup file (or the Windows user Path).
• Deletes the installation, last: ~/.rerail/current, the launcher's ~/.rerail/bin, every version under ~/.rerail/versions with update-state.json, the rule packs in ~/.rerail/packs, and the cache ~/.cache/rerail (left alone, and said so, while another Rerail home's daemon holds it).

In bin, versions and packs it deletes only what Rerail put there. A folder that also holds other files (a Rerail home shared with them, as with RERAIL_HOME=$HOME) is kept with those files, and named.

It prints each path it removed, and what it kept in the Rerail home (settings such as consent.json, logs, records), which you can delete if you will not install Rerail again. A home that also holds other files is never offered for deletion whole; only Rerail's files in it are named.

A file it cannot remove, such as one Windows holds while a session still runs Rerail, is named with the command that finishes the job once that session is closed. The rest of the uninstall has happened, so it still exits 0.

• PowerShell: Remove-Item -LiteralPath '<path>' -Recurse -Force; for the current link, [System.IO.Directory]::Delete('<path>'), which removes the link, not what it points at.
• Elsewhere: rm -rf <path>.

• Databases: rerail.sqlite and harness.sqlite in the Rerail home, with every file named after them (-wal, -shm, journals).
• Backups: every earlier backup, ~/.rerail-clean-*.
• Session ledgers: <checkout>/.rerail/sessions of every checkout the database recorded (read before the database goes), and the checkout's .rerail when the ledgers were all it held. A checkout that no longer exists is skipped. Links are never followed: a .rerail that is a link is left alone, and a sessions link is removed as a link, never its target. Ledgers written elsewhere with RERAIL_STORAGE_ROOT are not found.
• Content cache: ~/.cache/rerail (kept while another Rerail home's daemon holds it, as above), and the file RERAIL_CONTENT_STORE_PATH names, with its sidecars, when it is set.

--delete-data only goes with the whole uninstall: with --agents, or with --root naming a checkout other than the active install, it refuses before changing anything.