RustDesk — Admin Guide

This guide is for administrators, security reviewers, packagers and developers working with the RustDesk client 1.5.0 (commit a7f2260). It covers architecture, the complete configuration model, deployment and packaging, the security model, operations, performance tuning, integrations with a self-hosted server API, and developer internals. Day-to-day usage is in the companion User Guide.

1. Executive Summary

Important

The default configuration uses the public ID server rs-ny.rustdesk.com with key OeVuKk5nlHiXp+APNn0Y3pC1Iwpwn44JGqrQCsWqmBw=. Organizations that need to control metadata and relay paths should deploy their own server and distribute custom-rendezvous-server, relay-server, api-server and key to every client.

2. Architecture

2.1 System overview

                          +----------------------------+
                          |  ID / rendezvous (hbbs)    |  TCP+UDP 21116, TCP 21115 (NAT test)
                          |  optional HTTP API 21114   |  WebSocket 21118
                          +-------------+--------------+
                 RegisterPeer/Pk (15 s) |  PunchHole / FetchLocalAddr / RequestRelay
        +-------------------------------+-------------------------------+
        |                                                               |
+-------v---------------------------+                   +---------------v-------------------+
|  CONTROLLER (client)              |                   |  CONTROLLED (host)                 |
|  Flutter UI  <-FFI->  librustdesk |  race: TCP punch  |  --service (SYSTEM/root)           |
|   session / io_loop / decoders    |<=== UDP+KCP ====> |    supervises --server             |
|   port_forward, file jobs         |     IPv6+KCP      |  --server (user): RendezvousMediator|
|                                   |     WebRTC        |    Connection, services:           |
+-------------------+---------------+                   |    monitorN, audio, clipboard,     |
                    |      fallback                     |    input, display, printer,        |
                    |   +----------------------+        |    terminal (per connection)       |
                    +==>|  relay (hbbr) 21117  |<=======+  --cm   Connection Manager (UI)    |
                        |  WS relay 21119      |        |  --tray tray icon                  |
                        +----------------------+        +------------------------------------+

2.2 Component inventory

2.3 Cargo workspace layers

2.4 Process model

IPC endpoints: Windows named pipe \\.\pipe\RustDesk\query<postfix>; Linux/macOS /tmp/RustDesk-<euid>/ipc<postfix> (the _service and _uinput_* postfixes live in /tmp/RustDesk-service/). Postfixes: "" (main), _service, _cm, _pa (PulseAudio on Linux), _url (macOS), _whiteboard, _portable_service, _uinput_*, _drm.

Note

If a --server cannot bind the main IPC, it logs ipc is occupied by another process, try kill it, kills the main-window process and exits. Non-server processes pull configuration from the server over IPC at start (Data::SyncConfig), so the --server process is the source of truth for options at runtime.

2.5 Connection establishment

1. Controller guards: incoming-only builds refuse (Incoming only mode).
2. Direct IP or domain:port targets skip rendezvous and connect by TCP (bare IP → port 21118).
3. In parallel the controller prepares an IPv6 probe, a UDP NAT socket, and a WebRTC offer (disabled with a proxy).
4. The rendezvous socket is secured (secure_tcp) when a WebRTC offer rides on it (mandatory) or when a key plus token/switch code exists.
5. PunchHoleRequest{id, token, nat_type, licence_key, conn_type, version, udp_port, force_relay, socket_addr_v6, switch_code, webrtc_sdp_offer} goes to hbbs.
6. The host reacts to PunchHole (UDP/TCP punch, IPv6, WebRTC answer), FetchLocalAddr (same LAN) or RequestRelay.
7. The controller races TCP, UDP/KCP, IPv6/KCP and WebRTC; direct timeouts are 1 s on LAN or symmetric NAT, else punch time ×6 (×3 after a previous direct failure).
8. On failure or forced relay: RequestRelay → TCP to hbbr 21117 with the shared UUID.
9. Secure handshake (section 6), then login.

Labels shown to users: TCP, UDP, IPv6, WebRTC, WebRTC/IPv6, Relay, WebSocket. direct = false for relay, WebSocket and TURN-relayed WebRTC.

2.6 Service model on the host

Services are GenericService threads keyed by name: audio, display, clipboard, file-clipboard (feature), mouse_cursor, mouse_pos, window_focus (desktop; X11 only on Linux), remote-printer (Windows Flutter), and lazily created monitor<N> / camera<N> video services. Terminal services are per connection.

• A connection subscribes only to services its permissions allow (for example no audio if audio is disabled, no clipboard without clipboard permission).
• The run() loop backs off from 30 ms to 1000 ms on errors and logs Error of {name} service: {err}.
• Any change needing a new capturer/encoder raises SWITCH, which restarts the video service (codec change, new subscriber, quality change on encoders that cannot change on the fly, privacy-mode change, recording change).

2.7 Caching

Note

Values equal to a default (including a custom-client default) are never written to disk, and options present in an override layer are removed from disk. Config files therefore do not show effective defaults; read effective values with rustdesk --option <key>.

3. System Requirements

3.1 Runtime platforms

3.2 Linux runtime dependencies (Debian control)

libgtk-3-0t64 | libgtk-3-0, libxcb-randr0, libxdo3 | libxdo4, libxfixes3, libxcb-shape0, libxcb-xfixes0, libasound2t64 | libasound2, libsystemd0, curl, libva2, libva-drm2, libva-x11-2, libgstreamer-plugins-base1.0-0, gstreamer1.0-pipewire (+ libatomic1 on armhf); Recommends libayatana-appindicator3-1. The DRM variant adds libdrm2 (>= 2.4.101), libegl1, libgles2 and a measured glibc floor.

3.3 Build toolchain

3.4 Hardware guidance

4. Configuration Mastery

4.1 Files and locations

All files are {APP_NAME}{suffix}.toml (TOML via confy, mode 0600 on Unix). APP_NAME defaults to RustDesk and changes with a custom client's app-name.

Note

The Windows and Linux folder names come from the directories_next crate's conventions combined with RustDesk's path rewrites. There is no environment variable that relocates the config directory.

4.2 Resolution layers

Boolean convention (option2bool):

4.3 Server / Settings options (RustDesk2.toml)

4.4 Local options (RustDesk_local.toml)

4.5 Display defaults (RustDesk_default.toml)

Per-peer only: force-always-relay, rdp_port (3389), rdp_username, rdp_password, os-username, os-password (the last four encrypted).

4.6 Custom-client settings

A signed custom.txt (next to the executable; macOS ../Resources/custom.txt) is base64 of an Ed25519-signed JSON verified with the embedded key 5Qbwsde3unUcJBtrx9ZkvUmwFNoExHzpryHuPUdqlWM=. app-name renames the app (service name, IPC paths, URI scheme, file names); default-settings and override-settings fill the DEFAULT/OVERWRITE maps (keys normalized _→-, routed to display, local, server or built-in layers); any other top-level key becomes a hard setting.

Built-in settings (custom client only):

Hard settings: conn-type (incoming/outgoing), disable-tcp-listen, disable-settings, disable-ab, disable-account, disable-installation, preset password + salt.

Important

Built-in and hard settings cannot be set through the UI, --option, or a config file — only through a correctly signed custom.txt. A hand-edited file fails signature verification and is ignored (logged only).

4.7 Servers and ports

Rendezvous server selection: Windows exe-name host → custom-rendezvous-server → compile-time PROD_RENDEZVOUS_SERVER (empty) → remembered lowest-latency server → built-in list; :21116 appended if no port.

4.8 Environment variables

No environment variable overrides the ID server, relay, API or key.

4.9 Import and export

5. Deployment

5.1 Deployment options

5.2 Windows EXE installation layout

rustdesk-1.5.0-x86_64.exe --silent-install printer=1

(Toast "Installation Successful!"; with the debug argument the batch window stays open for 300 s.)

5.3 Windows MSI

Public properties for msiexec:

Custom actions: CreateStartService, AddFirewallRules / RemoveFirewallRules, AddRegSoftwareSASGeneration, InstallPrinter / UninstallPrinter, TerminateProcesses, TerminateBrokers, TryStopDeleteService, RemoveRuntimeGeneratedFiles, RemoveAmyuniIdd, TryDeleteStartupShortcut, LaunchApp (non-silent only). UpgradeCode = uuid5(NAMESPACE_OID, "<app>.exe"), so upgrades are stable per app name; MajorUpgrade allows same-version upgrades.

Build the MSI: in res/msi, python preprocess.py [-d ../../rustdesk] [--app-name X] [-v X.Y.Z] [--conn-type incoming|outgoing] [--template] [--custom-arp JSON] [-m Manufacturer], then build msi.sln with Visual Studio 2022.

Warning

MSI and EXE installs are mutually exclusive: the MSI blocks installation over an EXE install (BlockSelfInstalledApp), and install_me refuses to run over an MSI install. Pick one installer type per fleet.

5.4 Linux packages

Unit file (res/rustdesk.service):

[Unit]
Description=RustDesk
Requires=network.target
After=systemd-user-sessions.service

[Service]
Type=simple
ExecStart=/usr/bin/rustdesk --service
ExecStop=pkill -f "rustdesk --"
PIDFile=/run/rustdesk.pid
KillMode=mixed
TimeoutStopSec=30
User=root
LimitNOFILE=100000
Environment="PULSE_LATENCY_MSEC=60" "PIPEWIRE_LATENCY=1024/48000"

[Install]
WantedBy=multi-user.target

The service loop runs --server as root at the login screen (or a Wayland greeter with the DRM build) and as the logged-in user otherwise, with DISPLAY, XAUTHORITY and TERM set. RustDesk actively removes ~/.config/autostart/rustdesk.desktop. A binary is considered "installed" when it lives under /usr or /nix/store.

Note

Non-systemd init systems get only the /usr/bin/rustdesk symlink from the deb; no service is installed. apt purge removes /root/.config/rustdesk only — user configs remain.

5.5 macOS

rustdesk --install-service on macOS only checks that both plists exist; install through the in-app Install button.

5.6 Docker

The repository Dockerfile builds a build container, not a runtime service:

docker build -t rustdesk-builder .
docker run --rm -it -v "$PWD":/home/user/rustdesk \
  -v rustdesk-git-cache:/home/user/.cargo/git \
  -v rustdesk-registry-cache:/home/user/.cargo/registry \
  rustdesk-builder --release

    Finished release [optimized] target(s)

Caution

There is no EXPOSE, VOLUME or CMD; the image does not run RustDesk or any server. Output files are root-owned; PUID/PGID from the README are ignored. The image pins vcpkg 2023.04.15, not the CI baseline, and builds only the legacy Sciter binary.

5.7 Building from source (native)

git clone --recurse-submodules https://github.com/rustdesk/rustdesk
cd rustdesk
export VCPKG_ROOT=$HOME/vcpkg
vcpkg/vcpkg install libvpx libyuv opus aom
python3 build.py --flutter --hwcodec --unix-file-copy-paste

(Debian/Ubuntu host: produces rustdesk-1.5.0.deb in the repository root)

Cargo features: flutter, hwcodec, vram (Windows), mediacodec (Android), drm, drm-wake, linux-pkg-config, unix-file-copy-paste, screencapturekit (macOS), inline (Sciter), resampler features use_dasp (default), use_samplerate, use_rubato. Release profile: lto = true, codegen-units = 1, panic = 'abort', strip = true.

The Flutter–Rust bridge is generated from src/flutter_ffi.rs:

cargo install flutter_rust_bridge_codegen --version 1.80.1 --features uuid --locked
flutter_rust_bridge_codegen --rust-input ./src/flutter_ffi.rs \
  --dart-output ./flutter/lib/generated_bridge.dart \
  --c-output ./flutter/macos/Runner/bridge_generated.h

(generates src/bridge_generated.rs, flutter/lib/generated_bridge.dart and the C header; all git-ignored)

5.8 CI/CD

Signing: Windows binaries are sent to a signing task server with res/job.py (BASE_URL, SECRET_KEY, SIGN_TIMEOUT, TIMEOUT), only when the SIGN_BASE_URL secret exists; macOS uses codesign + rcodesign notary-submit --staple; Android uses r0adkll/sign-android-release.

6. Security

6.1 Threat model summary

6.2 Authentication

Password verification. The host sends Hash{salt, challenge}; the client replies with SHA256(SHA256(password + salt) + challenge), compared in constant time. Temporary passwords are checked first (if enabled), then the permanent password (if enabled, or if built-in allow-logon-screen-password applies at a lock/logon screen).

Rate limiting (per process, in memory):

Two-factor authentication. TOTP (SHA1, 6 digits, 30 s step, skew 1, issuer "RustDesk Connection", account = device ID). The secret is stored encrypted in option 2fa. With a Telegram bot token (option bot), each 2FA-gated login sends the current code and the source IP to https://api.telegram.org/bot<token>/sendMessage. Trusted devices (hwid = SHA-256 of machine UID, plus ID, name and platform) skip 2FA for 90 days.

Account login (API). OIDC via /api/oidc/auth and polling /api/oidc/auth-query (1 s interval, 180 s max); username/password via /api/login. With "remember me", access_token and user_info are stored as local options.

6.3 Authorization and access control

Order of checks for an incoming session:

1. Admission control (64 unauthenticated total, 16 per IP).
2. IP whitelist → "Your IP is blocked by the peer" + alarm.
3. allow-only-conn-window-open → "The main window is not open".
4. Challenge sent; connection audit posted.
5. Login type latched (a different type later → "Connection not allowed").
6. Trusted-device check (may clear 2FA).
7. ID whitelist → "Your ID is blocked by the peer" (failure-counted).
8. Per-type permission (file, camera, terminal, tunnel).
9. Privacy mode already active → refused.
10. Username must equal this device's ID (or direct IP) → else "Offline".
11. Approve mode / password.
12. 2FA, then authorize.

Permission resolution. A server-pushed ControlPermissions bit pair (2 bits per permission: 1 = disable, 2 = enable) wins; otherwise the local enable-* option; on Flutter desktop access-mode=full forces everything on and view forces everything off. The Connection Manager can toggle keyboard, clipboard, audio, file, restart, recording, block-input and privacy-mode live.

Session scope. After authorization, messages outside the session type are logged; allow-scope-violation-alarm posts an alarm and allow-scope-violation-close closes the session.

Warning

allow-remote-config-modification is enforced only by the host's Flutter settings UI (it blocks the settings page while remote input is detected). It does not gate protocol-level actions. The API server's heartbeat strategy.config_options can set any option key, including whitelists, approve mode and permissions — protect the API server accordingly.

6.4 Encryption and key exchange

Caution

Direct IP access (direct-server=Y) listens on all interfaces on port 21118, performs no signed-key handshake and carries no server-side permissions. Enable it only on trusted networks, combine it with an IP whitelist, and prefer ID-based connections through your own server.

6.5 TLS / certificates

• HTTP API, wss:// and HTTPS proxies use rustls with bundled webpki-roots plus native OS roots, with a platform-verifier fallback; no revocation checking.
• On failure, native-tls is tried; invalid certificates are accepted only with allow-insecure-tls-fallback=Y (per host:port, cached).
• The *_strict HTTP client variants never fall back and refuse plain http:// URLs ("Strict HTTP client requires HTTPS").
• allow-websocket=Y skips RustDesk's own rendezvous key exchange and relies on wss; with an http:// API server the WebSocket scheme is plain ws://.
• webpki-roots is refreshed weekly by an automated PR workflow.

6.6 Secrets at rest

Anyone who can read the config files and obtain the machine UUID can decrypt these values; treat config directories as sensitive and restrict filesystem access.

6.7 Data sent to third parties by default

Heartbeat, sysinfo, audit and switch-grant uploads are disabled when the API host is *.rustdesk.com.

6.8 Hardening checklist

• [ ] Deploy your own ID/relay/API server and distribute the key to every client
• [ ] Set approve-mode and verification-method deliberately; avoid permanent passwords where attended support is enough
• [ ] Enforce 2FA for unattended hosts; review trusted devices
• [ ] Use whitelist (CIDR) for admin networks; keep direct-server off
• [ ] Disable unneeded permissions (enable-tunnel, enable-terminal, enable-file-transfer, enable-camera)
• [ ] Set enable-lan-discovery=N on hosts where the LAN is untrusted (discovery replies reveal ID, MAC, hostname and logged-in username)
• [ ] Set an unlock PIN; ship a signed custom client with disable-settings/hide-* where users must not change policy
• [ ] Keep allow-insecure-tls-fallback off; use https API servers
• [ ] Protect the API server — its strategies can rewrite any client option
• [ ] Restrict read access to config directories; do not copy them between machines

7. Operations

7.1 Start, stop and status

sudo systemctl restart rustdesk
rustdesk --get-id

123456789

Tip

--uninstall-service sets stop-service=Y, which persists: a later reboot will not start the service. Use --install-service (or Start service) to clear it.

7.2 Health checks

7.3 Logging

Each process role logs to its own subfolder named after its first argument (server, service, tray, cm, portable-service; the main UI has none).

• debug and above are written to file. The project's logging rule: anything that can fire per packet/frame/input must use trace or hbb_common::throttled_log!.
• Logs contain peer IPs and ports, device IDs, relay UUIDs, rendezvous hosts, NAT type and OIDC request results. No log statement prints passwords, tokens or keys.
• Heartbeat failures and Wayland portal errors are throttled (Wayland: repeat only when the cause changes or after 600 s).

Note

The session logs include source IPs ("Connection opened from <addr>", "direct access from <addr>"), so treat them as personal data under your retention policy.

7.4 Backup and restore

Restore on the same machine:

sudo systemctl stop rustdesk
sudo cp -a backup/rustdesk/. /root/.config/rustdesk/
sudo systemctl start rustdesk

(no output; the status bar returns to Ready with the original ID)

Moving to new hardware: re-apply options with --config / --option or a custom client rather than copying encrypted files; set the ID with --set-id if you need to keep it (6–16 chars, letter first).

7.5 Upgrades

7.6 Capacity notes

• One encoder per display is shared by all viewers; a new viewer restarts the encoder so everyone gets a key frame.
• The slowest viewer gates the frame rate of a display (capture waits up to 3 s for all viewers to fetch a frame).
• Terminal: max 100 terminal services per host, 1 MB scrollback buffer each; idle cleanup after 1 h (non-persistent) or 2 h (persistent with no terminals).
• Port-forward mux: 256 channels per tunnel.

8. Performance Tuning

8.1 Quality, bitrate and FPS

Bitrate table (kbps, VP8/VP9 base, nearest preset scaled by pixels): 1280×720 = 1000, 1920×1080 = 2073, 2560×1440 = 3000, 3840×2160 = 5000, 7680×4320 = 12000. Hardware encoders multiply by a factor (2.0 for H.264, 1.5 for H.265 below 2000 kbps, decaying toward 1.0).

8.2 Video QoS constants

8.3 Codec behaviour worth knowing

• Periodic keyframes are disabled (VPX KF_DISABLED, hardware GOP = i32::MAX) except while recording (every 240 frames).
• VAAPI encoders cannot change quality on the fly; quality changes restart the encoder.
• MediaCodec and VideoToolbox are not "latency free": the last frame is re-encoded up to 10 times when idle.
• The client marks a codec unsupported after 3 consecutive decode failures and renegotiates.
• Encoder creation failure falls back to VP9; hardware failures clear the cached hwcodec config.

8.4 Platform tips

Tip

Audio encoding stops automatically after 800 silent packets (about 8 s), and idle desktops send no new video frames with VPX/AOM/VRAM encoders, so idle sessions cost little bandwidth.

9. Integrations

9.1 Self-hosted server HTTP API (client side)

With builtin use-raw-tcp-for-api, API calls are tunnelled as HttpProxyRequest over an encrypted TCP connection to hbbs port 21116 (36 s timeout).

Deploy exit codes:

sudo rustdesk --assign --token "$TOKEN" --device_group_name "Servers" --note "rack 4"

Done!

9.2 Server Pro management scripts (res/*.py)

All take a positional command plus --url <api base> and --token <bearer>; filters are fuzzy (%value%) unless - or already containing %; bulk operations on more than one match require typing Y.

python3 res/devices.py view --url https://rd.example.com --token "$TOKEN" --offline_days 30

(prints matching devices with last_online at least 30 days ago)

Warning

devices.py and users.py without filters act on every record the list call returns. Always run view with the same filters first.

9.3 Plugin / extension system

There is no runtime plugin loader in the 1.5.0 client. Extension points are:

9.4 Other integrations

• RDP: tunnels to localhost:3389 on the host and launches mstsc on the controller, credentials via cmdkey.
• Wake-on-LAN: sent to MAC addresses from LAN discovery.
• Telegram: 2FA code delivery.
• Windows file clipboard: CLIPRDR (FileGroupDescriptorW / FileContents); Linux FUSE mounts cliprdr-client / cliprdr-server beside the IPC directory.

10. Developer Internals

10.1 Repository structure

10.2 Protocol

Two protobuf files in libs/hbb_common/protos define the wire protocol:

Framing is length-prefixed (bytes_codec.rs); after the key exchange every frame is secretbox-sealed with a counter nonce.

10.3 Connection state machine (host)

accept socket -> admission control -> identity_handshake (SignedId / PublicKey)
   -> Connection::start
      -> on_open: IP whitelist, window-open check, send Hash{salt,challenge}, audit "new"
      -> LoginRequest: latch type, trusted device, ID whitelist, per-type permission,
         privacy check, username==id, approve mode / password, 2FA
      -> authorize: rotate temp password, subscribe services (monitorN, audio, clipboard...)
      -> session loop: input, clipboard, file jobs, options, permission toggles,
         scope enforcement, idle / auto-disconnect timers
      -> close: lock-after-session-end, release keys, restore resolution, audit

10.4 Video pipeline

capturer (DXGI | GDI | Magnifier | Quartz | X11 SHM | PipeWire | DRM | Android)
   -> BGRA/texture frame -> (HDR->SDR on Windows) -> YUV (I420/NV12/I444)
   -> encoder (VPX | AOM | hwcodec | VRAM | MediaCodec), ratio from video_qos
   -> send_video_frame to subscribed connections -> wait for fetch (<= 3 s)
   -> sleep remainder of spf; recorder taps frames if recording

Windows fallbacks: DXGI empty → GDI; >3 no-image tries → GDI; ACCESS_LOST restarts up to 3 times per 10 s before GDI; other DXGI errors → GDI.

10.5 Keyboard modes

Support: Legacy always; Map needs peer ≥ 1.2.0 and not Android; Translate/Auto need peer ≥ 1.2.0. Unsupported saved modes fall back to the first supported (Legacy). Windows Pause is always sent as Legacy.

10.6 Code patterns and conventions (from AGENTS.md)

• No unwrap()/expect() in production code except tests and lock poisoning; prefer Result + ?.
• Tokio: never nest runtimes or block_on in async code; no locks held across .await; spawn_blocking for blocking work.
• Logging: per-event sites use log::trace! or hbb_common::throttled_log!(interval, level, ...).
• Imports: one braced use per crate, split only for differing #[cfg].
• Minimal, additive diffs: new logic in feature modules; shared files (src/core_main.rs, src/server/connection.rs, src/tray.rs) get one-line hooks.
• Client-only code belongs in libs/base; hbb_common changes require a server round-trip.
• Localization: src/lang/template.rs is the master key list (never edit for translations); en.rs only overrides keys whose display text differs; it.rs is hand-maintained; new keys use sentence case and are appended to every language file.
• Commits require a DCO sign-off (git commit -s).

10.7 Module reference (selected functions)

10.8 Testing Strategy

cargo test --locked --workspace --no-fail-fast -- --skip test_get_cursor_pos --skip test_get_key_state

test result: ok. ... passed; 0 failed; ...

CI runs unit tests only on x86_64 Linux (default features), three cursor Flutter tests on macOS arm64 PR builds, and a DRM-feature subset in the unattended-Wayland job. cargo fmt, clippy and MSRV jobs are commented out. Project policy: a fix gets 1–3 regression tests that fail on master and pass with the fix; no new test infrastructure without maintainer approval.

Note

The libs/hbb_common submodule must be checked out (git submodule update --init --recursive); the workspace does not load without it.

11. Troubleshooting

Operator-focused items. End-user dialogs (wrong password, portal prompts, macOS permission cards) are covered in the User Guide.

Start with the log of the right process role: problems accepting sessions are in the server log, service start/stop in service, approval UI in cm, and outgoing sessions in the main UI log (no subfolder).

Tip

Many connection problems are transport-specific. Before deep debugging, retry with <id>/r (forced relay): if the relayed session works, focus on NAT, UDP and firewall paths rather than authentication or capture.

11.1 Service and process

Error: ipc is occupied by another process, try kill it

Cause: A second --server could not bind the main IPC endpoint.

Solution:

1. Stop the service, kill stray rustdesk --server processes, start the service again.
2. On Linux check /tmp/RustDesk-<uid>/ for stale sockets owned by another user.

Prevention: Do not run the Flutter main UI and a manually started --server for the same user.

Error: service stays stopped after reboot

Cause: stop-service=Y is persisted (tray Stop service, --uninstall-service, Linux service honours it at start and disables itself).

Solution: rustdesk --install-service, Start service, or rustdesk --option stop-service "" as admin.

Prevention: Hide the stop button with built-in hide-stop-service on managed fleets.

Error: Installation and administrative privileges required!

Cause: A management command (--password, --set-id, --config, --option, --assign, --deploy, --set-unlock-pin) was run on a portable copy or without elevation.

Solution: Run from an elevated prompt / sudo against the installed binary.

Prevention: Script management commands after installation.

Error: Settings are disabled!

Cause: Hard setting disable-settings=Y (custom client).

Solution: Use a build with built-in allow-command-line-settings-when-settings-disabled=Y, or change policy through the server strategy.

Prevention: Decide CLI manageability when building the custom client.

Error: --config does nothing

Cause: --config is silent on success and on parse failure; the string may be malformed.

Solution: Read back with rustdesk --option custom-rendezvous-server and --option key.

Prevention: Generate strings with the UI Export Server Config, or use host=...,key=....

Error: Failed to set Ctrl-C handler: <e>

Cause: Linux --service could not install its signal handler.

Solution: Check for unusual process supervision; restart the unit.

Prevention: Run under the shipped systemd unit.

Error: Failed to write plists: <e>

Cause: macOS service --write-plists could not write the launchd files.

Solution: Run with administrator rights; check /Library/LaunchDaemons permissions.

Prevention: Use the in-app Install flow.

Error: daemon.plist not found in embedded resources

Cause: Broken macOS app bundle.

Solution: Reinstall the app from the dmg.

Prevention: Do not modify the bundle contents.

Error: Unknown app directory of current exe file

Cause: macOS app launched from an unexpected location.

Solution: Move RustDesk into /Applications.

Prevention: Deploy to /Applications only.

11.2 Registration and server

Error: Server requires deployment. Run rustdesk --deploy --token <api_token> on this device.

Cause: The server replied NOT_DEPLOYED; registration is throttled to once per 30 s.

Solution:

sudo rustdesk --deploy --token "$API_TOKEN"

Device deployed.

Prevention: Include --deploy in your install script for servers that require deployment.

Error: Id <id> is already used by another machine on the server. (exit 6)

Cause: --deploy --id requested an ID owned by another device.

Solution: Choose another ID or free it on the server.

Prevention: Plan ID naming.

Error: Cannot deploy an unregistrable device! / Cannot deploy Outgoing-only clients.

Cause: Built-in register-device=N or hard setting conn-type=outgoing.

Solution: Use a different client build for devices that must register.

Prevention: Match custom-client type to device role.

Error: Rendezvous connection is timeout

Cause: No message from hbbs for 1.5 × keep-alive on a TCP/WebSocket mediator.

Solution: Check the path to hbbs. Behind nginx WebSocket proxying, set proxy_read_timeout above 60 s.

Prevention: Monitor hbbs and any reverse proxy.

Error: Handshake failed: invalid public key from rendezvous server

Cause: The configured key is not a valid 32-byte base64 Ed25519 key, or the hbbs-supplied peer key did not verify.

Solution: Correct the key option; sessions otherwise downgrade to unencrypted.

Prevention: Distribute keys via export/import or custom clients.

Error: Signature mismatch in key exchange

Cause: The hbbs key exchange signature does not verify against the configured key (wrong key or impostor server).

Solution: Verify the server's public key file and the client key.

Prevention: Pin the key in a signed custom client.

Error: the rendezvous server did not complete the key exchange

Cause: A WebRTC offer required a secured rendezvous channel but hbbs is too old.

Solution: Upgrade hbbs, or disable WebRTC (enable-webrtc=N).

Prevention: Keep server and clients in step.

Error: ID changed unexpectedly

Cause: hbbs answered UUID_MISMATCH; the client regenerates its ID (Config::update_id()).

Solution: Communicate the new ID or restore with --set-id.

Prevention: Avoid cloning machines with the same config; each install must have its own machine UUID.

Error: too many unauthenticated connections from <ip>

Cause: Admission control (16 per IP, 64 total) during a burst or scan.

Solution: Investigate the source IP; legitimate clients retry.

Prevention: Use IP whitelists on exposed hosts; keep direct IP access off.

11.3 Capture and codecs

Warning

On Wayland, RustDesk deliberately does not reset a capturer after repeated "no frame" results, because resetting would re-trigger the portal consent dialog every few minutes. A frozen Wayland picture therefore needs a manual reconnect or a service restart.

Error: dxgi error, fall back to gdi / No image, fall back to gdi

Cause: DXGI Desktop Duplication failed or produced no frames.

Solution: Usually self-healing; GDI is slower and disables VRAM encoding. Update GPU drivers; check enable-directx-capture.

Prevention: Keep GPU drivers current.

Error: dxgi access lost after 3 restarts in 10 seconds, fall back to gdi

Cause: Repeated ACCESS_LOST (mode changes, secure desktop, driver resets).

Solution: Restart the session; investigate display mode churn.

Prevention: Avoid frequent resolution changes during sessions.

Error: MIT-SHM extension not working properly on select X11 server

Cause: The X server's SHM extension is broken (common in some VNC/Xvfb setups).

Solution: Use an X server with working MIT-SHM.

Prevention: Test capture on headless X setups before rollout.

Error: Fatal pipewire error (process exits)

Cause: A PipeWire capture error starting with "Did not receive a reply".

Solution: Restart PipeWire / the desktop portal; the service restarts --server.

Prevention: Keep PipeWire and portals updated.

Error: drm capturer for display N unavailable (...); falling back to PipeWire

Cause: DRM/KMS capture could not serve a display (unattended-Wayland build).

Solution: Check /usr/lib/rustdesk/libdrmtap.so.0 is present; review libdrmtap dlopen failed logs.

Prevention: Install the complete rustdesk-unattended-wayland package.

Error: Failed to create encoder: <err>, fallback to VP9

Cause: The negotiated encoder could not be created.

Solution: Automatic; if hardware, check drivers or disable enable-hwcodec.

Prevention: Keep the hwcodec probe results fresh (they reset when the GPU signature changes).

Error: new hw encoder failed: ..., clear config

Cause: A cached hardware encoder failed at runtime.

Solution: The cache is cleared and VP9 is used; the next probe re-evaluates.

Prevention: Disable hardware codec on GPUs with known issues (#16324, #16156).

Error: Please change codec and try again.

Cause: A screenshot was requested from a VRAM (texture) frame repeatedly.

Solution: Switch the session codec to VP9/AV1 and retry.

Prevention: Use software codecs when screenshots matter.

Error: HDR output but the SDR white level cannot be read, assuming 80 nits until it can

Cause: Windows HDR desktop on a build older than 1709 or an API failure.

Solution: None required; colors may be dim.

Prevention: Keep Windows updated.

11.4 Audio

Error: Invalid audio capture layout: sample_rate=<r>, channels=<c>

Cause: The capture device reports an unusable layout.

Solution: Choose another Audio Input Device (audio-input).

Prevention: Standardize audio devices on hosts.

Error: Failed to read audio data:<err> (Linux)

Cause: The PulseAudio _pa IPC (hosted by the CM process) failed.

Solution: Ensure PulseAudio/PipeWire-Pulse is running for the user; per code comment, reinstalling pulseaudio may help.

Prevention: Keep a user session with audio running.

Error: no system audio from Windows 7 hosts

Cause: WASAPI loopback is event-driven and does not work before Windows 10 1703.

Solution: Select a microphone/virtual input device instead.

Prevention: Upgrade hosts.

11.5 Input

Error: Rejected connection on protected uinput ipc channel due to executable mismatch

Cause: A process that is not the same RustDesk binary tried to use the uinput IPC.

Solution: Investigate the caller; after an upgrade, restart the service so all processes run the new binary.

Prevention: Restart the service after package upgrades.

Error: X11 input does nothing

Cause: libxdo could not be loaded at runtime; the stub turns input into no-ops.

Solution: Install libxdo3/libxdo4 (xdotool on Arch/SUSE).

Prevention: Install from distribution packages that declare the dependency.

Error: Block input has no effect

Cause: block_input is a no-op on Linux and macOS.

Solution: Use privacy mode on macOS; there is no equivalent on Linux.

Prevention: Document platform limits for your support staff.

11.6 Windows installation and elevation

Error: Application name must match [a-zA-Z0-9-]+

Cause: Custom client app name contains invalid characters.

Solution: Rebuild the custom client with a valid name.

Prevention: Validate names during branding.

Error: <app> is not installed.

Cause: Update requested with no installed copy.

Solution: Install first.

Prevention: Check install state in deployment scripts.

Error: Failed to run the update msi: <e> / Unsupported update file format

Cause: Updater could not launch the MSI or got an unexpected file.

Solution: Update manually with the new MSI.

Prevention: Allow msiexec and the download host.

Error: Failed to run portable service process

Cause: The elevated/SYSTEM helper for quick support could not start (also no display available!, already running).

Solution: Install RustDesk instead of using portable elevation.

Prevention: Install on managed machines.

Error: Failed to connect to connection manager

Cause: The server could not reach the _cm IPC after launching the CM (10 retries).

Solution: Restart RustDesk in the user session; check that a desktop session exists.

Prevention: Keep users logged in for attended approval flows.

Error: Win10 or greater required!

Cause: Remote printer install on older Windows.

Solution: Upgrade the host.

Prevention: Check OS version before enabling printing.

11.7 Virtual display and privacy mode

Error: There are already 4 monitors plugged in.

Cause: Amyuni IDD limit reached.

Solution: Plug out a virtual display.

Prevention: Use Plug out all at session end.

Error: Plugging in too frequently.

Cause: Headless plug-in is rate-limited to once per 3 s.

Solution: Wait and retry.

Prevention: None.

Error: The virtual display is managed by other processes.

Cause: Another process controls the Amyuni driver.

Solution: Close the other process or reboot.

Prevention: Avoid multiple virtual display tools.

Error: Failed to install driver.

Cause: The Amyuni IDD driver (usbmmidd_v2\usbmmIdd.inf) could not be installed.

Solution: Run as administrator; check driver signing policy.

Prevention: Pre-approve the driver in enterprise policy.

Error: Privacy occupied by another one.

Cause: Another connection owns privacy mode.

Solution: Wait for it to be released.

Prevention: Coordinate admins.

Error: No privacy window created / No privacy monitor found

Cause: Topmost-window privacy mode failed (missing WindowInjection.dll, broker failure).

Solution: Switch to "Mode 2" (virtual display) on installed hosts.

Prevention: Keep installation files intact.

11.8 Terminal and tunnels

Error: Maximum number of terminal services (100) reached

Cause: Terminal service limit per host.

Solution: Close persistent terminals; idle ones expire after 1–2 h.

Prevention: Avoid leaving many persistent terminals.

Error: Terminal service user mismatch detected.

Cause: A persistent terminal service ID was reused by a different user/token.

Solution: Open a new terminal.

Prevention: Do not share terminal service IDs.

Error: Failed to get user token. / Failed to get current session id.

Cause: The Windows service could not obtain the console user's token.

Solution: Log a user on, or use administrator credentials.

Prevention: Keep a session for terminal-heavy workflows.

Error: Port forward target not authorized

Cause: A multiplexed tunnel channel tried to open a target different from the login target.

Solution: Create a separate mapping per target.

Prevention: One mapping per host:port.

11.9 API and account

Error: Heartbeat failed: ...

Cause: The API server is unreachable or rejects heartbeats (throttled log).

Solution: Check api-server, TLS, and proxy settings.

Prevention: Monitor the API endpoint.

Error: Strict HTTP client requires HTTPS: <url>

Cause: A strict call targeted an http:// URL.

Solution: Use an https:// API server.

Prevention: Terminate TLS on the API server.

Error: No authed oidc is found (repeating)

Cause: OIDC login pending; the client polls for up to 180 s.

Solution: Complete login in the browser.

Prevention: None.

Error: Downloader not found / Failed to get content length

Cause: Update download failures.

Solution: Retry or update manually.

Prevention: Allow the release host.

11.10 Build

Error: Couldn't find VCPKG_ROOT, also can't fallback to homebrew because it's only for macos aarch64.

Cause: VCPKG_ROOT not set.

Solution: Install vcpkg dependencies and export VCPKG_ROOT.

Prevention: Use the CI-pinned vcpkg commit.

Error: cargo build failed, please check rust source code.

Cause: Windows Flutter build: target/release/librustdesk.dll missing.

Solution: Fix the cargo error above it; run flutter clean if needed.

Prevention: Build with the pinned Rust toolchain.

Error: --drm is only supported on the deb packaging path

Cause: --drm on pacman/yum/zypper hosts or non-Linux.

Solution: Build the DRM variant on Debian/Ubuntu (#16220 tracks Flatpak/RPM).

Prevention: Use the deb path for unattended-Wayland.

Error: libdrmtap packaging gate fails (CPU-only stub / helper fallback)

Cause: libdrmtap built without EGL or with the privileged helper.

Solution: Install libegl-dev libgles2-mesa-dev (Arch: mesa libglvnd), delete third_party/libdrmtap/build-pkg, rebuild with -Dhelper=disabled.

Prevention: Build libdrmtap via build.py --drm.

Error: Sciter build crashes with Rust ≥ 1.78

Cause: i128 ABI change breaks Sciter.

Solution: Use Rust 1.75 (CI pin).

Prevention: Pin the toolchain.

Error: Android link fails on getifaddrs

Cause: Bionic exports it only from API 24; jniLibs target API 21.

Solution: Handled by build.rs compiling android_ifaddrs.c; ensure VCPKG_ROOT is set (build.rs panics otherwise).

Prevention: Build via flutter/ndk_*.sh.

Error: Unrecognized feature from build.py

Cause: -f/--feature has no available features in 1.5.0.

Solution: Omit -f.

Prevention: None.

12. Potential Improvements

13. Quick Reference

13.1 Paths

13.2 Commands

rustdesk --version
rustdesk --get-id
sudo rustdesk --password 'S3cure-Pass-2026'
sudo rustdesk --set-id office-pc-01
sudo rustdesk --option custom-rendezvous-server rd.example.com
sudo rustdesk --option key <base64-key>
sudo rustdesk --config "host=rd.example.com,key=<base64-key>"
sudo rustdesk --deploy --token "$API_TOKEN"
sudo rustdesk --assign --token "$API_TOKEN" --user_name alice
rustdesk --install-service
rustdesk --uninstall-service
rustdesk --connect 123456789 --password abc123

1.5.0
123456789
Done!
Done!
(silent)
(silent)
(silent)
Device deployed.
Done!

13.3 Ports

13.4 Most-used option keys