Troubleshooting

A computer shows as offline

• Is the bridge running? On the computer: coderail status. On a Mac, the menu bar icon is dimmed when it isn't connected; choose Resume if it's paused.
• Read the log: coderail logs (or Show Log in the Mac app). It says whether it's connecting, connected, or why it stopped.
• Was it removed? If the log says the machine was removed or its token refused, link it again: coderail link https://your-site (or Connect This Mac… in the Mac app).
• Linux, nobody logged in? A user service stops at logout unless you've run loginctl enable-linger $USER.

An agent is missing or can't sign in

• The computer must have claude or codex on the PATH of your login shell. Check that claude --version works in a new terminal there, then restart the bridge: coderail service restart.
• Sign it in from the site (Owner with terminal access) or in a terminal on the computer; see Signing in.

A session seems stuck

• Stop ends the current turn.
• Check Needs you: the agent may be waiting for an approval.
• If the computer went offline mid-turn, the session continues when it reconnects; the history shows what happened.

The Mac app won't open

• Make sure it's in Applications and you're on macOS 13 or later.
• If macOS says it can't check the app, download it again from your site: builds are notarized, and a damaged download is the usual cause.

Push notifications don't arrive

• Your server needs VAPID_PUBLIC_KEY and VAPID_PRIVATE_KEY; see Configuration.
• On iPhone, open CodeRail from the home screen icon and turn notifications on there.

Still stuck

Open an issue with what you see, the versions (coderail version, claude --version, codex --version) and the relevant log lines, minus anything private.