How a click in Rem0te becomes a remote desktop session, what each path needs to be true, and why the most common failure blames the wrong computer.
If you are here because of "Failed to connect: the target device is offline or does not exist", skip to When it fails — but read The thing that surprises everyone first, because that message is usually about the computer you are sitting at.
Rem0te does not carry remote-desktop traffic. RustDesk does. Rem0te decides who may connect to what, hands out the credential, and gets out of the way.
| Piece | What it does |
|---|---|
| Rem0te API / web | Access control, credentials, audit. Knows nothing about the live connection. |
| hbbs (port 21116) | RustDesk rendezvous. Every client registers here; every connection starts by asking it "where is peer X?" |
| hbbr (port 21117) | RustDesk relay. Carries the session when the two ends cannot reach each other directly. |
| RustDesk client | The actual remote desktop, on both ends. |
Two independent notions of "online" follow from this, and they are the source of most confusion:
- Rem0te's online dot is an HTTP heartbeat from the endpoint every ~3 minutes. The API marks an endpoint offline after ~10 minutes without one.
- RustDesk's idea of online is a live registration with hbbs. hbbs holds that map in memory only.
A Connect uses only the second one. They can disagree — and when they do, the
UI shows a green dot next to a machine that RustDesk will tell you is offline.
hbbs-probe.py exists to settle that argument.
There are three, and they are not equivalent.
- Devices → My devices — the computers this account may connect to. Platform Admins and Business Owners get the full list under Devices.
- Connect — downloads the script described below.
Clicking Connect asks you to confirm it is you when the launch carries the
computer's password (step-up, credential.reveal — once per 10 minutes), then
hands you one file, named for the target machine. The password is in that file
and nowhere else: the browser never receives it, and releasing it is recorded as
a reveal (0.30.1). It uses
the RustDesk already on the computer — or fetches a portable copy once into
%LOCALAPPDATA%\Rem0te — points it at this server, then opens the session
with the password applied. It deletes itself afterwards, because it carries a
live credential.
It installs nothing, so there is no elevation prompt, and only the first run on a machine without RustDesk pays the download.
It assumes nothing about the machine it runs on. That is deliberate, and it is what the alternative could not do:
The obvious implementation is to open
rustdesk://connection/new/<id>?password=<pw>and let Windows route it to the installed RustDesk. That is what Rem0te used to do, and it works only on a client that already knows this server — because the URI scheme has no field for a server address. There is no way to carry "useremote.example.net" in the link. A stock client asksrustdesk.cominstead, is told the ID is unknown, and reports "the target device is offline or does not exist" about a computer that is online.
Once a machine has run the script once its RustDesk is configured, so a plain
rustdesk:// link would work there from then on.
The Tauri launcher, if installed, handles reboot-remote://launch#token=….
It validates a single-use 120-second token with the API, receives the target ID
and this server's RustDesk config, applies the config with
rustdesk --config, then spawns rustdesk --connect <id>.
Because it can apply the config, this path is self-contained — it works on a RustDesk that has never heard of your server. It is also the only path that does, which is why the launcher is worth installing on a shared or rebuilt technician machine.
For someone with no enrolled machine and no account. They download a client
from the public /quick page, read you a 9-digit ID, and you connect to it.
The client configures itself: its server settings travel in its filename,
which RustDesk reads on first run.
The Connect button uses the RustDesk on your computer, with your computer's server settings.
A stock RustDesk — a fresh install, or an auto-update that replaced a
preconfigured build — points at rustdesk.com's public rendezvous servers.
Your endpoint IDs do not exist there. RustDesk asks, is told the ID is unknown,
and reports:
Failed to connect: the target device is offline or does not exist.
The endpoint is online. The server is fine. The client you clicked from was never told where to look.
This is why Connect hands you a script instead of a link. The script configures the client before connecting, so it works the first time on a machine that has never seen this server.
If you would rather prepare a machine in advance, Remote Support → Technician client → Set up this computer for Connect does the configuration on its own. See clients.md.
Rem0te hands out a credential and RustDesk carries the connection. Nothing in that handoff proves a remote desktop connection happened, so each status names the evidence behind it and nothing more:
| Status | Means | Set by |
|---|---|---|
| Launch requested | a credential was released for this session | the server |
| Launcher acknowledged | the launcher redeemed its token, or the Connect script checked in | the server |
| Client opened | RustDesk started on the technician's computer. Not a connection | the launcher or Connect script |
| Connection confirmed | a RustDesk connection is running on the remote computer, and this is the only launch it can belong to; or the technician said so (recorded as theirs) | the endpoint's agent (0.20.0+), or the technician |
| Disconnected / ended | the connection ended (measured), the technician completed it (reported), or a timeout (inferred) | the agent, technician or timeout |
| Failed / Canceled | reported failure before any confirmation / technician | |
| Status unknown | no confirming or failing signal arrived in time: 30 minutes after a launch, 12 hours after a client opened | timeout |
Duration is shown only when it was measured: a confirmed start and an
observed end, both from the endpoint. Otherwise it reads unknown and the
session says how the times it has were obtained. A finished session cannot be
reopened; a late event is recorded but changes nothing. Confirmation from the
endpoint needs an agent from 0.20.0, which counts RustDesk's incoming
connection processes (rustdesk.exe --cm). This is a heuristic: it cannot tell
two simultaneous incoming sessions apart, so with more than one open launch
for a computer it confirms neither.
Every computer has a Test connection panel, on its Diagnostics tab (0.31; Diagnose in the header opens it). It runs read-only checks and says, for each, what was found, where the problem is (server, endpoint or your computer) and what to do:
- Server: RustDesk settings configured; hbbs (21116), hbbr (21117) and the NAT test port (21115) reachable.
- Endpoint: the agent's last heartbeat and device secret; agent and RustDesk versions; live registration with hbbs; stored credential state; incoming sessions.
- Your computer: Check my computer downloads a read-only helper
.cmd. It reports this machine's RustDesk install, version, server address and key, and whether it can reach the server. The result appears in the panel.
Fixes that change something (reinstall the agent, accept a device secret, rotate the credential) are labeled as such and are never run by the test. Download report gives a text report with credentials, keys and addresses redacted, safe to attach to a ticket.
Work in this order. Each step rules something out for good.
sudo deploy/scripts/hbbs-probe.py <rustdesk-id>| Verdict | Means | Do this |
|---|---|---|
ONLINE |
hbbs found the peer and returned a connection path. The server and the endpoint are both fine. | The problem is the client you are connecting from — go to step 2. |
OFFLINE |
hbbs knows the ID but has no live registration right now. | Step 3. |
ID_NOT_EXIST |
hbbs has never seen this ID. | Step 4. |
LICENSE_MISMATCH |
The key does not match the one hbbs was started with. | Step 5. |
Nothing is wrong with the endpoint. Your RustDesk is talking to someone else's rendezvous server.
- Quit RustDesk completely — from the system tray, not just the window. A running client will not pick up a configuration change.
- Click Connect again and run the file it gives you. It reapplies the configuration every time, so a client that drifted gets corrected.
- If that still fails, Rem0te → Remote Support → Technician client → Set up this computer for Connect, and watch its output — it prints which RustDesk it found.
If it still fails, confirm what the client thinks: RustDesk → Settings → Network → ID/Relay Server. The ID Server must be your Rem0te host, and the Key must match Settings → RustDesk → Public Key in Rem0te exactly.
Reinstalling RustDesk does not clear this. %APPDATA%\RustDesk survives an
uninstall and a fresh install picks the old server straight back up — delete
that folder before reinstalling.
- Within ~30 seconds of an hbbs restart, this is normal and not a fault.
The online-peer map is in memory; a restart empties it and clients
re-register on their next cycle. Any
rustdesk-serverupgrade orsystemctl restart rustdesk-hbbsopens that window. Wait, probe again. - Otherwise the endpoint's RustDesk is not running, or the machine is off, or it has lost its route to port 21116. Check whether the Rem0te heartbeat is still arriving (the endpoint's Last seen). Heartbeat arriving but hbbs offline means RustDesk specifically is stopped or misconfigured on that machine.
hbbs has never seen this ID, so the endpoint is registering somewhere else —
usually rustdesk.com.
Re-run the Rem0te installer on the endpoint. Installs from before v0.8.2 wrote the RustDesk service config to a path the service never reads, leaving it on defaults pointing at the public servers while every check passed. That fix only lands by reinstalling.
The key the client presented is not the one hbbs was started with. Compare:
cat /var/lib/rustdesk-server/id_ed25519.pubagainst Settings → RustDesk → Public Key in Rem0te. They must be identical. If you regenerated the server keypair, every installer and every client configured before that moment is now wrong and must be reconfigured.
Rem0te stores the endpoint's permanent password encrypted and hands it to the
client in the rustdesk:// link. It desyncs if someone ran
rustdesk --password on the endpoint by hand. Stage a credential rotation from
the endpoint's page, or re-run the installer.
hbbs writes nothing to its log when a connection request fails — no line for an unknown ID, none for an offline peer, none for a key mismatch. The only way to see its answer is to ask it.
# native rendezvous, TCP 21116
sudo deploy/scripts/hbbs-probe.py 123456789
# the WebSocket path on 443, end to end through Caddy
sudo deploy/scripts/hbbs-probe.py 123456789 --ws --host remote.example.net
# check a client key rather than the server's own
deploy/scripts/hbbs-probe.py 123456789 --key '<base64 key>'It sends a real PunchHoleRequest and decodes the reply. Exit status is 0 for
ONLINE, 1 for any other verdict, so it drops into a monitoring check as-is.
| Port | Protocol | Used by |
|---|---|---|
| 443 | TCP | Rem0te web + API, and RustDesk over WebSocket (see below) |
| 21115 | TCP | hbbs NAT type test |
| 21116 | TCP + UDP | hbbs rendezvous — UDP registration, TCP connection requests |
| 21117 | TCP | hbbr relay |
| 21118 | TCP | hbbs WebSocket (/ws/id) |
| 21119 | TCP | hbbr WebSocket (/ws/relay) |
Port 21116 needs UDP as well as TCP. Endpoint registration is UDP; a firewall that forwards only TCP produces endpoints that appear briefly and then go offline.
For sites that permit nothing but 443 outbound, Caddy proxies /ws/id to hbbs
and /ws/relay to hbbr, matching hbb_common's own wss://<host>/ws/id
convention. Clients find it without extra configuration.
This requires rustdesk-server 1.1.16 or newer. 1.1.15 accepts the WebSocket upgrade and then immediately drops the connection, so the routes look present and do nothing. Check under Updates → RustDesk Server, or:
hbbs --version
sudo deploy/scripts/hbbs-probe.py <id> --ws --host <your-host>- clients.md — which client to hand to whom, and how each gets configured
- updates.md — keeping Rem0te, the RustDesk clients and hbbs/hbbr current
- troubleshooting.md — everything else
