You can install RustDesk on Ubuntu with a download and one apt command. Out of the box, though, every session is brokered by RustDesk’s public ID and relay servers, and the home screen tells you so: “For faster connection, please set up your own server”. A self-hosted hbbs/hbbr pair used about 2 MB of RAM in our lab, runs in two containers, and keeps the brokering on a box you control.
This guide covers the RustDesk download for Ubuntu (the official .deb) and the Wayland split between 26.04 and 24.04, which decides whether unattended access works at all. Then you build a self-hosted RustDesk server in Docker Compose, open the hbbs and hbbr ports in UFW, point your clients at it, and fix the five connection errors we hit along the way. Every command and screenshot below comes from a lab run in October 2026 with the RustDesk 1.5.0 client on Ubuntu 26.04 and 24.04 against RustDesk Server OSS 1.1.16 in Docker on Ubuntu 26.04.
How the self-hosted pieces fit together
A self-hosted RustDesk setup has two server processes and as many clients as you like. hbbs is the ID and rendezvous server. Every client registers its ID and public key with it over UDP 21116, and when one client asks for another, hbbs introduces them. hbbr is the relay, and it only carries screen traffic when the two clients cannot reach each other directly. In our lab, two desktops on the same LAN always went direct, so hbbr sat idle until we forced relaying on.
The server signs everything with a key pair it writes into its data directory on first start. Clients that have the matching public key get an encrypted session. Clients with a wrong or missing key get “Key mismatch” and nothing else, which is why the key, not the hostname, is the part people get wrong.
The lab had four machines. You only need the first one, plus the desktops you already have:
- rustdesk01: Ubuntu 26.04 server, 2 vCPU and 4 GB RAM, running Docker, hbbs and hbbr
- desk01: Ubuntu 24.04 with GNOME on Xorg, the remote desktop for the X11 tests
- desk03: Ubuntu 26.04 with GNOME 50 on Wayland, the remote desktop for the Wayland tests
- desk02: Linux Mint 22.3 (Ubuntu 24.04 base), used as the controlling client
Install the RustDesk client on Ubuntu
RustDesk is not in the Ubuntu archive, so the client comes from the project’s GitHub releases as a .deb. The same commands work on Ubuntu 26.04 and 24.04. Look up the current release tag first so the download URL does not go stale:
RD_VER=$(curl -s https://api.github.com/repos/rustdesk/rustdesk/releases/latest | grep -m1 '"tag_name"' | cut -d '"' -f 4)
echo "$RD_VER"It should print a bare version such as 1.5.0. If it prints nothing, you have hit GitHub’s unauthenticated API limit of 60 requests an hour, which we did after a few dozen lab runs. Wait for the limit to reset or copy the version from the RustDesk releases page by hand.
1.5.0Download the x86_64 package and install it with apt, so its dependencies come along:
wget "https://github.com/rustdesk/rustdesk/releases/download/${RD_VER}/rustdesk-${RD_VER}-x86_64.deb"
sudo apt install -y ./rustdesk-${RD_VER}-x86_64.debThe package installs a systemd unit called rustdesk.service and enables it straight away. That service is what lets other people connect to this machine, so it runs even before anyone opens the app. Check the version and the service:
rustdesk --version
systemctl is-active rustdeskBoth lines should come back clean:
1.5.0
activeHow much apt pulls in depends on what is already on the box. We installed the same .deb on three machines and the difference is large enough to matter if you are tempted to put the client on a headless server:
| Machine | New packages | Extra disk |
|---|---|---|
| Ubuntu 26.04 server, no desktop | 132 | 131 MB |
| Ubuntu 24.04 with GNOME | 9 | 16.5 MB |
| Ubuntu 26.04 with GNOME | 3 | 142 kB |
On the bare server, the 132 packages are GTK, ALSA and PipeWire libraries for a GUI nobody will look at. Keep the client off the machine that runs hbbs and hbbr. We removed it from rustdesk01 after this capture.
Launch RustDesk from the app grid once it is installed. The window shows this machine’s ID and a one-time password, which is all a peer needs while you’re still on the public servers.
Check Wayland vs X11 before you rely on it
This section decides whether unattended access works on your desktop, and the answer differs between the two LTS releases. Ubuntu 24.04 still ships a GNOME on Xorg session (/usr/share/xsessions/ubuntu-xorg.desktop). Ubuntu 26.04’s GNOME 50 doesn’t: its ubuntu-session and gnome-session packages ship only Wayland session files, and on our 26.04 desktop /usr/share/xsessions doesn’t exist at all, while /usr/share/wayland-sessions holds a single ubuntu.desktop.
Check which one the remote desktop is running before you change anything. Run this in a terminal on the desktop itself, not over SSH, because an SSH login is its own session:
loginctl show-session $(loginctl list-sessions --no-legend | awk '$4=="seat0"{print $1}') -p TypeOn desk03, the Ubuntu 26.04 desktop, it printed the line below. desk01 printed Type=x11 after the GDM change that follows:
Type=waylandOn Ubuntu 24.04, the reliable setup for a machine you will reach unattended is X11. Set it in GDM so the login screen and the session both run on Xorg:
sudo vim /etc/gdm3/custom.confUnder the existing [daemon] section, uncomment or add this line, then reboot:
[daemon]
WaylandEnable=falsedesk01 ran exactly that, with automatic login also turned on in the same file, and the standard client gave a full remote session through our server with no prompt on the remote side. Without automatic login, you land on the GDM login screen instead, which RustDesk’s Linux docs say works once GDM runs on Xorg. You’ll see that session in the connection test further down.
On Ubuntu 26.04, the standard client does connect, but it stops at a message asking someone at the remote machine to pick the screen to share. Wayland only hands out screen capture through the desktop portal, and the portal asks the local user to approve it at least once per login session. Nobody was sitting at desk03, so the session went no further:
RustDesk’s answer is a separate package, rustdesk-unattended-wayland, published next to the normal .deb in the same release. It captures the screen from the kernel’s DRM/KMS output instead of through the portal (pull request 15420). RustDesk still calls it a preview for x86_64 Debian and Ubuntu systems in its announcement of the unattended Wayland build, so keep another way into the machine until you’ve tried it. The package declares Conflicts, Replaces and Provides: rustdesk, so apt swaps it in for the standard client:
RD_VER=$(curl -s https://api.github.com/repos/rustdesk/rustdesk/releases/latest | grep -m1 '"tag_name"' | cut -d '"' -f 4)
wget "https://github.com/rustdesk/rustdesk/releases/download/${RD_VER}/rustdesk-unattended-wayland-${RD_VER}-x86_64.deb"
sudo apt install -y ./rustdesk-unattended-wayland-${RD_VER}-x86_64.debapt removes rustdesk and installs the new package in one step. The ID, the server settings and the permanent password survived the swap on desk03. Confirm which package is active:
dpkg -l | grep -i rustdeskThe ii line is the one in use. The rc line is the removed standard package, which leaves its config behind:
rc rustdesk 1.5.0 amd64 A remote control software.
ii rustdesk-unattended-wayland 1.5.0 amd64 A remote control software.With that build, the same connection went straight into the Ubuntu 26.04 Wayland session. We opened a terminal with Ctrl+Alt+T sent through RustDesk and typed into it, so keyboard input works too, not just viewing:
We also rebooted desk03 with automatic login turned off and connected again before anyone logged in. The session landed on the GDM login screen, which the standard build can’t reach on Wayland:
The short version: on 24.04, switch GDM to X11 and use the standard package. On 26.04, use the unattended Wayland package for any machine you need to reach with nobody at the keyboard, and the standard package only where a person will approve each session.
Install Docker on the RustDesk server
The server half runs on any Ubuntu box with a public or LAN address that your clients can reach. It needs very little: hbbs used 1.5 MiB of RAM and hbbr 700 KiB at idle in our lab, the rustdesk/rustdesk-server image is 19 MB, and the data directory held 124 KB. The real sizing input is relay bandwidth. RustDesk’s OSS install page puts a relayed 1080p session between 30 KB/s and 3 MB/s, and hbbr logged its own defaults at startup: 128 Mb/s per connection (SINGLE_BANDWIDTH), 1024 Mb/s in total (TOTAL_BANDWIDTH), and 32 Mb/s (LIMIT_SPEED) for blacklisted connections or ones downgraded after 30 minutes of sustained heavy use. If most of your clients sit behind NATs that cannot punch through, size the uplink, not the CPU.
We used Docker Engine from Docker’s own apt repository, which already publishes a resolute suite for Ubuntu 26.04. Add the key and the repository:
sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.ascWrite the repository definition. The codename is filled in from /etc/os-release, so the same command works on 26.04 and 24.04:
echo "Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc" | sudo tee /etc/apt/sources.list.d/docker.sourcesInstall the engine and the Compose plugin:
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
docker --version
docker compose versionAny recent release is fine. These are the versions the lab ran:
Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1Our guide to installing Docker CE on Ubuntu 26.04 covers the post-install steps (running Docker without sudo, log rotation) if this is a fresh host.
Open the RustDesk ports in UFW
The server needs three TCP ports and one UDP port. Everything else either belongs to the paid Pro edition or to the web client:
- 21115/tcp: hbbs NAT type test
- 21116/tcp and 21116/udp: hbbs ID registration, heartbeat and TCP hole punching
- 21117/tcp: hbbr relay
- 21118/tcp and 21119/tcp: WebSocket ports for the web client only
- 21114/tcp: web console, Server Pro only
Don’t open 21118 and 21119 unless you run the web client behind a reverse proxy. RustDesk’s own Docker docs warn that hbbs and hbbr trust the X-Real-IP header on those ports without validating it, so anyone who can reach them directly can spoof their source address. The containers listen on both ports whether you want them or not (ss showed hbbs on 21118 and hbbr on 21119), which is exactly why the firewall rule matters. The UFW line on RustDesk’s own install page opens 21114:21119/tcp, which includes both of those plus the Pro-only 21114. The narrower rules below are all the open-source server uses.
Allow SSH before enabling UFW. Its default policy denies incoming traffic, so turning it on without that rule can lock you out of a remote server. If sshd listens on a port other than 22, allow that port instead of the OpenSSH profile:
sudo ufw allow OpenSSH
sudo ufw allow 21115:21117/tcp
sudo ufw allow 21116/udp
sudo ufw --force enable
sudo ufw statusThe status should list your three rules for IPv4 and IPv6:
Status: active
To Action From
-- ------ ----
OpenSSH ALLOW Anywhere
21115:21117/tcp ALLOW Anywhere
21116/udp ALLOW Anywhere
OpenSSH (v6) ALLOW Anywhere (v6)
21115:21117/tcp (v6) ALLOW Anywhere (v6)
21116/udp (v6) ALLOW Anywhere (v6)Docker normally writes its own iptables rules for published ports and walks straight past UFW. That does not happen here, because the Compose file below uses host networking and publishes nothing, so these UFW rules are the ones that apply. We proved it by deleting the UDP rule and the TCP 21117 rule in turn: each one broke the client in a different way, shown in the errors section. If the server sits behind a cloud firewall or a home router, open the same ports there as well. The UFW firewall commands guide has the rule syntax for narrowing these to known client networks.
Run hbbs and hbbr with Docker Compose
Create a directory for the server. The Compose file mounts ./data from it, and that is where the key pair and the peer database live:
sudo mkdir -p /opt/rustdesk-server
cd /opt/rustdesk-server
sudo vim compose.ymlPaste the Compose file. It is the one from RustDesk’s Docker documentation, unchanged, and it’s the exact file the lab ran:
services:
hbbs:
container_name: hbbs
image: rustdesk/rustdesk-server:latest
command: hbbs
volumes:
- ./data:/root
network_mode: "host"
depends_on:
- hbbr
restart: unless-stopped
hbbr:
container_name: hbbr
image: rustdesk/rustdesk-server:latest
command: hbbr
volumes:
- ./data:/root
network_mode: "host"
restart: unless-stoppedOlder guides, including the oneuptime tutorial that ranks for this search (it also pins server 1.1.15 and opens 21118 and 21119), start hbbs with an -r flag pointing at the relay address on port 21117. The current docs drop it, and our lab did not need it either: with the client’s relay field left empty, desk01 still reached hbbr on the ID server’s host, port 21117. Host networking (network_mode: "host") matters more. It lets hbbs see each client’s real address instead of Docker’s bridge IP, which hole punching depends on.
Validate the file, then start both containers:
sudo docker compose config --quiet && echo compose-valid
sudo docker compose up -d
sudo docker compose logsOn first start hbbs generates the key pair and prints the public key. The lines to look for are these:
hbbs | [2026-10-24 19:31:37.871250 +00:00] INFO [src/common.rs:147] Private/public key written to id_ed25519/id_ed25519.pub
hbbs | [2026-10-24 19:31:37.871295 +00:00] INFO [src/rendezvous_server.rs:1243] Key: TBOA3XhWFKgJzEQKlHyFho2l0K1eRgdviLtRBQnlH+c=
hbbr | [2026-10-24 19:31:36.553938 +00:00] INFO [src/relay_server.rs:82] Listening on tcp :21117
hbbs | [2026-10-24 19:31:39.683434 +00:00] INFO [src/rendezvous_server.rs:109] Listening on tcp/udp :21116
hbbs | [2026-10-24 19:31:39.683436 +00:00] INFO [src/rendezvous_server.rs:110] Listening on tcp :21115, extra port for NAT test
hbbs | [2026-10-24 19:31:39.683622 +00:00] INFO [src/rendezvous_server.rs:161] ALWAYS_USE_RELAY=NThe same key is in data/id_ed25519.pub, which is the easier place to copy it from. Yours will differ from ours:
sudo cat /opt/rustdesk-server/data/id_ed25519.pubThat one line is the value every client needs. The private half, data/id_ed25519, never leaves the server, and the next section explains why you should back it up.
Back up the data directory as soon as the server is up. If you lose id_ed25519 and hbbs generates a new pair, every client still holds the old public key and gets the “Key mismatch” error until someone updates it by hand. A tarball of ./data was 3.3 KB in our lab:
sudo tar czf ~/rustdesk-server-data-$(date +%F).tar.gz -C /opt/rustdesk-server data
sudo chmod 600 ~/rustdesk-server-data-*.tar.gz
sudo chown "$USER": ~/rustdesk-server-data-*.tar.gzThe chmod matters because tar left the file world-readable in our lab, and it contains the server’s private key. The chown hands it back to your login user, so you can copy it off with scp without sudo. Copy it off the server, to wherever your other secrets live.
Upgrades are a pull and a restart. The key and database sit in the mounted directory, so they carry over:
cd /opt/rustdesk-server
sudo docker compose pull
sudo docker compose up -dWhen pull reports the image as already current, as it did in our lab, up -d leaves both containers running and nothing restarts. When a new image does land, up -d recreates the containers, and peers can read as offline for up to a minute while they register again (the relay test below shows that window).
Point the clients at your server
Every client needs two values: the ID server and the key. The relay server field is optional because it defaults to the ID server’s host, but we fill it in anyway so nobody has to guess where relay traffic goes. Leave API server empty. That field is for Server Pro, and with it empty the client logs harmless warnings about failed HTTP calls to port 21114.
Use a DNS name rather than a bare IP if you can. A name survives a server move without touching every client. If you would rather not expose the ports to the internet at all, a private network such as self-hosted Headscale or WireGuard gives the clients a route to the server without any public rule. In the lab, rustdesk.example.com pointed at rustdesk01 through an /etc/hosts entry on each client. In production, it is an A record.
From the RustDesk window
Click the â‹® button beside your ID to open Settings, then choose Network. RustDesk keeps network settings locked, and changing them needs an administrator password through the system’s polkit prompt:
Click Unlock network settings, enter your password, then open ID/Relay server. Fill in ID server, Relay server and Key, and click OK:
Back on the home screen, the status line reads “Ready” with no “set up your own server” link after it. That missing link is the quickest sign the client has moved off the public servers:
If the status line turns red with “Not ready” instead, jump to the errors section. In our lab, that came from a missing UDP 21116 rule.
From the command line
The GUI is fine for one desktop. For several machines, or a box you only reach over SSH, the client takes the same settings as root on the command line. Set the server and key once per shell:
export RD_HOST="rustdesk.example.com"
export RD_KEY="TBOA3XhWFKgJzEQKlHyFho2l0K1eRgdviLtRBQnlH+c="Replace both with your own hostname and the key you copied from id_ed25519.pub, then write them into the client config. The last command sets a permanent password, so you do not have to read a one-time password off the remote screen. Start that line with a space so Ubuntu’s default HISTCONTROL keeps the password out of your shell history:
sudo rustdesk --option custom-rendezvous-server "${RD_HOST}"
sudo rustdesk --option relay-server "${RD_HOST}"
sudo rustdesk --option key "${RD_KEY}"
sudo rustdesk --password 'Choose-A-Long-Password'
sudo systemctl restart rustdeskRead the settings back and note the ID. That number is what you type on the controlling machine:
sudo rustdesk --option custom-rendezvous-server
sudo rustdesk --option key
sudo rustdesk --get-idThe settings land in /root/.config/rustdesk/RustDesk2.toml for the service, and the GUI keeps its own copy in ~/.config/rustdesk/RustDesk2.toml. On the server, a client that registered shows up in the hbbs log as an update_pk line with its ID:
sudo docker logs hbbs 2>&1 | grep update_pkOne line per client means both have registered. Our two peers, with lab addresses replaced and the key bytes at the end of each line trimmed:
[2026-10-24 19:39:05.124547 +00:00] INFO [src/peer.rs:102] update_pk 296238143 [::ffff:10.0.1.118]:54510 ...
[2026-10-24 19:46:46.083498 +00:00] INFO [src/peer.rs:102] update_pk 291796377 [::ffff:10.0.1.180]:37037 ...Registration rides on UDP 21116, so a client that never shows up here after a firewall change points at the UDP rule first. A client that does show up but cannot be reached points at the key or the relay port instead.
Connect and check direct vs relayed
Type the remote ID into Control Remote Desktop on the controlling machine and click Connect. A green shield in the session tab means the key matched and the session is encrypted. After the password, desk02 had full control of the Ubuntu 24.04 desktop:
Hover over that shield and you see how the session travels. It read “Direct and encrypted connection (TCP)” here, and ss on desk01 agreed: its RustDesk process held a connection straight to desk02 and nothing on 21117. On a single LAN that is the normal case, and it means hbbr carries none of your screen traffic.
To prove the relay path works before a client behind a hard NAT needs it, force every session through hbbr for a while. Add an environment block to the hbbs service in compose.yml:
hbbs:
container_name: hbbs
image: rustdesk/rustdesk-server:latest
environment:
- ALWAYS_USE_RELAY=Y
command: hbbsRecreate hbbs and confirm the setting took:
cd /opt/rustdesk-server
sudo docker compose up -d
sudo docker logs hbbs 2>&1 | grep ALWAYS_USE_RELAYThe last line should say Y:
[2026-10-24 19:50:18.558394 +00:00] INFO [src/rendezvous_server.rs:161] ALWAYS_USE_RELAY=YWait about a minute before reconnecting. Recreating hbbs drops its in-memory online list, and our first attempt 15 seconds after the restart failed with “Remote desktop is offline”. The retry a minute later went through, and the tooltip changed:
hbbr logs each relayed session as a request from one peer that gets paired with the other, and both peers hold a TCP connection to 21117 for as long as the session lasts:
Remove the environment block and run sudo docker compose up -d again from /opt/rustdesk-server when you are done, unless you want every session relayed. Forced relaying gives the server operator a single place to watch and cap traffic, but it costs bandwidth that direct sessions would never touch.
Fix RustDesk connection errors
We caused three of these on purpose by changing one thing at a time, and ran into the other two by accident, so the cause of each one is known exactly.
Error: “Key mismatch”
The client’s Key field doesn’t match the server’s id_ed25519.pub. We got this dialog with the first characters of the key changed and again with the field empty, so a missing key gives the same message as a typo:
Copy the key again from /opt/rustdesk-server/data/id_ed25519.pub and paste it into ID/Relay server, or set it with sudo rustdesk --option key "${RD_KEY}" followed by sudo systemctl restart rustdesk. A missing key shows one more clue: the session tab has no shield icon at all. If every client broke at once, the server probably generated a new key pair, so restore ./data from your backup rather than editing every client.
Error: “Not ready. Please check your connection”
The client can’t register with hbbs. With UDP 21116 blocked on the server and TCP left open, the client’s status line turned red within seconds of a restart, even though the NAT test on TCP 21115 still passed:
Check sudo ufw status for the 21116/udp rule, and check any cloud firewall in front of the server too. That UDP rule is the one people forget, because every other RustDesk port is TCP. Once we restored it, our next check 20 seconds later showed “Ready” again.
Error: stuck on “Connecting…” then “Failed to connect to relay server: Please try later”
The session needs the relay and cannot reach TCP 21117. We reproduced it with ALWAYS_USE_RELAY=Y and the UFW rule narrowed to 21115:21116/tcp. The client sat on “Connecting…” for 18 seconds before giving up:
Open 21117/tcp. If only some sessions hang like this, those are the ones that couldn’t go direct, and the relay port is closed somewhere between them and the server.
Error: “Remote desktop is offline” or “ID does not exist”
“Remote desktop is offline” means hbbs knows the ID but hasn’t heard from that peer lately. We saw it right after recreating the hbbs container, and it cleared on its own within a minute. “ID does not exist” means the peer never registered with your server at all. desk03 gave us that one after a reboot, because cloud-init rewrote /etc/hosts and dropped our rustdesk.example.com entry, so the client couldn’t resolve its ID server. Check that the remote side resolves the server name and shows the same ID server and key as the controller.
Open-source server vs Server Pro
Everything above uses the free open-source server, which handles ID registration and relaying for any number of clients. Server Pro is a separate paid product (currently 1.8.7) that adds the management layer. We didn’t test it, so this table comes from RustDesk’s pricing page as of October 2026:
| Free (OSS) | Individual | Basic | |
|---|---|---|---|
| Price | $0 | $11.88/month | $23.88/month |
| Billing | none | annual only | annual only |
| Login users | none | 1 | 10 |
| Managed devices | unlimited, unmanaged | 20 | 100 |
| Web console, address book, audit log | no | yes | yes |
| 2FA, access control, centralized settings | no | yes | yes |
| Distributed relay servers | no | yes | yes |
| OIDC (SSO) and LDAP | no | no | yes |
| Custom client generator | no | no | yes |
There is no monthly plan and licences don’t auto-renew. Pro also unlocks port 21114 for the web console, which is why that port appears in RustDesk’s docs at all.
We would stay on the open-source server for a homelab or a handful of machines you support yourself. There, an ID, a key and a password are all the access control you need. The Individual plan starts paying for itself when you want an address book and an audit trail of who connected where. Basic is the first tier with SSO and LDAP, so it’s the realistic floor for a team. If you’re still deciding whether RustDesk is the right tool at all, our Guacamole vs RustDesk vs MeshCentral comparison weighs it against a browser gateway and an agent-based manager, and the AnyDesk on Ubuntu guide covers the closest proprietary option. If you would rather reach desktops through a browser with no client installed, Apache Guacamole on Ubuntu is that route.
