Settings reference

Settings is administrator-only and has seven tabs. Most settings take effect immediately, without a restart.

Settings stored here override the equivalent environment variable. Environment variables set the initial value; the database is the source of truth afterwards.

Client Setup

Read-only. Shows the exact ID Server and Relay Server values to enter in a RustDesk client, ready to copy. Nothing to configure — it exists so you are not retyping values from memory when setting up a machine.

To point a client at CortenDesk, set its API Server to the console URL, plus the ID Server, Relay Server and Key from here. See Devices.

Server

Setting	Default	What it does
ID server	—	Your hbbs address, host:21116. Shown to clients.
Relay server	—	Your hbbr address, host:21117.
Public key	—	Contents of id_ed25519.pub from the RustDesk server. Must match exactly — see the warning below.
Online window	60 seconds	How long after its last heartbeat a device still counts as online. Raise it if devices flicker on unreliable links.
Require device approval	Off	New devices register as pending and stay hidden until an administrator approves them.
Approve when the device's user signs in	Off	With the gate on, a pending device whose client is signed in to this console with a user account is approved on arrival and that user becomes its owner. Since 1.13.0.
Default group for new devices	None	Every first-seen device is placed in this group. See Devices and device groups. Since 1.13.0.
Server access	Open	Approved devices only makes the ID server refuse sessions to and from devices that are not approved. See Server access control. Since 1.10.0.
Identify signed-out devices by IP address	Off	In approved-only mode, lets signed-out clients start sessions when an approved device registered from the same IP. Weak behind shared IPs and some Docker setups. Since 1.10.0.
rdgen URL	—	Link to an rdgen instance for building custom clients. Adds the Build Installers item to the sidebar. Leave blank to hide it.
Client URL scheme	rustdesk	Scheme of the links that open a device in the RustDesk client. A client built with rdgen under another app name registers its own. CORTENDESK_CLIENT_URL_SCHEME sets the default. Since 1.14.0.
Link to client downloads on the sign-in page	On	Shows a "Download the client" link under the sign-in form when builds are published in Client Downloads. Since 1.8.0.

Whitespace in the public key. The key is compared exactly. A trailing newline or space picked up when copying through an editor makes it mismatch, and the symptom is indistinguishable from a genuinely wrong key — clients simply fail to connect. Paste it with no surrounding whitespace.

Security

Setting	Default	What it does
Require 2FA for everyone	Off	Every user must enrol in TOTP before using the console.
Require 2FA for administrators	Off	Same, administrators only.
Emailed sign-in verification	Off	Sends a one-time code when someone signs in from an unrecognised browser. Requires working SMTP.
Trusted device days	30	How long a browser stays remembered after a successful emailed code, before it is challenged again.

Requiring 2FA with no way to enrol will lock people out — read Two-factor authentication first, and note the break-glass command in the command-line reference.

Email

SMTP for invitations, password resets and sign-in codes.

Setting	Notes
Enable SMTP	Master switch. With it off, nothing is sent.
Host / Port	Your relay.
Encryption	TLS, STARTTLS or none, matching your relay.
Username / Password	Blank for an unauthenticated relay.
From address / From name	Must be an address your relay is allowed to send as.
Send test to	Sends a real message and reports the exact error on failure.

Use the test send before relying on any email feature. It surfaces the provider's own error text, which is usually the fastest way to a fix.

Without working SMTP: no invitations, no self-service password reset, no emailed sign-in codes. Administrators are warned in the console when SMTP is unset, because account recovery silently depends on it.

See Email, invitations and password reset.

SSO

OpenID Connect for both the console and RustDesk clients. Full walkthrough in Single sign-on (OIDC) — the fields are:

Setting	Notes
Enable SSO	Master switch.
Discovery URL	Provider's .well-known/openid-configuration.
Public base URL	Override when the browser reaches the provider at a different address than the server does — split-horizon DNS, or a container network.
Client ID / Client secret	From your provider.
Scopes	Defaults are sufficient for most providers.
Button label	Text on the sign-in button.
New user policy	What happens on first sign-in by an unknown user.
Default administrator	Whether provisioned users become administrators. Leave off.
Default group	User group new accounts join.
Allowed email domains	Restrict which domains may sign in.
Require verified email	Off by default deliberately: some providers send email_verified: false as a matter of policy, and turning this on rejects those users.
Provider sign-out	Also sign out of the identity provider on logout.
Disable local login	Turns away password sign-in on the console and in the RustDesk client.

Before you disable local login, know how to get back in. Password sign-in returns automatically only when SSO stops being usable as configured — that is, SSO is switched off, or its discovery URL, client ID or client secret is blank. A provider that is merely unreachable or broken while still fully configured does not restore password sign-in on its own.

For that case the break-glass is an environment variable on the server:

CORTENDESK_OIDC_DISABLED=true

It forces SSO off regardless of the stored settings and brings the password form back. Set it, restart, sign in, fix the provider.

Notifications

Apprise-based fleet and security alerts — endpoint, delivery mode, per-event switches, cooldown and device scoping. Covered in full on Notifications.

Setting	Default	What it does
Cooldown (minutes)	15	Minimum gap between alerts for the same event and subject.
Offline alert grace (minutes)	0	Wait this long after a device goes offline before alerting, up to 1440. See offline alert grace. Since 1.8.1.

Presence alert maintenance, on the same tab, snoozes offline and recovery alerts for a device or group. See maintenance snoozes.

Since 1.11.0 a send that fails with a timeout or a temporary error is retried about 1 and 5 minutes later, and Recent deliveries shows the attempts. See retries. How long scheduled sends wait for Apprise is the CORTENDESK_NOTIFY_TIMEOUT environment variable, not a setting here.

Maintenance

Setting	Default	What it does
Log retention days	365	Age at which audit rows are deleted. 0 keeps everything forever.
Prune now	—	Runs the prune immediately and reports rows deleted.

Retention covers connections, file transfers, logins, alarms and the console audit trail. Automatic pruning needs the scheduler — running inside the Docker image already, but a manual install must add the cron entry.

Environment only

Some settings have no screen and are read from the environment at start, among them CORTENDESK_DOWNLOADS_MAX_MB, CORTENDESK_UPDATE_CHECK and CORTENDESK_NOTIFY_TIMEOUT, and in the Docker image CORTENDESK_HTTP_PORT, CORTENDESK_LOG_LEVEL, CORTENDESK_FPM_MAX_CHILDREN and CORTENDESK_NGINX_WORKER_CONNECTIONS. See Install with Docker.

Related

• Audit logs
• Command-line reference
• Troubleshooting