RustDesk Headless Setup

One-click setup for headless (no monitor) Linux machines to work with RustDesk remote desktop.

Solves two common problems:

1. No virtual display — RustDesk can't connect when the monitor is unplugged
2. Password every time — Sets a permanent password so you don't need to approve each connection

---

一鍵設定無螢幕 Linux 主機，讓 RustDesk 遠端桌面正常運作。

解決兩個常見問題：

1. 沒有虛擬顯示 — 拔掉螢幕後 RustDesk 無法連線
2. 每次都要輸入密碼 — 設定永久密碼，免去每次手動核准

---

Supported Platforms | 支援平台

• Ubuntu 20.04+ (and Ubuntu-based: Pop!_OS, Linux Mint, etc.)
• Raspberry Pi OS (Bookworm+)
• Debian

One-Liner Install | 一鍵安裝

curl -fsSL https://raw.githubusercontent.com/h63016401/rustdesk-headless-setup/main/setup_headless_display.sh | sudo bash -s -- --password YOUR_PASSWORD

Manual Install | 手動安裝

git clone https://github.com/h63016401/rustdesk-headless-setup.git
cd rustdesk-headless-setup
sudo ./setup_headless_display.sh --password YOUR_PASSWORD

Usage | 使用方式

sudo ./setup_headless_display.sh [options]

Options:
  --password <pwd>    Set RustDesk permanent password / 設定 RustDesk 永久密碼
  --skip-rustdesk     Skip RustDesk configuration / 跳過 RustDesk 設定
  --x11               Force X11 display server (RPi only) / 強制使用 X11（僅 RPi）
  --wayland           Force Wayland display server (RPi only) / 強制使用 Wayland（僅 RPi）
  --hdmi <1|2>        HDMI port to target (RPi only, default: 1) / HDMI 埠（僅 RPi，預設：1）
  --width <pixels>    Width, default: 1920 / 寬度，預設：1920
  --height <pixels>   Height, default: 1080 / 高度，預設：1080
  --refresh <hz>      Refresh rate, default: 60 / 更新率，預設：60
  --help              Show this help / 顯示說明

Examples | 範例

# Ubuntu - basic setup with RustDesk password
# Ubuntu - 基本設定並設定 RustDesk 密碼
sudo ./setup_headless_display.sh --password mypassword

# Raspberry Pi - X11 mode
# 樹莓派 - X11 模式
sudo ./setup_headless_display.sh --x11 --password mypassword

# Raspberry Pi - custom resolution on HDMI port 2
# 樹莓派 - 自訂解析度，使用 HDMI 埠 2
sudo ./setup_headless_display.sh --hdmi 2 --width 1280 --height 720 --password mypassword

# Only set up virtual display, skip RustDesk
# 只設定虛擬顯示，跳過 RustDesk
sudo ./setup_headless_display.sh --skip-rustdesk

What It Does | 腳本做了什麼

Ubuntu

• Installs xserver-xorg-video-dummy package | 安裝 xserver-xorg-video-dummy 套件
• Creates X11 config at /etc/X11/xorg.conf.d/10-headless.conf with a virtual monitor | 建立虛擬螢幕的 X11 設定檔
• Disables Wayland in GDM (dummy driver requires X11) | 關閉 GDM 的 Wayland（dummy 驅動需要 X11）

Raspberry Pi | 樹莓派

• Adds video=HDMI-A-x:WxH@R and vc4.force_hotplug=1 to kernel cmdline | 在核心啟動參數加入虛擬顯示設定
• Optionally switches between X11 and Wayland via raspi-config | 可選擇切換 X11 或 Wayland
• Installs an xrandr helper script for X11 mode | 安裝 xrandr 輔助腳本（X11 模式）

RustDesk (Both Platforms | 兩平台通用)

• Auto-installs RustDesk if not present (latest version from GitHub) | 若未安裝會自動安裝最新版 RustDesk
• Sets permanent password for unattended access | 設定永久密碼，免核准遠端連線
• Enables and starts the RustDesk service | 啟用並啟動 RustDesk 服務

After Installation | 安裝後

1. Reboot | 重新開機: sudo reboot
2. Connect from another machine using your RustDesk ID and the password you set | 從另一台電腦用 RustDesk ID 和設定的密碼連線

License

MIT