Troubleshooting

Phone app · macOS · Linux · Windows (WSL)

Before pairing, the phone checks that the computer answers on your network. It got no reply within a few seconds.

1. Check the app is open on the computer, the computer is awake, and the phone is on the same Wi-Fi — not mobile data or a guest network.
2. From the phone's browser, open http://<computer's address>:38787/health. It should show {"ok":true}. If it never loads, something is blocking the phone.
3. Linux: if the firewall is on (sudo ufw status says active), let the phone through:

   sudo ufw allow 38787/tcp

   Copy
4. Linux with firewalld instead:

   sudo firewall-cmd --permanent --add-port=38787/tcp
   sudo firewall-cmd --reload

   Copy
5. macOS: if asked whether Agent Remote may accept incoming connections, choose Allow. If you chose Deny: System Settings → Network → Firewall → Options, and allow Agent Remote.
6. Windows (WSL): turn on mirrored networking and allow it through the firewall when Windows asks. Run agent-remote doctor to check.
7. A VPN or a virtual machine on the computer can put an address the phone can't reach into the code. Turn the VPN off, or set the virtual machine's network to bridged, then make a new code.
8. Still nothing? With Pro, pair over Tunnel instead — it doesn't need the same network.

More on pairing over your network

Phone app

The code you scanned is an older kind the phone no longer uses to pair.

1. On the computer, open Access and choose Generate pairing QR, then scan the new code.

Phone app

The camera read a code, but it isn't one made by Agent Remote — or it came through damaged.

1. On the computer, open Access and choose Generate pairing QR, then scan the new code.
2. Hold the phone steady with the whole code on screen, away from glare.

Phone app

This code points outside your network, and the app on the computer is too old to pair that way.

1. Pair once while the phone is on the same network as the computer, or
2. Update the app on your computer, then scan its pairing code again.

Phone app

The computer didn't accept the code. Usually it was already used, or more than fifteen minutes old.

1. A code works once, for fifteen minutes. On the computer, open Access and choose Generate pairing QR, then scan the new code.

Computer app

The code on screen is more than fifteen minutes old.

1. Choose Generate pairing QR again and scan the new code.

Phone app

The computer still lists this phone, but the phone app lost its pairing — for example after its data was cleared.

1. On the computer, open Access, choose this phone and remove it (the bin).
2. On the computer, open Access and choose Generate pairing QR, then scan the new code.

Computer app

After too many failed tries, the computer stopped answering pairing from that device for a while.

1. Wait — it clears itself after a few minutes — or choose Clear and let it try again.
2. A code works once. If you scanned the same one twice, make a new one.

Phone app

The computer at this address is not the one this phone was paired with. That happens after Agent Remote is reinstalled or reset on it.

1. If you did reinstall or reset it: scan its pairing code again.
2. If you didn't, don't continue on this network until you know why.

Phone app

This phone's computers came from another phone (a backup or a transfer), or a copy of its data connected first. A pairing belongs to the phone it was made on.

1. On each computer, open Agent Remote, choose Generate pairing QR in Access, and scan it with this phone.

Phone app

The phone is paired, but the computer doesn't answer right now.

1. Wake the computer and check the app is open on it.
2. Tap Try again, or Find it on this network if it changed network.
3. Away from your own network you need Pro with Tunnel on, and the phone paired over Tunnel.
4. Still nothing: on the computer, Access → your phone → Reconnect, and scan. The phone keeps its key.

Phone app

None of the addresses the phone knows for this computer answered on this network.

1. Check the computer is awake and on the same network as the phone.
2. If it moved network, re-scan its pairing code: Access → your phone → Reconnect.

Phone app

The phone was blocked or removed on the computer.

1. On the computer, open Access: unblock the phone, or pair it again.

Computer app

The app window is open, but the part that runs your sessions isn't answering.

1. Quit the app and open it again. Your sessions keep running.

Server without a screen · macOS

The one-line install is for a Linux machine or WSL. A Mac uses the app.

1. Get the app for your Mac on the download page.

Download page

Server without a screen · Linux · Windows (WSL)

The install line needs a standard tool (such as curl or tar) that this machine doesn't have.

1. Install the tool it names. On Debian or Ubuntu, for example:

   sudo apt install curl tar

   Copy
2. Run the install line again.

Server without a screen · Linux

There is no build for this machine's processor yet.

1. Install it on a 64-bit Intel/AMD or 64-bit ARM machine instead.

Server without a screen

The file didn't arrive in one piece. Nothing on the machine was changed.

1. Check the machine's internet connection and run the install line again.

Server without a screen

agent-remote update only works on a copy put there by the install line.

1. Run the install line from the download page again. Your phones stay paired.

The install line

Server without a screen

The new version didn't start, so the one you had was put back. Your sessions keep running.

1. See what went wrong:

   agent-remote logs

   Copy
2. Try agent-remote update again later. If it keeps failing, write to support with what the logs say.

Server without a screen

This computer has the desktop app, which keeps itself up to date.

1. Update from the app on this computer instead of agent-remote update.

Computer app

The app couldn't reach the update server, or the download didn't install.

1. Check the internet connection and try again in a few minutes.

Server without a screen · Linux · Windows (WSL)

Something else on the machine already listens on the port Agent Remote uses — often an older copy of Agent Remote.

1. Close that program, or start it on another port:
2. Use another port (then use that number in any firewall rule too):

   agent-remote start --port 38788

   Copy

Server without a screen · Computer app

agent-remote doctor found that Agent Remote isn't running on this machine.

1. Start it:

   agent-remote start

   Copy
2. If this computer has the app, open the app instead.

Server without a screen · Linux

It runs now, but won't start again by itself after the machine restarts.

1. Turn starting by itself on:

   agent-remote start

   Copy

Server without a screen · Linux

After a restart it waits until you log in, so your phone can't reach the machine until then.

1. Run this once:

   sudo loginctl enable-linger $USER

   Copy

Server without a screen · Windows (WSL)

WSL is running without systemd, so nothing can start Agent Remote by itself.

1. Add these two lines to /etc/wsl.conf:

   [boot]
   systemd=true

   Copy
2. In PowerShell:

   wsl --shutdown

   Copy
3. Reopen the terminal and run:

   agent-remote start

   Copy

Server without a screen · Windows (WSL)

WSL is on its own network inside Windows, so a phone on your Wi-Fi can't reach it.

1. Add these two lines to .wslconfig in your Windows user folder:

   [wsl2]
   networkingMode=mirrored

   Copy
2. In PowerShell, then reopen the terminal:

   wsl --shutdown

   Copy
3. Allow it through the firewall if Windows asks, then run agent-remote doctor again.

Server without a screen

The machine has no address on a local network a phone could be on.

1. Connect it to the same Wi-Fi or network as your phone — or, with Pro, link it to your account and use the tunnel.

Server without a screen · Computer app

A part Agent Remote needs to run sessions is missing or broken.

1. Run the install line from the download page again — or, with the app, reinstall the app.

Phone app · Android

Android won't install the Android download over a copy of Agent Remote that came from somewhere else: a download from before version 1.0.12, or the app from Google Play.

1. If you have Agent Remote from Google Play, keep using that one. Google Play keeps it up to date, and you don't need the download.
2. Otherwise, uninstall Agent Remote once: press and hold its icon and choose Uninstall, or go to Settings → Apps → Agent Remote → Uninstall.
3. Open the file you downloaded again and tap Install. You only need to uninstall once.
4. Uninstalling removes the computers you paired and your sign-in from the phone. Your sessions keep running on your computers. Sign in again, then pair each computer again.
5. On the computer, open Access and choose Generate pairing QR, then scan the new code.
6. Still App not installed? Check the phone has free space and the download finished, then download the file again from the download page.

Installing the Android download

Phone app

The session wasn't started. Either this phone isn't allowed to start sessions, or the computer hit an error.

1. If it says the device isn't allowed: on the computer, Access → this phone, and give it the Full role or switch starting sessions on.
2. Otherwise, try again.

Phone app

This phone's role lets it watch sessions but not end them.

1. On the computer, Access → this phone, and change its role to Full.

Phone app

This phone has the View role: it can watch, not type.

1. On the computer, Access → this phone, and change its role to Operate or Full.

Phone app

This phone has as many sessions open as your plan allows. A session dimmed with a lock is the same thing.

1. Close one of your open session tabs — the session keeps running — or stop one you no longer need.

Computer app · Linux

Attach opens the session in a terminal window, and the app found no terminal app it knows.

1. Install a terminal app, for example:

   sudo apt install gnome-terminal

   Copy
2. Or set the TERMINAL variable to the one you use, then try Attach again.

Phone app

Another paired device opened the same session.

1. If that wasn't you, on the computer open Access and block or remove the device you don't recognise.

Computer app

Reaching the computer from outside your network is part of Pro.

1. Choose LAN at the top of the pairing dialog, or start Pro and turn on Tunnel in Access.

Computer app

The tunnel's address stopped working — it can change when the app restarts or updates.

1. In Access, turn Tunnel off and on again.
2. On each phone that uses it: Access → the phone → Reconnect, choose Tunnel and scan.

Phone app

The phone can't reach the computer from outside your network right now. Your dev server isn't the problem.

1. Make sure the computer is awake and online, then try again.
2. If it keeps happening, turn Tunnel off and on in the app on the computer.

Phone app

Your trial or subscription ended, so this computer is back to the free plan's limits. Everything on your own network keeps working.

1. Close a session to start another, or subscribe again on the website under Billing.

Phone app

Your plan has more computers linked than it has room for, and this one is over the line.

1. Unlink a computer you no longer use, or move up to a plan with more computers.

Phone app

You reached your plan's limit — of open sessions or of paired phones.

1. Close one to start another, or move up a plan for more.

Server without a screen · Website

Every computer your plan allows is already linked.

1. Unlink one you no longer use, or upgrade the plan, then link this one again.

Website

The email and password don't match an account.

1. Check both and try again, or choose Forgot password to set a new one.

Website

The email link was already used, or is too old.

1. Ask for a new one — Forgot password on the sign-in page — and use the newest email.

Website · Computer app

The browser sign-in page didn't recognise the request the app on your computer sent.

1. In the app's Cloud tab, start signing in again.
2. If it keeps happening, update the app.

Computer app

The sign-in in the browser didn't complete, or took too long.

1. In the Cloud tab, sign in again and finish it in the browser in one go.

Computer app

The check with your account didn't get through. It says nothing about your account, and everything on your own network keeps working.

1. Check the internet connection and try again.

Website · Server without a screen

The code typed on the link page doesn't match, or it's too old.

1. On the machine, get a new code:

   agent-remote cloud login

   Copy
2. Enter it at the link page while signed in.

Website

The payment page couldn't be opened. Nothing was charged.

1. Wait a moment and try again. If it keeps failing, write to support.

Website

The team that invited you is full on its plan.

1. Ask whoever invited you to free a place or move up a plan, then open the invite again.

Phone app

The phone app isn't allowed to use the camera.

1. Open the phone's Settings, find Agent Remote, and turn Camera on. Then scan again.

Phone app

This version of the phone app can't use the camera.

1. Update the phone app from your store, then try again.

Phone app

The phone isn't allowed to show notifications from Agent Remote.

1. Turn them on in the phone's Settings for Agent Remote.
2. Notifications also need Pro or the trial, the computer linked to your account, and Receive notifications on for this phone in Access.

What notifications need

Phone app

The notification came from a computer this phone can't match, so nothing was sent.

1. Open the session on that computer, or open the phone app, and answer there.

Phone app

Files sent to a session can be up to 25 MB.

1. Send a smaller file, or split it.