rustdesk-server Documentation

Technical Documentation: rustdesk/rustdesk-server

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

RustDesk Server Program

Download

Manual

Configuration & environment variables

FAQ

How to migrate OSS to Pro

Self-host your own RustDesk server, it is free and open source.

[!IMPORTANT]
Need more features? RustDesk Server Pro might suit you better.

Want to develop your own server? Start with rustdesk-server-demo, a simpler starting point than this repository.

How to build manually Copy Chapter

cargo build --release

Three executables will be generated in target/release.

• hbbs - RustDesk ID/Rendezvous server
• hbbr - RustDesk relay server
• rustdesk-utils - RustDesk CLI utilities

You can find updated binaries on the Releases page.

Configuration Copy Chapter

hbbs and hbbr can be configured with command-line flags, environment
variables, or an .env / config file. Run hbbs --help or hbbr --help to see
the available flags.

The most common options:

See docs/environment-variables.md for the
full list of variables, the file/flag/env precedence rules, database and relay
bandwidth tuning, Docker image variables, and examples.

Installation Copy Chapter

Please follow this doc

Environment Variables (`docs/environment-variables.md`) Copy Section

Configuration & Environment Variables

This document is the single reference for every option that the open‑source
RustDesk server binaries (hbbs, hbbr) understand: command‑line flags,
environment variables, and configuration files.

TL;DR — For most people the command‑line flags shown by hbbs --help /
hbbr --help are all you need. Environment variables are an alternative way to
set the same options, plus a handful of extra tuning knobs that have no flag.

How configuration is loaded Copy Chapter

Both servers read their configuration from the following sources. For
hbbs the order of precedence, from highest to lowest, is:

1. Command‑line flag (e.g. -p 21116, -k mykey)
2. --config <file> — an INI file passed with -c/--config
3. .env — an INI file named .env in the working directory
4. Inherited process environment — variables exported before launch

A value set by a higher source overrides the same value from a lower one. Under
the hood every source is turned into a process environment variable, and the
code then reads that variable — so "flag", "config file" and "env var" are just
three ways to set the same thing.

For hbbr the precedence is: flag (-b, -p, -k) → .env →
inherited environment.

RUST_LOG is an exception to these rules. Both binaries initialize logging
before loading .env (or hbbs's --config file), so RUST_LOG must be set
in the inherited process environment.

`hbbs` — ID / rendezvous server Copy Chapter

🅴 = set through the inherited process environment.

PORT_FOR_API / KEY_FOR_API are only used by RustDesk Server Pro and its
API; they have no effect in the open‑source server.

`hbbr` — relay server Copy Chapter

Relay bandwidth / QoS Copy Section

These have no CLI flag and can also be changed through the hbbr
loopback console (tb, sb, ls, dt, t, …; send h
for help).

Downgrade is decided independently for each connection; it does not check
aggregate relay congestion. After DOWNGRADE_START_CHECK, a connection is
capped to LIMIT_SPEED once its average throughput since it started exceeds
SINGLE_BANDWIDTH * DOWNGRADE_THRESHOLD. A lone transfer can therefore be
downgraded even when the relay is otherwise idle. TOTAL_BANDWIDTH is a
separate aggregate cap.

These may also be placed in .env using the uppercase spellings shown above
(e.g. SINGLE_BANDWIDTH=256).

Blocklists / blacklists (files, not env vars) Copy Section

hbbr reads two optional files from its working directory at start‑up:

• blacklist.txt — IPs that are bandwidth‑limited (one IP per line;
  anything after the first space on a line is ignored).
• blocklist.txt — IPs that are refused outright.

Both can also be edited live through the hbbr loopback console (ba/br,
Ba/Br).

Runtime console Copy Section

The runtime consoles are TCP command transports built into the services; they
are not rustdesk-utils commands or interactive standard-input consoles. A
connection from a loopback address is treated as a single console command:

# hbbs: toggle forced relay on PORT-1 (21115 by default)
printf 'always-use-relay Y' | nc 127.0.0.1 21115

# hbbr: list commands on its relay PORT (21117 by default)
printf 'h' | nc 127.0.0.1 21117

Use the corresponding configured ports if you changed PORT.

Database Copy Chapter

At runtime the database location comes from DB_URL (default
./db_v2.sqlite3). If unset, hbbs creates the SQLite file in its working
directory.

Do not confuse DB_URL with DATABASE_URL. The DATABASE_URL entry in
the repository's .env is used only at compile time by sqlx to check SQL
queries; it is not read by the running server. Setting DATABASE_URL on a
running server has no effect — use DB_URL.

Logging Copy Chapter

Both binaries use flexi_logger, which honours the standard RUST_LOG
environment variable (default level info). Set it in the process environment
before launching the binary. A value in .env or hbbs's --config file is
loaded too late and has no effect on logging.

RUST_LOG=debug hbbs

Keys and encryption Copy Chapter

The KEY / -k value can be:

• a public key string — clients must present the matching key;
• a base64‑encoded 64‑byte secret key — the server derives the public key
  from it;
• - or _ — the server loads a key pair from the working directory or
  generates one on first start, writing id_ed25519 (private) and
  id_ed25519.pub (public);
• empty — key validation is disabled. hbbs still loads or generates key
  files for signing but deliberately leaves its active validation key empty;
  hbbr neither loads nor generates a key. Both services then accept clients
  without validating a key. This is the intentional hbbr default; use a
  non-empty value when relay key validation is required.

hbbs defaults to -, so it already loads or generates a key pair without an
explicit -k _. hbbr intentionally defaults to an empty key to avoid
key-pair setup and mismatch failures. Leave it empty for the default mode
without key validation. To enable relay key validation, give it the same
non-empty key as hbbs; both services can reuse key material from a shared
working directory. The _ value is not a stricter mode than - in the current
implementation.

To supply your own key pair, place id_ed25519 and id_ed25519.pub in the
process's current working directory before first start. That directory may
differ from the directory containing the executable. For the supervisor Docker
image, the working directory is /data.

Docker image variables Copy Chapter

The supervisor image (rustdesk/rustdesk-server-s6) starts both binaries with
s6 and adds a few convenience variables handled by its service scripts, not
by hbbs/hbbr directly:

Any variable from the tables above can also be passed straight through the
container's environment (e.g. -e ALWAYS_USE_RELAY=Y, -e RUST_LOG=debug).

The classic scratch image (rustdesk/rustdesk-server) contains only the
binaries and does not implement RELAY, ENCRYPTED_ONLY, KEY_PUB, or
KEY_PRIV; those variables are ignored by that image.

Examples Copy Chapter

Command line — non-standard ports Copy Section

# Tell clients where the relay listens because it is not using port 21117.
hbbs -p 22116 -r rustdesk.example.com:22117
hbbr -p 22117

`.env` file (working directory) Copy Section

# Non-standard ports shared by both binaries; hbbr listens on PORT+1.
relay-servers=rustdesk.example.com:22117
PORT=22116

docker-compose Copy Section

services:
  rustdesk-server:
    image: rustdesk/rustdesk-server-s6:latest
    environment:
      - RELAY=rustdesk.example.com:21117
      - ALWAYS_USE_RELAY=Y
      - RUST_LOG=info
      - SINGLE_BANDWIDTH=256
    ports:
      - "21115:21115"
      - "21116:21116"
      - "21116:21116/udp"
      - "21117:21117"
      - "21118:21118"
      - "21119:21119"
    volumes: ["./data:/data"]
    restart: unless-stopped

systemd Copy Section

[Service]
Environment=ALWAYS_USE_RELAY=Y
Environment=RUST_LOG=info
ExecStart=/usr/bin/hbbs

Port reference Copy Chapter

Ports 21118/21119 are only needed for the web client; you can omit them
otherwise.

--- METRICS ---

• Files Extracted: 2
• Estimated Token Budget: ~3660 tokens
• Canonical Reference: https://codewiki.google/github.com/rustdesk/rustdesk-server