Skip to content

Troubleshooting

Run remotxai doctor on the computer first. Every line should say PASS. A FAIL line names the problem.

Settings → Appearance → Reload app reloads the screen. Sessions keep running. If it’s still stuck, check the service on the computer and start it if it’s down:

Terminal window
remotxai status
remotxai service start

The app says Computer unreachable, Offline or Asleep.

  1. Wake the computer and check its network.
  2. Run remotxai status on the computer. If the service isn’t running, start it.
  3. Check its relay link line. linked to wss://app.remotxai.com with organisation admission means the app can reach the computer. refused: gives the reason, for example host-not-endorsed. off: says why it isn’t connecting at all. remotxai doctor shows the same in its relay config row.
  4. If you ran remotxai down, run remotxai up.
  5. If relay linked now says no and relay last linked is minutes old, run remotxai reload --relay. It drops the relay connection and dials again without restarting the service. Run it once; a second call within 2 seconds answers try again in N s.
  6. In the app, tap Reconnect.
Terminal window
remotxai status
remotxai service status
remotxai service start
remotxai up
remotxai reload --relay

Sessions keep running while the link is down. The app catches up when it returns. Don’t resend a prompt while it reconnects.

The connection drops after sleep or a network change

Section titled “The connection drops after sleep or a network change”

The app shows “Connection dropped, reconnecting (sessions keep running)”. Keep it open. The computer reconnects by itself and logs relay linked: when it does:

Terminal window
remotxai logs -n 100

A sleeping computer does no work. Keep it awake for long agent runs.

Do not approve it and do not guess. A relay may be sitting between the phone and the computer.

  1. Deny the request at the computer. remotxai pair requests lists it, and remotxai pair deny <ref> denies it.
  2. Run remotxai up on the computer and sign in again, or, on a computer that runs with REMX_LEGACY_PAIRING=1, open a fresh pairing window.
  3. Start again on the phone. A legacy pairing shows a fresh code.
Terminal window
remotxai pair requests
remotxai pair deny <ref>
remotxai pair enable 5m
remotxai pair

If the code still does not match, stop. Check that the phone and the computer use the remotxai service you expect.

The phone says the computer isn’t in an organisation

Section titled “The phone says the computer isn’t in an organisation”

New pairing is off by default, so the phone says This computer isn’t in an organisation. On the computer, run remotxai up and sign in, then tap Retry on the phone.

Terminal window
remotxai up

To pair a phone directly instead, set REMX_LEGACY_PAIRING=1 in the daemon’s environment, then run remotxai pair and leave it running (or remotxai pair enable 10m). remotxai pair enable also still opens the window that approves a scope change for a device already paired.

Nobody approved it within 3 minutes. Tap Start a new request on the phone and run remotxai pair approve <ref> on the computer within 3 minutes. A new device only reaches the computer through remotxai up, or through a pairing window when the daemon runs with REMX_LEGACY_PAIRING=1. A computer restart also ends pending requests.

Terminal window
remotxai pair requests
remotxai pair approve <ref>

The service may be reconnecting. Wait a minute and retry. If it keeps failing, check the log and run remotxai doctor:

Terminal window
remotxai status
remotxai logs -n 100
remotxai doctor

The app says an agent can’t start. In the terminal where you installed remotxai, check that it’s installed:

Terminal window
command -v claude
command -v codex
command -v pi

You only need the one you use. Install it and sign in, then run remotxai service install so the service finds it. This restarts the service and stops running sessions, so finish active work first.

  • Notifications are blocked in this browser. Allow them in the phone’s settings.
  • This browser cannot receive push notifications. On iPhone, add the app to the home screen first. See Install the app on your phone.
  • This computer can’t send notifications yet. Upgrade remotxai on it.
  • None arrive while the app is open on screen.
Terminal window
remotxai upgrade

Then tap Notify this device again. More: Notifications.

The app gives the reason. Usually the file is over 32 MiB, the message’s files total over 64 MiB, the file is empty or the agent can’t read that type. See Files and attachments. Fix or replace the file and resend. On an older remotxai, upgrade first:

Terminal window
remotxai upgrade

The app says The agent didn’t start under the new profile, so the session went back. Nothing was lost. Check that the profile’s login still works on the computer, run remotxai doctor, then retry. If the app says an earlier switch didn’t finish, check which account is running. Then clear the flag with Clear recovery flag on an admin phone, or on the computer. See Profiles and accounts.

Terminal window
remotxai doctor
remotxai sessions clear-switch-recovery <session-id>
Terminal window
remotxai service status
remotxai service start
remotxai logs -n 100

If it isn’t installed, run remotxai service install. If it keeps stopping, remotxai doctor and the log name the cause. On a new computer it’s often that no agent is installed (claude, codex or pi). The log then says no coding agent found. See The agent is unavailable.

Go back to the previous version:

Terminal window
remotxai service rollback

After a rollback, a release downloaded for the upgrade you undid is never applied by itself, because the computer only applies a release newer than the one it runs. The daemon removes such a leftover when it starts, and remotxai status removes it too, with a line saying so. To go back to an older release on purpose, use remotxai service rollback or remotxai upgrade --allow-downgrade.

Collect these:

Terminal window
remotxai doctor
remotxai logs -n 100
remotxai diagnostics

remotxai diagnostics writes a redacted remotxai-diagnostics-<timestamp>.tar.gz in the current folder. Remove any tokens or personal names before you share it. Email [email protected] only for security issues.