Troubleshooting

Start with the computer. Run remotxai doctor in a terminal on it. Every line should say PASS. A FAIL line names the problem.

The app cannot reach my computer

The app says Computer unreachable, Offline or Asleep.

1. Wake the computer and check its network.
2. On the computer, run remotxai status. It should say the service is running. If it cannot connect, run remotxai service status, then remotxai service start.
3. If the computer was disconnected on purpose with remotxai down, run remotxai up to reconnect.
4. Back in the app, choose Reconnect.

Sessions keep running on the computer while the link is down. The app catches up when the link returns. Do not send the same prompt again while it reconnects.

The connection drops after sleep or a network change

The app shows “Connection dropped, reconnecting (sessions keep running)”. Keep the app open and wait. The computer reconnects by itself. remotxai logs -n 100 shows relay linked: when it does. A computer that is asleep cannot do any work until it wakes. Set it to stay awake if your agents run long.

The verification code does not match

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.
2. Run remotxai pair enable 5m, then remotxai pair.
3. Start pairing again on the phone. It shows a fresh code.

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

Pairing says it is not open

The phone says Pairing isn’t open on the computer. On the computer, run remotxai pair and leave it open, or run remotxai pair enable 10m. Then choose Retry on the phone.

The pairing request timed out

Nobody approved it within 3 minutes. Choose Start a new request on the phone. Pairing requests also end when the computer restarts, on purpose.

remotxai status or remotxai pair hangs

The service may be busy reconnecting. Wait a minute, then run remotxai status again. If it keeps failing, run remotxai logs -n 100 and remotxai doctor.

The agent is unavailable

The app says a harness cannot start. Check that the program is installed and signed in, in the same terminal where you installed remotxai:

command -v claude
command -v codex
command -v pi

You only need the one you use. Install it, sign in with its own instructions, then run remotxai service install so the service sees it. That restarts the service and stops running sessions, so finish active work first.

I get no notifications

• Notifications are blocked in this browser. Allow them for the app 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 cannot send push notifications. Run remotxai upgrade on the computer.
• You get nothing while the app is on screen.

Then choose Notify this device again. Notifications has the details.

An attachment is refused

The app says why. The usual causes are a file over 8 MiB, a message over 20 MiB of files in total, an empty file, or an agent that cannot read that file type. See Files and attachments. If your computer is old, run remotxai upgrade.

A profile switch did not work

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, then try again. If the app says a previous switch did not finish cleanly, an admin phone has to choose Clear recovery flag after checking which account is running. See Profiles and accounts.

The background service is not running

remotxai service status
remotxai service start
remotxai logs -n 100

If it is not installed, run remotxai service install. If it keeps stopping, remotxai doctor and the log name the cause.

An upgrade broke something

Go back to the previous version:

remotxai service rollback

Still stuck

Run remotxai doctor and remotxai logs -n 100. Remove any tokens or personal names from the output before you share it. Email [email protected] only for security issues.