#Troubleshooting

The suggested upgrade matches how Node was installed:

Ubuntu 24.04's nodejs package is Node 18; NodeSource has Node 24. npm prints npm warn EBADENGINE Unsupported engine lines before set-up's message; they mean the same.

Until Rerail's first stable release, npm may stop sooner. Both of these errors mean install Node 24:

• npm 10 (Node 20 and 22): npm error notarget No matching version found for @neralabs/rerail@*.
• engine-strict=true in ~/.npmrc: npm error code EBADENGINE.

Rerail's Linux engines need glibc 2.28 or newer, like Node 24's own builds. Every distribution Node 24 runs on has it: Debian 10+, Ubuntu 20.04+, RHEL 8+ and rebuilds, Amazon Linux 2023, Fedora, and the default node:24 and node:24-slim images. Amazon Linux 2, Ubuntu 18.04 and CentOS 7 are too old.

Other reasons:

• musl (node:24-alpine): this Linux uses musl (Alpine, for example), and Rerail needs glibc. Rerail ships only glibc engines for Linux; use a glibc image such as node:24-slim.
• No engine (FreeBSD, 32-bit ARM): Rerail has no engine for <system> on <processor>.

The suggested install command fits the system:

• Linux: apt-get, dnf, pacman or zypper, without sudo as root.
• macOS: xcode-select --install.
• Windows: winget install --id Git.Git -e.
• Elsewhere: your package manager, or https://git-scm.com.

Rerail tries the first git on PATH (git.exe on Windows), then the locations listed. On Windows it also tries C:\Program Files\Git\cmd, C:\Program Files (x86)\Git\cmd, ~\AppData\Local\Programs\Git\cmd (per-user Git for Windows) and ~\scoop\apps\git\current\cmd.

It skips PATH entries that are relative (., bin), inside the repository (direnv's PATH_add) or inside node_modules. So a repository's own bin/ cannot supply git, and a Git only there is not found. A folder named git, or a git without its execute bit, is skipped too.

macOS always has /usr/bin/git, but only as a stub for Apple's developer tools. Rerail counts it once the Command Line Tools (xcode-select --install), or Xcode with Git, are installed.

rerail update stops the same way. Both run your own npm with your ~/.npmrc, so a registry mirror set there works for Rerail and its rule packs.

A failed install removes what it staged and its lock. Ctrl-C while set-up or rerail update installs leaves the lock, and the next run says Another Rerail update is already running for up to 15 minutes. If nothing else is installing, delete ~/.rerail/update.lock and run again.

npm gave set-up no rule packs: the registry went away, or your npm account has no access.

If only some packs fail to download or load, set-up goes on and lists them under Rule packs set-up could not use:, each with its reason. A pack made for a newer Rerail says so, and that rerail update installs the newest.

Set-up says it changed PATH: You can run `rerail` from any new terminal, or from a coding agent Added ~/.rerail/bin to PATH in ~/.zshrc. Open a new terminal to run rerail.

• Windows: set-up adds the folder to your user Path. Terminals in VS Code, Cursor or another editor, and what they start (agent shells too), keep the editor's old Path: quit the editor completely and reopen it. Meanwhile run %USERPROFILE%\.rerail\bin\rerail.cmd. Git Bash uses the sh launcher set-up writes beside rerail.cmd.
• zsh scripts and ssh: set-up writes ~/.zshrc, which only interactive zsh reads, so zsh -c '…' and ssh host rerail … miss it. Use ~/.rerail/bin/rerail, or add export PATH="$HOME/.rerail/bin:$PATH" to ~/.zshenv (Rerail never writes it).
• A different shell: set-up writes the startup file of $SHELL, else your login shell. For another shell, or with RERAIL_MODIFY_PATH=0, add ~/.rerail/bin to PATH yourself.
• Containers: docker exec … bash -c reads no startup file. Use bash -l, or the full path.

Set-up backs up each startup file it changes to <file>.rerail.bak, one backup per file.

The launcher, hooks and Claude Code's status line run the Node that ran set-up, by full path. For Homebrew that is /opt/homebrew/bin/node, a link brew upgrade keeps, so upgrading changes nothing.

If that Node is gone (nvm uninstall, say), they fall back to the first node on PATH. Claude Code's status line on Windows does not.

With that node older than 24, the daemon does not start and hooks do nothing. Claude Code's status line reads R E R A I L ✕ needs Node 24 or newer (this is 22.12.0).

With no node on PATH, the launcher and hooks fail with exit code 127 (…/.rerail/bin/rerail: line 5: exec: node: not found). Install Node 24, then run ~/.rerail/bin/rerail install --refresh.

After connecting Codex, set-up's summary says Open Codex and run /hooks once to trust Rerail’s hooks. Codex asks again whenever an update changes the hook, as this release does on Windows.

In Codex the commands are skills: $rerail, $rerail-show-me and so on. Set-up's summary uses that form when Codex is the only connected agent; with several, it adds In Codex, type $rerail-show-me.

On Windows, the hook works from a profile folder with a space or non-ASCII letter (C:\Users\José García).

Set-up skips an agent whose file does not parse, connects the others, starts the repository, and names the skipped agent in its summary. rerail update and rerail install --refresh skip that agent the same way and say so.

rerail install stops instead, with rerail: Cannot parse JSON in <file>: <reason>, and changes no config. Fix the file, or name the other agents: rerail install --agents cursor.

Set-up connects the new agents and names them (Now also connected: Codex.).

It never connects an agent you left out with --agents or disconnected with rerail install --remove --agents <id>; ~/.rerail/coding-agents.json tracks those. Connect one with rerail install --agents <id>.

With Claude Code's sandbox on, set-up keeps the agent's commands and file tools out of the Rerail home and ~/.cache/rerail (see What a coding agent can reach). With a redirect, a cd or a $(...), Rerail's commands stay sandboxed and fail.

After moving RERAIL_HOME or Node, run rerail setup again so the entries name the new paths.

/rerail-stop covers this checkout and its worktrees: no rules run and nothing is logged there. The daemon keeps running for other checkouts and agents, and the reply says so.

An agent session in a checkout where Rerail is still started restarts the daemon with its next event; stop Rerail there too. rerail status says whether the daemon is running.

The daemon reuses the port in ~/.rerail/daemon-port.json: 4737 at first, or the one rerail daemon start --port <n> named. Only when another program holds that port and 4737 does it take a free port, and keep it, so old links stop working. A taken --port fails the start instead (below).

--insecure-http keeps plain http, fair only because the port is on the host's loopback. Published anywhere else, pass --tls-cert <pem> --tls-key <pem> instead so the capability is not sent in clear (see the daemon section of reference.md).

Off loopback:

• The capability changes on every start. After a restart, open the new link rerail daemon start prints.
• Anyone holding the link can read and change your rules. Do not paste it anywhere.
• 127.0.0.1 keeps the port off the host's network, but in the container the daemon listens on every interface. Other containers on its Docker network (a Compose service, a sidecar) reach it directly, and are refused without the capability.

Every data request needs the capability. The browser keeps it once you open the link rerail manage opens or rerail daemon start prints. A bookmark, a new browser or profile, cleared site data, or a link pasted from an agent's session has none.

• On loopback the capability lasts across restarts, as access-token in your Rerail home. Delete it to rotate, then open the link again.
• curl and scripts send it as the x-rerail-access header, read from accessToken in daemon.json. Without it they get 401 {"error":"access-required"}.

If rerail status says the daemon "refused the access capability in daemon.json", the daemon and its state file disagree (one was edited or replaced). Run rerail daemon stop, then rerail daemon start.

• --output <file> writes elsewhere. The file is readable by your user only.
• It covers the repository's latest session; --session <id> names another (the id is in its dashboard address).
• It works where Rerail won't start or set-up never finished, and says which parts it could not read.

In what stays, Rerail replaces the daemon's capabilities, home folders (anyone's /Users/…, /home/… or C:\Users\…), recorded repositories' paths and names, the session id, your user name and the computer's name. It also removes common secret shapes (API keys, auth headers, passwords in URLs, private keys) and email addresses.

Other absolute paths, such as /opt/…, /srv/… or /Volumes/…, stay as written. A user name under four characters is replaced inside paths only. A steer can quote your code, and a file path or your own rule's id can name a project.

A bundle is diagnostic context for maintainers, not a way to show others what Rerail did.

A bin, versions or packs folder that also holds other files, as when RERAIL_HOME is shared with other things, is kept too; only Rerail's files go.

1. Disconnects every coding agent.
2. Takes ~/.rerail/bin off PATH, and deletes the <file>.rerail.bak it kept.
3. Stops the daemon.
4. Moves your database into a backup, ~/.rerail-clean-YYYYMMDD/.
5. Deletes ~/.rerail/current, ~/.rerail/bin, ~/.rerail/versions, the rule packs and ~/.cache/rerail.

It prints each removed path (Removed <path> (<what>).) and each kept one:

• Kept ~/.rerail: … (Rerail's settings, logs and records; delete it if you will not install Rerail again).
• Kept <path> (<what>): it holds files that are not Rerail's: <names>.

A file it cannot remove, such as one Windows locks while a session still runs Rerail, is named with the command that finishes the job: Could not remove <path> (<reason>). Close every coding agent and terminal still running Rerail, then run: ….