RustDesk Self-Hosted: Client Fails to Connect Despite Open Ports

[electriquo]

Summary of the Issue

• HBBS and HBBR Containers start correctly
• Ports are open and reachable
• Client can connect to the server socket
• However, the client never becomes "ready"
• Connections are immediately dropped by the server

Request

Any guidance on why the client cannot complete the connection (despite successful TCP connectivity) would be appreciated.

---

Environment

• OS: macOS 26.4.1
• Container runtime: Rancher Desktop 1.22.0

Docker Compose Setup

I created the following compose.yaml, inspired by:

• Docker Compose example
• Configuration refactor proposal

services:
  hbbs:
    container_name: hbbs
    image: docker.io/rustdesk/rustdesk-server:1.1.15
    command: hbbs
    volumes:
      - ./data:/root
    depends_on:
      - hbbr
    restart: unless-stopped
    environment:
      - RUST_LOG=debug
      - ALWAYS_USE_RELAY=Y
      - RELAY-SERVERS=localhost
      - RENDEZVOUS-SERVERS=localhost
    network_mode: host

  hbbr:
    container_name: hbbr
    image: docker.io/rustdesk/rustdesk-server:1.1.15
    command: hbbr
    volumes:
      - ./data:/root
    restart: unless-stopped
    environment:
      - RUST_LOG=debug
    network_mode: host

Firewall Check

Verified that the macOS firewall is disabled

$ /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate
Firewall is disabled. (State = 0)

Running the Services

Started the Server and Relay containers

$ docker compose run --rm --service-ports --pull always hbbs
[+] create 0/1
[+]  2/2t 2/22r.io/rustdesk/rustdesk-server:1.1.15 Pulling   3.7s
 ✔ Image docker.io/rustdesk/rustdesk-server:1.1.15 Pulled    3.7s
 ✔ Container hbbr                                  Started   0.1s
Image docker.io/rustdesk/rustdesk-server:1.1.15 Pulling
Image docker.io/rustdesk/rustdesk-server:1.1.15 Pulling
Image docker.io/rustdesk/rustdesk-server:1.1.15 Pulled
Image docker.io/rustdesk/rustdesk-server:1.1.15 Pulled
WARN[0004] No services to build
Container rustdesk-hbbs-run-bd37cde62bf0 Creating
Container rustdesk-hbbs-run-bd37cde62bf0 Created
[2026-04-14 14:19:02.336174 +00:00] INFO [libs/hbb_common/src/config.rs:895] Generated new keypair for id:
[2026-04-14 14:19:02.340149 +00:00] INFO [src/common.rs:147] Private/public key written to id_ed25519/id_ed25519.pub
[2026-04-14 14:19:02.340162 +00:00] DEBUG [src/common.rs:148] Public key: wUrf0XQ0jTpxorpiLZWXBPRwD0R5y4ngMKgN7kaP4Ag=
[2026-04-14 14:19:02.340556 +00:00] INFO [src/rendezvous_server.rs:1251] Key: wUrf0XQ0jTpxorpiLZWXBPRwD0R5y4ngMKgN7kaP4Ag=
[2026-04-14 14:19:02.340566 +00:00] INFO [src/peer.rs:84] DB_URL=./db_v2.sqlite3
[2026-04-14 14:19:02.342270 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/hyper-0.14.32/src/client/connect/dns.rs:122] resolving host="api.rustdesk.com"
[2026-04-14 14:19:02.342284 +00:00] DEBUG [src/database.rs:58] MAX_DATABASE_CONNECTIONS=1
[2026-04-14 14:19:02.347730 +00:00] DEBUG [<unnamed>:0] PRAGMA page_size = 4096; …; rows affected: 0, rows returned: 2, elapsed: 4.763ms

PRAGMA page_size = 4096;
PRAGMA locking_mode = NORMAL;
PRAGMA journal_mode = WAL;
PRAGMA foreign_keys = ON;
PRAGMA synchronous = FULL;
PRAGMA auto_vacuum = NONE;

[2026-04-14 14:19:02.359522 +00:00] DEBUG [<unnamed>:0] create table if not …; rows affected: 0, rows returned: 0, elapsed: 11.491ms

create table if not exists peer (
  guid blob primary key not null,
  id varchar(100) not null,
  uuid blob not null,
  pk blob not null,
  created_at datetime not null default(current_timestamp),
  user blob,
  status tinyint,
  note varchar(300),
  info text not null
) without rowid;
create unique index if not exists index_peer_id on peer (id);
create index if not exists index_peer_user on peer (user);
create index if not exists index_peer_created_at on peer (created_at);
create index if not exists index_peer_status on peer (status);

[2026-04-14 14:19:02.359547 +00:00] INFO [src/rendezvous_server.rs:107] serial=0
[2026-04-14 14:19:02.359594 +00:00] INFO [src/common.rs:45] rendezvous-servers=["localhost"]
[2026-04-14 14:19:02.359600 +00:00] INFO [src/rendezvous_server.rs:109] Listening on tcp/udp :21116
[2026-04-14 14:19:02.359601 +00:00] INFO [src/rendezvous_server.rs:110] Listening on tcp :21115, extra port for NAT test
[2026-04-14 14:19:02.359602 +00:00] INFO [src/rendezvous_server.rs:111] Listening on websocket :21118
[2026-04-14 14:19:02.359609 +00:00] DEBUG [libs/hbb_common/src/udp.rs:36] Receive buf size of udp [::]:21116: Ok(212992)
[2026-04-14 14:19:02.359628 +00:00] DEBUG [src/rendezvous_server.rs:1357] listen on udp Some([::]:21116)
[2026-04-14 14:19:02.359641 +00:00] INFO [src/rendezvous_server.rs:146] mask: None
[2026-04-14 14:19:02.359642 +00:00] INFO [src/rendezvous_server.rs:147] local-ip: ""
[2026-04-14 14:19:02.359658 +00:00] INFO [src/common.rs:45] relay-servers=["localhost"]
[2026-04-14 14:19:02.359676 +00:00] DEBUG [src/rendezvous_server.rs:1369] listen on tcp Ok([::]:21116)
[2026-04-14 14:19:02.359690 +00:00] DEBUG [src/rendezvous_server.rs:1369] listen on tcp Ok([::]:21115)
[2026-04-14 14:19:02.359697 +00:00] DEBUG [src/rendezvous_server.rs:1369] listen on tcp Ok([::]:21118)
[2026-04-14 14:19:02.359698 +00:00] INFO [src/rendezvous_server.rs:161] ALWAYS_USE_RELAY=Y
[2026-04-14 14:19:02.359707 +00:00] INFO [src/rendezvous_server.rs:193] Start
[2026-04-14 14:19:02.359722 +00:00] DEBUG [libs/hbb_common/src/udp.rs:36] Receive buf size of udp [::]:0: Ok(212992)
[2026-04-14 14:19:02.361504 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/hyper-0.14.32/src/client/connect/http.rs:542] connecting to 49.12.46.241:443
[2026-04-14 14:19:02.424698 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/hyper-0.14.32/src/client/connect/http.rs:545] connected to 49.12.46.241:443
[2026-04-14 14:19:02.424730 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/rustls-0.21.12/src/client/hs.rs:73] No cached session for DnsName("api.rustdesk.com")
[2026-04-14 14:19:02.424797 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/rustls-0.21.12/src/client/hs.rs:132] Not resuming any session
[2026-04-14 14:19:02.487632 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/rustls-0.21.12/src/client/hs.rs:615] Using ciphersuite TLS13_AES_256_GCM_SHA384
[2026-04-14 14:19:02.487652 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/rustls-0.21.12/src/client/tls13.rs:142] Not resuming
[2026-04-14 14:19:02.487760 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/rustls-0.21.12/src/client/tls13.rs:381] TLS1.3 encrypted extensions: [ServerNameAck, Protocols([ProtocolName(687474702f312e31)])]
[2026-04-14 14:19:02.487779 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/rustls-0.21.12/src/client/hs.rs:472] ALPN protocol is Some(b"http/1.1")
[2026-04-14 14:19:02.489695 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/hyper-0.14.32/src/proto/h1/io.rs:352] flushed 583 bytes
[2026-04-14 14:19:02.554802 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/hyper-0.14.32/src/proto/h1/io.rs:211] parsed 9 headers
[2026-04-14 14:19:02.554861 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/hyper-0.14.32/src/proto/h1/conn.rs:224] incoming body is content-length (73 bytes)
[2026-04-14 14:19:02.554907 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/hyper-0.14.32/src/proto/h1/conn.rs:300] incoming body completed
[2026-04-14 14:19:02.554987 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/hyper-0.14.32/src/client/pool.rs:380] pooling idle connection for ("https", api.rustdesk.com)

Key Observations from Logs

• Keypair is generated successfully
• Server starts and listens on expected ports:
  • 21115 (TCP, NAT test)
  • 21116 (TCP/UDP)
  • 21118 (WebSocket)
• Relay and rendezvous servers are set to localhost
• No obvious startup errors

Port Connectivity Test

On another terminal, verify all required ports appear reachable locally:

$ nc -v -w 1 localhost 21115 
Connection to localhost port 21115 [tcp/*] succeeded!

$ nc -v -w 1 localhost 21116
Connection to localhost port 21116 [tcp/*] succeeded!

$ nc -v -w 1 -u localhost 21116
Connection to localhost port 21116 [udp/*] succeeded!

$ nc -v -w 1 localhost 21117
Connection to localhost port 21117 [tcp/*] succeeded!

$ nc -v -w 1 localhost 21118
Connection to localhost port 21118 [tcp/*] succeeded!
HJ
idjtw99rmb6*

Client Configuration

Configured the client manually using ID Server and Key

• ID Server: localhost
• Key: (public key auto-generated from server logs)

Client UI

• Initial state: "Connecting to the RustDesk network..."

  

• Final state: "Not ready. Please check your connection"

  

Server Logs During Client Attempts

Each client attempt results in a short-lived TCP connection:

[2026-04-14 14:19:18.722947 +00:00] DEBUG [src/rendezvous_server.rs:1143] Tcp connection from [::1]:38376, ws: false
[2026-04-14 14:19:18.723942 +00:00] DEBUG [src/rendezvous_server.rs:1199] Tcp connection from [::1]:38376 closed
[2026-04-14 14:20:20.902202 +00:00] DEBUG [src/rendezvous_server.rs:1143] Tcp connection from [::1]:58324, ws: false
[2026-04-14 14:20:21.722775 +00:00] DEBUG [src/rendezvous_server.rs:1143] Tcp connection from [::1]:58326, ws: false
[2026-04-14 14:20:21.723320 +00:00] DEBUG [src/rendezvous_server.rs:1199] Tcp connection from [::1]:58326 closed
[2026-04-14 14:20:21.913355 +00:00] DEBUG [src/rendezvous_server.rs:1199] Tcp connection from [::1]:58324 closed
[2026-04-14 14:21:07.938607 +00:00] DEBUG [src/rendezvous_server.rs:1143] Tcp connection from [::1]:48276, ws: false
[2026-04-14 14:21:08.947254 +00:00] DEBUG [src/rendezvous_server.rs:1199] Tcp connection from [::1]:48276 closed
[2026-04-14 14:21:22.724163 +00:00] DEBUG [src/rendezvous_server.rs:1143] Tcp connection from [::1]:53340, ws: false
[2026-04-14 14:21:22.724730 +00:00] DEBUG [src/rendezvous_server.rs:1199] Tcp connection from [::1]:53340 closed
[2026-04-14 14:22:26.723989 +00:00] DEBUG [src/rendezvous_server.rs:1143] Tcp connection from [::1]:48848, ws: false
[2026-04-14 14:22:26.724796 +00:00] DEBUG [src/rendezvous_server.rs:1199] Tcp connection from [::1]:48848 closed
[2026-04-14 14:23:27.724178 +00:00] DEBUG [src/rendezvous_server.rs:1143] Tcp connection from [::1]:46810, ws: false
[2026-04-14 14:23:27.724818 +00:00] DEBUG [src/rendezvous_server.rs:1199] Tcp connection from [::1]:46810 closed
[2026-04-14 14:25:24.897200 +00:00] DEBUG [src/rendezvous_server.rs:1143] Tcp connection from [::1]:58400, ws: false
[2026-04-14 14:25:24.897714 +00:00] DEBUG [src/rendezvous_server.rs:1199] Tcp connection from [::1]:58400 closed
[2026-04-14 14:26:25.901243 +00:00] DEBUG [src/rendezvous_server.rs:1143] Tcp connection from [::1]:38400, ws: false
[2026-04-14 14:26:25.901966 +00:00] DEBUG [src/rendezvous_server.rs:1199] Tcp connection from [::1]:38400 closed
[2026-04-14 14:27:28.902146 +00:00] DEBUG [src/rendezvous_server.rs:1143] Tcp connection from [::1]:52576, ws: false
[2026-04-14 14:27:28.902845 +00:00] DEBUG [src/rendezvous_server.rs:1199] Tcp connection from [::1]:52576 closed
[2026-04-14 14:28:31.902305 +00:00] DEBUG [src/rendezvous_server.rs:1143] Tcp connection from [::1]:36200, ws: false
[2026-04-14 14:28:31.903039 +00:00] DEBUG [src/rendezvous_server.rs:1199] Tcp connection from [::1]:36200 closed
[2026-04-14 14:29:32.902085 +00:00] DEBUG [src/rendezvous_server.rs:1143] Tcp connection from [::1]:53684, ws: false
[2026-04-14 14:29:32.903013 +00:00] DEBUG [src/rendezvous_server.rs:1199] Tcp connection from [::1]:53684 closed
[2026-04-14 14:30:33.902034 +00:00] DEBUG [src/rendezvous_server.rs:1143] Tcp connection from [::1]:60916, ws: false
[2026-04-14 14:30:33.902629 +00:00] DEBUG [src/rendezvous_server.rs:1199] Tcp connection from [::1]:60916 closed

This repeats periodically, suggesting:

• The client can reach the server
• The connection is immediately closed

Additional Notes

• Instead of using localhost in compose.yaml and Client Configuration, I tried using the machine's local IP address.

  $ ipconfig getifaddr en0

[ghost]

same here

[p0we7]

Has anyone fixed this issue?

----- UPDATE -----
I found the cause of the problem.

I was running a VPN service alongside the hbbs server, and I used the tun0 interface to handle all traffic.

Since the heartbeat packet traffic for hbbs was handled by tun0, the heartbeat packets were sent in the wrong direction.

You can try using the following command to check if the database path is correct, to better identify the issue.

sudo tcpdump -ni any udp port 21116

[electriquo]

If it wasn't clear, I am using a vanilla setup without any VPN's etc.
Any idea what's wrong?

[p0we7]

I suggest using the above tcpdump command to capture packets first, as this will provide better help in identifying the issue.

Also, if your rustdesk server is listening on localhost, tcpdump should specify the lo interface.

[ELHart05]

Your TCP tests are all green, but the part of the RustDesk handshake that actually makes a client go "ready" — ID registration and heartbeat — runs over UDP/21116, not TCP. The short TCP connections you see opening and closing are normal: those are the client's NAT-test / connection probes (the TCP listener on 21116 only handles NAT-test and "online" queries). The registration that has to succeed before the client is "ready" comes in on UDP (RegisterPeer / RegisterPk), and that's the path that's broken in your setup. There are three separate problems feeding into this:

1. RELAY-SERVERS=localhost and RENDEZVOUS-SERVERS=localhost are wrong (and harmful)

These values are not "where hbbs runs" — they are values hbbs hands back to clients:

• relay-servers is sent to the connecting client so it knows where the relay (hbbr) is. With a single entry, hbbs returns it verbatim (rendezvous_server.rs::get_relay_server returns relay_servers[0]), so the client is told to open localhost:21117 — i.e. its own machine.
• rendezvous-servers is a list of rendezvous/relay servers that hbbs shares with peers in multi-server setups. Pointing it at localhost serves no purpose in a single-server setup.

Because you also set ALWAYS_USE_RELAY=Y, every session is forced through the relay (hbbs flags the NAT type as symmetric to force relay), so the bad localhost relay address guarantees failure once a connection is attempted.

If hbbr runs on the same host and default port (21117) as hbbs, you don't need RELAY-SERVERS/-r at all — the RustDesk docs confirm the relay is created implicitly on the same machine and you don't have to specify it. When relay-servers is empty, hbbs returns an empty relay address and the client falls back to the ID-server host it already connected to. Only set RELAY-SERVERS (to a value the client can reach, e.g. your server's LAN IP) if hbbr is on a different host/port. So: drop both RELAY-SERVERS and RENDEZVOUS-SERVERS, and drop ALWAYS_USE_RELAY=Y until the basic connection works.

A note on env var names: hbbs uppercases the flag and turns _→-, so it reads RELAY-SERVERS / RENDEZVOUS-SERVERS (hyphens) — your names were being picked up (your log shows relay-servers=["localhost"]), which is exactly the problem.

2. macOS + Rancher Desktop + network_mode: host is the likely real culprit

On macOS the containers run inside a Lima VM, so network_mode: host binds to the VM's interfaces, not your Mac. Rancher Desktop auto-forwards listening ports from the VM, but UDP forwarding through Lima has historically been the fragile part of this stack (it's had a rocky history and bugs have persisted into recent Lima releases). Two consequences for you:

• Your nc -u localhost 21116 "succeeded" line is meaningless — UDP is connectionless, so nc -u reports success even when nothing is listening. It is not evidence that UDP/21116 works.
• On macOS, prefer explicit published ports over network_mode: host, and make sure 21116 is published for both TCP and UDP.

3. Use a real address for the ID server, not localhost

localhost tends to resolve to IPv6 ::1 (hence the [::1] in your logs). Use the Mac's LAN IP (ipconfig getifaddr en0) for both the compose ports and the client's ID Server so the path is unambiguous and you can later test from a second device.

---

Suggested compose.yaml

services:
  hbbs:
    container_name: hbbs
    image: docker.io/rustdesk/rustdesk-server:1.1.15
    command: hbbs            # no -r needed: hbbr is local on default port
    volumes:
      - ./data:/root
    ports:
      - "21115:21115"
      - "21116:21116"        # TCP
      - "21116:21116/udp"    # UDP — required for client registration/heartbeat
      - "21118:21118"        # only if you need the web client / websocket
    environment:
      - RUST_LOG=debug
    depends_on:
      - hbbr
    restart: unless-stopped

  hbbr:
    container_name: hbbr
    image: docker.io/rustdesk/rustdesk-server:1.1.15
    command: hbbr
    volumes:
      - ./data:/root
    ports:
      - "21117:21117"
      - "21119:21119"        # only if you need the web client / websocket
    restart: unless-stopped

Bring it up with docker compose up (not run --service-ports, which is meant for one-off runs).

Client config

• ID Server: your Mac's LAN IP (e.g. 192.168.x.y), not localhost
• Relay Server: leave blank
• Key: the value from Public key: ... in the hbbs log

How to confirm it's the UDP path

This is exactly what @p0we7's tcpdump tip is for. With the client trying to connect, run on the host:

sudo tcpdump -ni any udp port 21116

You should see UDP packets from the client and a reply. (As @p0we7 noted, if the server is only listening on loopback, also try the loopback interface — -i lo0 on macOS.) If you see the client's packets but no reply reaching the container (or no packets at all), it's the macOS/Rancher UDP-forwarding issue, not your config — in that case make sure you're on a current Rancher Desktop, use published ports as above, and if it still fails, test with the server on a Linux host or small VM where host networking and UDP forwarding behave normally.

A genuinely "ready" client has registered over UDP; until that UDP round-trip works, the [::1]/short-TCP churn in your log is all you'll ever see.

If after dropping the localhost relay/rendezvous values + ALWAYS_USE_RELAY and publishing UDP/21116 it still won't go ready, post the tcpdump output and the client log (~/Library/Logs/RustDesk/ on macOS) — that will tell us whether it's stuck at register, key confirmation, or relay.

[electriquo]

Thank you for your attention and for the detailed, clear explanation!

RustDesk Client still cannot reach HBBS/HBBR.
That's what I did...

First Terminal

Capture network traffic

$ sudo tcpdump -ni any udp port 21116 -w rustdesk-21116.pcap
Password:
tcpdump: data link type PKTAP
tcpdump: listening on any, link-type PKTAP (Apple DLT_PKTAP), snapshot length 524288 bytes

Second Terminal

Spin-up RustDesk server and relay

$ ipconfig getifaddr en0
192.168.10.6

$ cat compose.yml
services:
  hbbs:
    container_name: hbbs
    image: docker.io/rustdesk/rustdesk-server:1.1.15
    command: hbbs
    volumes:
      - ./data:/root
    depends_on:
      - hbbr
    restart: unless-stopped
    environment:
      - RUST_LOG=debug
    ports:
      - 21114:21114
      - 21115:21115
      - 21116:21116
      - 21116:21116/udp
      - 21118:21118
  hbbr:
    container_name: hbbr
    image: docker.io/rustdesk/rustdesk-server:1.1.15
    command: hbbr
    volumes:
      - ./data:/root
    restart: unless-stopped
    environment:
      - RUST_LOG=debug
    ports:
      - 21117:21117
      - 21119:21119

$ docker compose config
...

$ docker compose up -d
WARN[0000] No services to build
[+] up 2/2
 ✔ Container hbbr Created   0.0s
 ✔ Container hbbs Created   0.0s

$ docker compose ps --services --status running
hbbr
hbbs

$ docker compose logs hbbs
hbbs  | [2026-06-03 20:03:38.545861 +00:00] INFO [libs/hbb_common/src/config.rs:895] Generated new keypair for id:
hbbs  | [2026-06-03 20:03:38.546770 +00:00] INFO [src/common.rs:147] Private/public key written to id_ed25519/id_ed25519.pub
hbbs  | [2026-06-03 20:03:38.546782 +00:00] DEBUG [src/common.rs:148] Public key: XHV2qjjDfv0wwpAZOhTWzqejiHp7I7yPyBTCgQpWO80=
hbbs  | [2026-06-03 20:03:38.547052 +00:00] INFO [src/rendezvous_server.rs:1251] Key: XHV2qjjDfv0wwpAZOhTWzqejiHp7I7yPyBTCgQpWO80=
hbbs  | [2026-06-03 20:03:38.547060 +00:00] INFO [src/peer.rs:84] DB_URL=./db_v2.sqlite3
hbbs  | [2026-06-03 20:03:38.549088 +00:00] DEBUG [src/database.rs:58] MAX_DATABASE_CONNECTIONS=1
hbbs  | [2026-06-03 20:03:38.551545 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/hyper-0.14.32/src/client/connect/dns.rs:122] resolving host="api.rustdesk.com"
hbbs  | [2026-06-03 20:03:38.554660 +00:00] DEBUG [<unnamed>:0] PRAGMA page_size = 4096; …; rows affected: 0, rows returned: 2, elapsed: 4.995ms
hbbs  |
hbbs  | PRAGMA page_size = 4096;
hbbs  | PRAGMA locking_mode = NORMAL;
hbbs  | PRAGMA journal_mode = WAL;
hbbs  | PRAGMA foreign_keys = ON;
hbbs  | PRAGMA synchronous = FULL;
hbbs  | PRAGMA auto_vacuum = NONE;
hbbs  |
hbbs  | [2026-06-03 20:03:38.564890 +00:00] DEBUG [<unnamed>:0] create table if not …; rows affected: 0, rows returned: 0, elapsed: 10.064ms
hbbs  |
hbbs  | create table if not exists peer (
hbbs  |   guid blob primary key not null,
hbbs  |   id varchar(100) not null,
hbbs  |   uuid blob not null,
hbbs  |   pk blob not null,
hbbs  |   created_at datetime not null default(current_timestamp),
hbbs  |   user blob,
hbbs  |   status tinyint,
hbbs  |   note varchar(300),
hbbs  |   info text not null
hbbs  | ) without rowid;
hbbs  | create unique index if not exists index_peer_id on peer (id);
hbbs  | create index if not exists index_peer_user on peer (user);
hbbs  | create index if not exists index_peer_created_at on peer (created_at);
hbbs  | create index if not exists index_peer_status on peer (status);
hbbs  |
hbbs  | [2026-06-03 20:03:38.564916 +00:00] INFO [src/rendezvous_server.rs:107] serial=0
hbbs  | [2026-06-03 20:03:38.564920 +00:00] INFO [src/common.rs:45] rendezvous-servers=[]
hbbs  | [2026-06-03 20:03:38.564921 +00:00] INFO [src/rendezvous_server.rs:109] Listening on tcp/udp :21116
hbbs  | [2026-06-03 20:03:38.564921 +00:00] INFO [src/rendezvous_server.rs:110] Listening on tcp :21115, extra port for NAT test
hbbs  | [2026-06-03 20:03:38.564922 +00:00] INFO [src/rendezvous_server.rs:111] Listening on websocket :21118
hbbs  | [2026-06-03 20:03:38.564930 +00:00] DEBUG [libs/hbb_common/src/udp.rs:36] Receive buf size of udp [::]:21116: Ok(212992)
hbbs  | [2026-06-03 20:03:38.564947 +00:00] DEBUG [src/rendezvous_server.rs:1357] listen on udp Some([::]:21116)
hbbs  | [2026-06-03 20:03:38.564955 +00:00] INFO [src/rendezvous_server.rs:146] mask: None
hbbs  | [2026-06-03 20:03:38.564955 +00:00] INFO [src/rendezvous_server.rs:147] local-ip: ""
hbbs  | [2026-06-03 20:03:38.564957 +00:00] INFO [src/common.rs:45] relay-servers=[]
hbbs  | [2026-06-03 20:03:38.564969 +00:00] DEBUG [src/rendezvous_server.rs:1369] listen on tcp Ok([::]:21116)
hbbs  | [2026-06-03 20:03:38.564974 +00:00] DEBUG [src/rendezvous_server.rs:1369] listen on tcp Ok([::]:21115)
hbbs  | [2026-06-03 20:03:38.564980 +00:00] DEBUG [src/rendezvous_server.rs:1369] listen on tcp Ok([::]:21118)
hbbs  | [2026-06-03 20:03:38.564981 +00:00] INFO [src/rendezvous_server.rs:161] ALWAYS_USE_RELAY=N
hbbs  | [2026-06-03 20:03:38.564989 +00:00] INFO [src/rendezvous_server.rs:193] Start
hbbs  | [2026-06-03 20:03:38.565011 +00:00] DEBUG [libs/hbb_common/src/udp.rs:36] Receive buf size of udp [::]:0: Ok(212992)
hbbs  | [2026-06-03 20:03:38.572214 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/hyper-0.14.32/src/client/connect/http.rs:542] connecting to 49.12.46.241:443
hbbs  | [2026-06-03 20:03:38.641802 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/hyper-0.14.32/src/client/connect/http.rs:545] connected to 49.12.46.241:443
hbbs  | [2026-06-03 20:03:38.641825 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/rustls-0.21.12/src/client/hs.rs:73] No cached session for DnsName("api.rustdesk.com")
hbbs  | [2026-06-03 20:03:38.641888 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/rustls-0.21.12/src/client/hs.rs:132] Not resuming any session
hbbs  | [2026-06-03 20:03:38.712093 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/rustls-0.21.12/src/client/hs.rs:615] Using ciphersuite TLS13_AES_256_GCM_SHA384
hbbs  | [2026-06-03 20:03:38.712119 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/rustls-0.21.12/src/client/tls13.rs:142] Not resuming
hbbs  | [2026-06-03 20:03:38.712227 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/rustls-0.21.12/src/client/tls13.rs:381] TLS1.3 encrypted extensions: [ServerNameAck, Protocols([ProtocolName(687474702f312e31)])]
hbbs  | [2026-06-03 20:03:38.712246 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/rustls-0.21.12/src/client/hs.rs:472] ALPN protocol is Some(b"http/1.1")
hbbs  | [2026-06-03 20:03:38.713995 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/hyper-0.14.32/src/proto/h1/io.rs:352] flushed 572 bytes
hbbs  | [2026-06-03 20:03:38.795558 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/hyper-0.14.32/src/proto/h1/io.rs:211] parsed 9 headers
hbbs  | [2026-06-03 20:03:38.795619 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/hyper-0.14.32/src/proto/h1/conn.rs:224] incoming body is content-length (73 bytes)
hbbs  | [2026-06-03 20:03:38.795674 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/hyper-0.14.32/src/proto/h1/conn.rs:300] incoming body completed
hbbs  | [2026-06-03 20:03:38.795742 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/hyper-0.14.32/src/client/pool.rs:380] pooling idle connection for ("https", api.rustdesk.com)

RustDesk Client

Settings > Network > ID/Relay server:

• Key: XHV2qjjDfv0wwpAZOhTWzqejiHp7I7yPyBTCgQpWO80
• ID server: 192.168.10.6

"Not ready. Please check your connection"

If after dropping the localhost relay/rendezvous values + ALWAYS_USE_RELAY and publishing UDP/21116 it still won't go ready, post the tcpdump output and the client log (~/Library/Logs/RustDesk/ on macOS) — that will tell us whether it's stuck at register, key confirmation, or relay.

• TCPDump capture file: rustdesk-21116.pcap.tar.gz
• RuskDesk client log: RustDesk_rCURRENT.log

[ELHart05]

Thanks for the detailed follow-up — and the good news first: your config is correct now. The startup log confirms relay-servers=[], rendezvous-servers=[], ALWAYS_USE_RELAY=N, you're publishing UDP/21116, and the client points at the LAN IP. So config is off the table, and your two attachments actually pin down where it's stuck.

Both files agree on one thing: your client's packets reach the server's port, but the server replies to none of them.

The pcap

Every UDP flow to :21116 is one-way:

192.168.10.6:57749  ->  :21116    18 sent     0 back
192.168.10.6:62464  ->  :21116    16 sent     0 back
192.168.10.4:64773  ->  :21116    11 sent     0 back
192.168.10.4:52079  ->  :21116     5 sent     0 back

Two clients (.4 and .6), every packet the same 85-byte register_pk, and not one reply on any flow.

The client log

register_pk of 192.168.10.6:21116 due to key not confirmed

every ~3s. Worth being precise about this line: it does not mean your key is wrong. It means the client sent its register_pk and is still waiting for the server's RegisterPkResponse — until that comes back, the client keeps the "not confirmed" flag and resends on its 3-second timer. The packets in your pcap are exactly those resends. So the real question is narrow: why does the server never answer?

Two things cause total silence like this, and one command tells them apart

With the client running and trying to connect, tail the server:

docker compose logs -f hbbs

If you see new lines while the client retries → the UDP packets are reaching hbbs and it isn't answering them. The usual reason is a server-key mismatch: when hbbs runs with a key, the client must be configured with that exact key, or hbbs can't read the packets and stays silent. Re-copy the key from the server log and make sure the field has the trailing =:

XHV2qjjDfv0wwpAZOhTWzqejiHp7I7yPyBTCgQpWO80=

Your screenshot shows it without the =, which is probably just trimming when you pasted, but check the actual field. One gotcha: hbbs generates a new keypair whenever ./data is empty, so if you ever wipe that folder the client's saved key goes stale.

If you see no new lines at all while the client retries → the packets aren't making it into the container, and this is the macOS Rancher Desktop / Lima UDP-forwarding problem. The tell is already in your log: the client's TCP connection to :21116 (the /api/sysinfo proxy fallback) does reach hbbs and gets closed, while UDP to the same port gets nothing. TCP-fine / UDP-dead through the Lima VM's port forwarder is long-standing — it sits under both Rancher Desktop and Colima, and "UDP forwarding fails in one direction" is a known report there. RustDesk registration lives entirely on that UDP path, so it never completes.

If it turns out to be the forwarder, the reliable fixes (best first)

1. Run hbbs/hbbr on a Linux host — a small VM, an old box, or a cheap VPS. Host networking and UDP behave normally, and it's the setup the docs assume.
2. Stay on the Mac but drop the VM: run the native macOS server binaries from releases directly. No container, no Lima, no port-forward.
3. Or try Docker Desktop instead of Rancher (different UDP handling, sometimes works where Rancher's doesn't), and keep Rancher on its latest version if you stay on it.

One cleanup either way

Drop the 21114:21114 mapping. 21114 is the Pro web-console/API port; the OSS server doesn't implement it, which is all those /api/sysinfo and /api/heartbeat IncompleteMessage errors in your log are. Harmless noise, and unrelated to "Not ready."

Paste the docker compose logs -f hbbs output from a connect attempt and we'll know right away whether it's the key or the forwarder.

[electriquo]

@ELHart05, THANK YOU!! :)

The culprit is Colima (which is based on Lima), which forwards ports over SSH. Since SSH port forwarding supports TCP only, UDP ports cannot be forwarded through this mechanism (see the SSH manual pages for details).

Instead of using Rancher Desktop/Colima/Docker, I switched to Vagrant/VirtualBox/Docker while keeping the same Docker Compose configuration. Everything worked flawlessly. If anyone is interested, I'd be happy to share the Vagrantfile.

This thread contains a lot of valuable information. It would be great to pin it or otherwise ensure that this knowledge remains easily discoverable for others who encounter the same issue.

[electriquo]

ID registration and heartbeat — runs over UDP/21116

What does it take to change it to TCP to ease such pains?

[ELHart05]

Glad you got it working, and thanks for digging up the Lima detail (SSH port-forwarding being TCP-only is the cleanest one-line explanation of the whole thread). On your question:

Short version: on the open-source server there's no switch for it, and it's UDP on purpose.

Registration and heartbeat (RegisterPeer / RegisterPk) are only wired into hbbs's UDP handler. The TCP listener on 21116 does exist, but it only carries the punch-hole and relay signaling; if a client tries to register over it, hbbs answers NOT_SUPPORT. So there's no server flag that moves registration onto TCP.

It's UDP because that's the rendezvous server's actual job: NAT hole-punching. hbbs reads your public ip:port straight off the incoming datagram and hands it to the peer, and the periodic re-register doubles as the keepalive that holds the NAT mapping open. The data path isn't tied to UDP the same way (relay through hbbr/21117 is TCP, the classic direct connection is a TCP simultaneous-open, and newer clients can also bring up a KCP-over-UDP direct path). It's specifically the signaling that lives on UDP.

There are two client-side options that move the signaling off UDP: disable-udp=Y (plain TCP on 21116) and allow-websocket=Y (WebSocket on 21118). The catch is the other end. WebSocket rendezvous is documented as Pro-only (Server Pro 1.5.7+, client 1.4.0+) and is relay-only, no P2P. And the OSS hbbs doesn't accept registration over its TCP/WebSocket handler at all (no RegisterPeer arm, RegisterPk returns NOT_SUPPORT), so flipping an OSS client to TCP won't actually complete a registration.

So for a self-hosted OSS setup the honest answer is you don't change it to TCP, you make sure UDP/21116 is genuinely forwarded, which is exactly what your move to Vagrant/VirtualBox fixed. TCP-only signaling is effectively a Pro feature today (via WebSocket), and it comes with the tradeoff of forcing relay for every session.

[electriquo]

@ELHart05, Million thanks. Much appreciated!

Do you think anything from this thread should be officially documented elsewhere, or should we simply link to it from the documentation? Either way, please let me know what changes you'd like to see, and I'll open a pull request.