For AI agents: this page as Markdown · llms.txt · JSON Schema

Installing Rerail

One command in your repository installs Rerail under your home folder, connects your coding agents and, once you say yes, starts Rerail there.

Details: How set-up works. Problems: Troubleshooting. From source: Developing from a checkout.

Requirements

Set-up checks these first and changes nothing if one is missing.

Platform and registry notes

When a requirement is missing, set-up stops and says what to do. Native engines ship prebuilt, so nothing is compiled on your machine. Supported and not supported has the full platform list. Registry access covers npmjs, the only registry Rerail is published to, and mirrors.

Install

Run set-up in your repository; it turns nothing on until you say yes.

sh
npx @neralabs/rerail setup

It installs Rerail under ~/.rerail, without admin rights, and asks:

  1. Read sessions? "No" stops set-up with Rerail installed and off.
  2. Read this repository? Or skip the scan and pick rule packs yourself.
  3. Start? Accept the recommended rule packs, change them, or answer "Not now".
What each question covers
  1. Asked once per computer: may Rerail read your coding agents' sessions (what you ask, what they do, the files they edit) to check them against your rules?
  2. Outside a repository it asks which folder to start with, or lets you skip; --repo <folder> names one. If you skip the scan and pick rule packs yourself, no code is read.
  3. It shows the recommended rule packs, each with why it matched, and the coding agents it will connect. "Not now" installs, connects and turns on nothing.

On yes, it connects your coding agents and starts Rerail in this repository only. Start a new coding agent session there; rerail manage opens the dashboard.

Agents, answering and relay mode

Set-up connects the coding agents it finds (Claude Code, Codex, Cursor, OMP and Pi), or only those named with --agents. It ends with a summary and a dashboard link. Open rerail manage in a new terminal.

In a terminal, answer with ↑/↓ and Enter, or type the answer's number. To have a coding agent install Rerail, ask it: it runs setup --relay and asks you each question in the session.

Running set-up again

Set-up is idempotent, so rerunning it doubles as an upgrade.

What a rerun connects

In a repository already set up, it changes nothing there. It connects only coding agents installed since set-up or rerail install last looked.

It skips agents you left out with --agents or removed with rerail install --remove --agents <id>. Name one to connect it anyway, for example npx @neralabs/rerail setup --agents codex.

What it changes on your machine

Set-up writes to three places outside the repository, and to nothing before you say yes.

Exact files and entries

Nothing in the repository, its Git metadata or the database changes before you say yes.

How set-up works lists every step, file and entry.

Other ways to install

Pi and OMP can install Rerail through their own package managers; set-up then takes over.

pi install npm:@neralabs/rerail works; Rerail is in Pi's package gallery. The next Pi session loads Rerail and says to run /rerail-start, which finishes set-up.

How the managed install takes over

/rerail-start also replaces the npm:@neralabs/rerail entry in ~/.pi/agent/settings.json, in place, with the managed install, ~/.rerail/current. Pi then loads one copy, and rerail update, not pi update, governs the version. A gallery install made after set-up is swapped the same way, by /rerail-start again or the next rerail update.

From OMP's plugins

After set-up, run omp plugin uninstall @neralabs/rerail if you used omp plugin install @neralabs/rerail, then restart OMP. Set-up cannot replace OMP's copy, so both would load; set-up and rerail update remind you while it stays.

Update

Rerail updates only when you ask; nothing polls the registry or installs a version in the background.

sh
rerail update check   # is a newer version on the channel?
rerail update         # install it; /rerail-update in a coding agent ($rerail-update in Codex)

Rerunning npx @neralabs/rerail setup also updates.

Channels and what an update does

Details: Updates.

Start and stop

Rerail is off in every repository until started there; stopping keeps your rules and history.

Unset repositories, all checkouts and the daemon

How checkouts and worktrees inherit this: Rule scoping.

Remove

Removal keeps your rules and history unless you ask to delete them.

sh
rerail rules export --output ~/rerail-rules.json   # optional: a portable copy of your rules
rerail install --remove --dry-run                  # print what would change
rerail install --remove                            # or /rerail-uninstall in a coding agent

Restart open coding agent sessions afterwards. --delete-data also deletes your database; that cannot be undone.

What removal keeps and deletes

rerail install --remove takes Rerail out of every coding agent and off PATH, backing up each file it changes and leaving other tools' entries alone. It stops the daemon and moves your database into ~/.rerail-clean-YYYYMMDD/.

It then deletes, naming each path, ~/.rerail/current, the launcher, every version, the rule packs and the cache ~/.cache/rerail.

rerail install --remove --delete-data deletes the database, its backups, the cache and the checkouts' session ledgers instead of keeping them. Nothing it deletes can be restored.

See Removing Rerail in detail.

Supported and not supported

In short: macOS, glibc Linux and Windows 11 on arm64 or x64, with Node.js 24+, for Claude Code, Codex, Cursor, OMP and Pi.

Supported
Not supported

What a coding agent can reach

A coding agent runs commands as you, so only its own sandbox can keep it out of Rerail's data.

Set-up adds denies where it can and never turns a sandbox on or off. rerail status shows whether each connected agent's tools can read Rerail's data.

Per-agent coverage

Rerail's data is ~/.rerail (the dashboard's access token, your rules and history) and ~/.cache/rerail. Set-up adds denies for both where the agent's settings have a place for them.

Settings → Coding agents in the dashboard shows the same as rerail status, for this computer, from each agent's current settings. For Claude Code, that is whether sandbox.enabled is on in your user or managed settings.

Sandbox and permission entries lists every entry.

Registry access

Rerail is published only to npmjs, as a public package, so no account or sign-in is needed.

Set-up and rerail update use your npm configuration, so a mirror or proxy in ~/.npmrc works; a repository's own .npmrc does not apply to updates. Updates covers expired tokens and signature checks.