[feat] add Linux headless mode and interactive console

2026-10-16 17:10:20 +08:00 · 2026-09-25 00:29:24 +08:00
parent c661319890
commit 191ba26772
28 changed files with 2120 additions and 201 deletions
@@ -57,13 +57,13 @@ xmake r crossdesk
 ## Linux

 Linux 构建支持 Ubuntu 20.04 及以上版本的 amd64 和 arm64。发布安装包以
-Ubuntu 20.04/glibc 2.31 为兼容基线。以下依赖命令以 Ubuntu 20.04 为例；其他发行版或较新版本需按其软件源调整包名和工具链，复现 CI 可使用下文的构建镜像。先安装基础编译依赖：
+Ubuntu 20.04/glibc 2.31 为兼容基线。以下依赖命令以 Ubuntu 20.04 为例；其他发行版或较新版本需按其软件源调整包名和工具链，复现 CI 可使用下文的构建镜像。先安装基础编译和无头运行依赖：

 ```bash
 sudo apt-get update
 sudo apt-get install -y \
  git curl unzip build-essential gcc-10 g++-10 python3-pip \
-  pkg-config binutils dpkg-dev \
+  pkg-config binutils dpkg-dev xvfb xfce4 dbus \
  libx11-dev libxext-dev libxrender-dev libxft-dev libxrandr-dev \
  libxinerama-dev libxcursor-dev libxi-dev libxfixes-dev libxv-dev \
  libxtst-dev libxcb-randr0-dev libxcb-xtest0-dev libxcb-xinerama0-dev \
@@ -60,13 +60,13 @@ Linux builds support Ubuntu 20.04 or later on amd64 and arm64. Release packages
 use Ubuntu 20.04/glibc 2.31 as their compatibility baseline. The dependency
 commands below target Ubuntu 20.04; adapt package names and toolchains for
 other distributions or newer versions, or use the build image below to
-reproduce CI. Install the base build dependencies first:
+reproduce CI. Install the base build and headless runtime dependencies first:

 ```bash
 sudo apt-get update
 sudo apt-get install -y \
  git curl unzip build-essential gcc-10 g++-10 python3-pip \
-  pkg-config binutils dpkg-dev \
+  pkg-config binutils dpkg-dev xvfb xfce4 dbus \
  libx11-dev libxext-dev libxrender-dev libxft-dev libxrandr-dev \
  libxinerama-dev libxcursor-dev libxi-dev libxfixes-dev libxv-dev \
  libxtst-dev libxcb-randr0-dev libxcb-xtest0-dev libxcb-xinerama0-dev \
@@ -24,6 +24,10 @@

 Wayland 画面捕获依赖启用了 Wayland 支持的构建、宿主系统 PipeWire 0.3 和桌面门户授权；无法捕获时也可在 X11 会话中对比验证。构建选项见 [Linux 构建说明](BUILD.md#linux)。

+## Linux 电脑未连接显示器或没有图形会话
+
+正常启动 CrossDesk 即可自动发现并选择当前用户的已有 X11 桌面，保留原来的 Dock 和应用，无需知道显示编号；多个会话会根据登录状态和活动状态自动选择。只看到 CrossDesk、背景一片黑，通常是创建了未运行桌面环境的裸 Xvfb；请改为复用原桌面。需要独立虚拟桌面时安装 `xvfb xfce4 dbus`，使用 `--headless-size 1920x1080 --headless-session startxfce4`。部署与限制见 [Linux 无头运行](HEADLESS.md)。
+
 ## Windows 锁屏后无法操作

 在被控电脑检查 CrossDesk Service 是否安装、是否运行，并保持 CrossDesk 客户端运行。便携版可在“设置 → 锁屏控制服务”安装。服务状态检查命令见 [Windows 服务说明](../README.md#windows-service)。
@@ -84,6 +88,7 @@ Windows 安装包和便携包内置了 Amyuni 的 `usbmmidd_v2` 虚拟显示器
 | P2P connection failed | Enable TURN relay in Settings and reconnect. For self-hosting, check Coturn and relay/media firewall ports. Review [release compatibility notes](https://github.com/kunkundi/crossdesk/releases). |
 | Black screen / no input on macOS | Grant Screen Recording and Accessibility, then reopen the app. A changed app path or signature may require fresh permission grants. |
 | No capture on Linux Wayland | Check the Wayland build option, host PipeWire 0.3, and desktop portal permission. Compare with an X11 session. See [Linux build instructions](BUILD_EN.md#linux). |
+| Linux host has no monitor or graphical session | Start CrossDesk normally to automatically discover and select your existing desktop, preserving its Dock and apps; no display number is needed. A bare Xvfb shows only CrossDesk on a black background; use an existing session or install Xfce and specify `--headless-session startxfce4`. See [Linux headless operation](HEADLESS_EN.md). |
 | Cannot control a Windows lock screen | Install/start CrossDesk Service and keep the host client running. See [service commands](../README_EN.md#windows-service). |
 | Windows host has no monitor attached | The Windows installer and portable archive bundle Amyuni's `usbmmidd_v2` virtual display driver (in the `usbmmidd_v2` folder with its License.txt). On each connection to a host without a monitor (capture method Auto), CrossDesk starts streaming in compatibility mode and, in the background, asks the CrossDesk Service session helper to install the Microsoft-signed driver (first time only) and plug one virtual monitor at 1920×1080; capture then switches to DXGI/WGC on that monitor and it is unplugged when the session ends. Without the service only an elevated CrossDesk can plug it itself; otherwise the host stays in **headless compatibility mode**: GDI capture at an OS-fixed resolution (often 1024×768) with reduced frame rate; the host log records why. Input, privacy screen and file transfer still work. A real monitor or an HDMI/DP dummy plug also restores GPU capture. |
 | Removing the bundled virtual display driver | The uninstaller removes the driver when CrossDesk installed it and leaves a driver you installed yourself. For the portable build run `deviceinstaller64 enableidd 0`, `deviceinstaller64 stop usbmmidd` and `deviceinstaller64 remove usbmmidd` as administrator from the `usbmmidd_v2` folder, or uninstall "USB Mobile Monitor Virtual Display" in Device Manager. |
@@ -0,0 +1,155 @@
+# Linux 无头运行
+
+[返回 README](../README.md) · [English](HEADLESS_EN.md)
+
+无显示器的 Linux 主机可复用已有 X11 桌面，也可通过 Xvfb 创建独立虚拟桌面。画面采集、键鼠、光标和剪贴板使用同一个显示会话。
+
+## 保留原来的 Ubuntu 桌面和应用
+
+正常打开 CrossDesk 即可，程序会自动发现并选择当前用户的已有桌面，保留 Dock、任务栏、壁纸和已打开应用。无需知道 `:0`、`:10` 等显示编号，也无需设置 `DISPLAY`：
+
+```bash
+# 安装包
+crossdesk
+# 源码构建
+xmake r crossdesk
+```
+
+多个可用桌面同时存在时也会自动选择：优先启动环境中的桌面，其次是当前登录会话、系统标记的活动主桌面、其他活动桌面和仍在线的桌面。没有系统会话信息或优先级相同时，按稳定的显示顺序选择，避免每次启动切到不同桌面。失效会话与没有窗口管理器的空白 Xvfb 不会作为已有桌面选中。
+
+复用已有桌面不依赖 Xvfb，也不会在退出 CrossDesk 时结束桌面或其他应用。若原会话已锁屏，远程会先看到系统锁屏界面，需要用该用户的系统密码解锁。
+
+自动发现使用系统登录会话信息和当前用户的 X11 套接字，并验证窗口管理器确实可用。没有 systemd/logind 的发行版仍可自动发现并选择桌面。认证使用现有 `XAUTHORITY`（未设置时使用 Xlib 默认认证位置），必要时尝试当前用户的 GDM 认证文件。不会自动选择其他用户的桌面或登录欢迎界面。
+
+`--headless` 可用于显式触发这套自动选择流程，例如忽略终端里失效的 Wayland 环境变量。`--headless-display` 仅供需要覆盖默认选择的高级使用者或调试使用：
+
+```bash
+crossdesk --headless-display :10  # 示例编号，以实际会话为准
+```
+
+此覆盖选项只连接指定的已有桌面；无法连接或没有运行窗口管理器时会报错，不会悄悄创建另一块屏幕。
+
+**不要添加 `--headless-size` 或 `--headless-session` 来连接原桌面**：它们用于创建独立 Xvfb。原桌面的分辨率由原来的显示服务管理。
+
+## 命令行控制台
+
+无头模式下，终端只显示设备 ID、连接密码、在线状态和操作结果，常规日志写入文件。在 SSH / 无图形环境下普通启动会自动进入此模式；也可显式启用：
+
+```bash
+xmake r crossdesk --headless
+```
+
+程序运行后，在同一个终端输入命令并回车：
+
+| 命令 | 作用 |
+| --- | --- |
+| `status` | 显示本机 ID、当前连接密码和在线状态 |
+| `settings` | 打开设置菜单，输入编号或名称修改；`back` 返回 |
+| `settings show` | 仅查看设置 |
+| `settings set 名称 值` | 直接修改一个设置 |
+| `password` | 提示输入新密码；6 位英文字母或数字，输入 `cancel` 取消 |
+| `password Ab12Cd` | 直接提交新密码（示例，请自行选择密码） |
+| `random` | 生成随机密码并提交修改 |
+| `help` | 显示帮助 |
+| `quit` | 关闭 CrossDesk；复用模式下不会关闭原桌面 |
+
+设置菜单与 GUI 共用 `config.ini`，每项修改校验通过后立即保存，无需另执行保存命令。输入 `cancel` 放弃正在编辑的值。控制台状态、菜单、密码提示和帮助跟随语言设置，支持中文、英文和俄文；命令名称保持不变。
+
+| 设置名称 | 可选值 / 格式 | 生效方式 |
+| --- | --- | --- |
+| `language` | `zh-CN` / `en-US` / `ru-RU` | 立即切换控制台和 GUI 语言，下次启动保留 |
+| `codec` | `h264` / `av1` | 保存后重新连接 |
+| `hardware` | `on` / `off` | 保存后重新连接；构建不支持时拒绝开启 |
+| `turn` | `off` / `auto` / `udp` / `tcp` | 保存后重新连接；`udp` / `tcp` 表示强制中继 |
+| `server_host` | 主机名或 IP，不含协议与路径 | 自托管未启用时保存备用，已启用时重连 |
+| `server_port` | `1`–`65535` | 同上 |
+| `self_hosted` | `on` / `off` | 先配置地址、端口，再开启；保存后重连 |
+| `privacy` | `on` / `off` | 后续远程连接的自动隐私屏行为 |
+| `file_path` | 已存在且可写的绝对目录；`default` 恢复默认 | 后续接收的文件；路径可含空格，无需额外引号 |
+| `autostart` | `on` / `off` | 下次图形桌面登录时启动；不等于系统服务开机启动 |
+| `daemon` | `on` / `off` | 普通模式下次启动生效；无头控制台仍保持前台 |
+
+例如，在运行中的控制台输入：
+
+```text
+settings
+1
+en-US
+back
+settings set codec av1
+settings set file_path /home/user/Received Files
+```
+
+存在远程会话（含正在连接的会话）或尚未完成的密码修改时，连接相关设置会被拒绝，避免中断会话。修改服务器地址和端口前，应先结束远程会话。切换自托管可能切换到该服务器对应的 ID 和密码，以重新连接后的 `status` 为准。画质和帧率由控制端管理，Linux 无头模式采用 X11 采集，这些不提供额外的全局修改入口。
+
+修改密码需要连接到信令服务器。控制台会显示提交、确认和重新连接的结果；仅在服务器确认后采用新密码，并沿用 GUI 的凭据持久化与超时恢复流程。离线、密码格式错误或修改尚未完成时，会给出明确提示。密码修改会触发重新连接。
+
+日志路径会在启动时显示，继续使用原有的 `crossdesk-YYYYMMDD-HHMMSS.log` 和 `minirtc-YYYYMMDD-HHMMSS.log`，文件命名和原有轮转规则不变，不额外创建无头模式日志文件。无头启动诊断写入 CrossDesk 日志；终端日志副本和第三方组件直接写向标准输出/标准错误的内容被静默处理。ID/密码状态输出直接送往终端，不经过日志系统。非交互运行（例如 systemd、重定向输出）默认不显示明文密码；标准输入关闭不会终止后台服务。
+
+交互控制台在前台运行，内置 daemon 设置在此模式下不会将进程分离。当前已有旧版本进程时，需要退出旧实例后启动新版本才能使用控制台。
+
+## 创建独立虚拟桌面
+
+Debian/Ubuntu 安装包将 Xvfb、Xfce 和 D-Bus 会话工具声明为强依赖，使用 APT 安装时会自动补齐，即使指定 `--no-install-recommends` 也不会跳过。源码直接运行时，需在开发环境中准备同样的运行依赖；项目构建镜像和 CI 已包含这些组件。
+
+原来没有图形会话，或者希望单独开一套桌面时，可启动独立 Xfce 会话。Ubuntu / Debian 示例（安装包用户无需重复安装依赖）：
+
+```bash
+sudo apt install xvfb xfce4 dbus
+crossdesk --headless-size 1920x1080 --headless-session startxfce4
+```
+
+默认分辨率为 1920×1080，宽高必须是 320–8192 范围内的偶数。`--headless-session` 接收一个可执行程序名称或路径，通过独立的 `dbus-run-session` 启动。需要参数时，创建可执行脚本，在脚本中用 `exec` 启动桌面或窗口管理器。
+
+仅做画面采集调试时，可以明确启动裸 Xvfb：
+
+```bash
+sudo apt install xvfb
+crossdesk --headless-session none
+```
+
+裸 Xvfb 只提供屏幕，**不会生成 Dock、任务栏或原来的应用窗口**。只使用 `--headless-size` 而未指定桌面会话也属于这一情况，启动诊断日志会记录提示。此前“只看到 CrossDesk，其余一片黑”就是因为进入了这种独立裸显示。
+
+## 自动选择与限制
+
+- 普通图形启动继续使用现有 `DISPLAY` 或 Wayland 会话。X11 没有活动 RandR 输出或没有 RandR 扩展时，采集可用的根窗口。
+- `--headless`，或没有可连接的 `DISPLAY` 且未设置 Wayland 环境时，会先自动选择已有 X11 桌面，再回退到独立 Xvfb；没有桌面环境时，回退的裸 Xvfb 会明确提示其不包含 Dock 和原应用。
+- `--headless-display` 与 `--headless-size` / `--headless-session` 不能混用。
+- `--no-headless` 禁用自动发现和回退；`--headless-help` 查看命令说明。
+- 不会在显示会话之间迁移应用，也不会把运行中的会话自动切换到另一块屏幕。物理会话已经失效时，另建 Xvfb 无法恢复其应用。
+
+## 后台运行
+
+创建独立 Xvfb 时，在前台保留一个管理进程，监控 Xvfb、桌面会话和 CrossDesk。退出程序、发送 SIGINT / SIGTERM / SIGHUP，或任一受监控进程退出时，会清理该次会话的子进程与临时认证文件。显示编号由 Xvfb 自动分配，避免占用已有显示；TCP 监听关闭，X11 连接使用随机认证 cookie，认证文件仅当前用户可读。
+
+启动诊断日志会记录 `DISPLAY` 和 `XAUTHORITY` 路径；在同一用户的终端设置这两个变量后，可以将其他应用启动到虚拟桌面。认证文件会随会话退出被删除。
+
+需要开机后保持服务，可创建用户级 systemd 单元 `~/.config/systemd/user/crossdesk-headless.service`，并将 `ExecStart` 改为实际程序路径：
+
+```ini
+[Unit]
+Description=CrossDesk virtual desktop
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/crossdesk --headless-size 1920x1080 --headless-session startxfce4
+Restart=on-failure
+RestartSec=5
+KillMode=mixed
+TimeoutStopSec=15
+
+[Install]
+WantedBy=default.target
+```
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now crossdesk-headless.service
+journalctl --user -u crossdesk-headless.service -f
+```
+
+需要复用原桌面的服务应将 `ExecStart` 改为 `/usr/bin/crossdesk`（自动发现和选择；确保已有图形会话登录）。如需在用户未登录时运行用户服务，管理员需为该用户启用 linger：`sudo loginctl enable-linger 用户名`。独立 Xvfb 模式下内置 daemon 选项不会生效；systemd 负责重启整个虚拟桌面。停止该模式会结束虚拟桌面中的应用，请先保存工作。
+
+## 运行限制
+
+虚拟显示的 GUI 使用软件渲染，画面走 X11 → NV12 采集。视频编码仍遵循 CrossDesk 设置和本机编码器能力。声音依赖当前用户可用的音频服务；Xvfb 本身不提供虚拟声卡。此实现针对 Linux；Windows 无显示器支持见 [常见问题](FAQ.md)。
@@ -0,0 +1,152 @@
+# Linux headless operation
+
+[README](../README_EN.md) · [中文](HEADLESS.md)
+
+CrossDesk can reuse an existing X11 desktop or create a separate Xvfb desktop on a Linux host without a monitor. Capture, input, cursor and clipboard use the same display.
+
+## Preserve the existing desktop and applications
+
+Start CrossDesk normally. It automatically discovers and selects your existing desktop, preserving its Dock, panel, wallpaper and open applications. No display number or `DISPLAY` configuration is required:
+
+```bash
+crossdesk
+# Source build:
+xmake r crossdesk
+```
+
+With multiple desktops, selection prefers the startup environment's desktop, then the current login session, the active primary desktop, other active desktops, and online desktops. Equal-priority desktops use a stable display order, also used when systemd/logind metadata is unavailable. Inaccessible sessions and bare Xvfb displays without a window manager are excluded from existing-desktop selection.
+
+Reusing a desktop does not require Xvfb. Exiting CrossDesk does not terminate that desktop or its applications. A locked session initially shows the system lock screen; unlock it with that user's system password.
+
+Discovery combines the current user's login-session metadata with their X11 sockets and verifies a live window manager. It works without systemd/logind as well. It respects `XAUTHORITY` or Xlib's default location when unset, and can try the user's GDM authority file. Other users' desktops and login greeters are not automatically selected.
+
+`--headless` explicitly requests automatic selection, for example when the shell has stale Wayland environment variables. The display override is retained only for advanced use and debugging:
+
+```bash
+crossdesk --headless-display :10  # Example display, not needed for normal startup.
+```
+
+The override fails if the specified desktop is inaccessible or has no window manager; it never substitutes a blank Xvfb.
+
+Do not add `--headless-size` or `--headless-session` to reuse an existing desktop: those options create a separate Xvfb. The existing display server controls its resolution.
+
+## Terminal console
+
+Headless mode keeps routine logs in files and displays the device ID, connection password, online status and command results in the terminal. SSH launches without a graphical environment enable this automatically; to request it explicitly:
+
+```bash
+xmake r crossdesk --headless
+```
+
+Enter commands in that terminal while CrossDesk is running:
+
+| Command | Action |
+| --- | --- |
+| `status` | Show the device ID, current password and connection state |
+| `settings` | Open the numbered settings menu; `back` returns |
+| `settings show` | Show settings without entering the menu |
+| `settings set KEY VALUE` | Change a setting directly |
+| `password` | Prompt for a new password; six ASCII letters or digits, or `cancel` |
+| `password Ab12Cd` | Submit a password directly (example only) |
+| `random` | Generate and submit a random password |
+| `help` | Print command help |
+| `quit` | Exit CrossDesk, preserving a reused desktop |
+
+The menu shares the GUI's `config.ini`. Each valid change is saved immediately; `cancel` discards the value being edited. Console status, menus, password messages and help follow the saved Chinese, English or Russian language setting. Command names remain the same.
+
+| Key | Values / format | When applied |
+| --- | --- | --- |
+| `language` | `zh-CN` / `en-US` / `ru-RU` | Immediately, including the GUI; retained on restart |
+| `codec` | `h264` / `av1` | Reconnect after saving |
+| `hardware` | `on` / `off` | Reconnect; enabling requires a build with hardware codec support |
+| `turn` | `off` / `auto` / `udp` / `tcp` | Reconnect; UDP/TCP force relay use |
+| `server_host` | Hostname or IP without URL scheme/path | Reconnect if self-hosting is enabled; otherwise saved for later |
+| `server_port` | `1`–`65535` | Same as server host |
+| `self_hosted` | `on` / `off` | Configure host/port first, then enable; reconnect |
+| `privacy` | `on` / `off` | Automatic privacy screen on subsequent connections |
+| `file_path` | Existing writable absolute directory, or `default` | Subsequent received files; spaces need no extra quotes |
+| `autostart` | `on` / `off` | Next graphical desktop login, not a system boot service |
+| `daemon` | `on` / `off` | Next normal-mode start; the headless console remains in the foreground |
+
+Example commands inside the running console:
+
+```text
+settings
+1
+en-US
+back
+settings set codec av1
+settings set file_path /home/user/Received Files
+```
+
+Connection settings cannot change while a remote session is connected/connecting or a password change is unresolved. Switching signaling servers may change the device identity; use `status` after reconnection. Quality/frame rate are controlled by the viewer, and headless Linux capture uses X11; those options are not additional mutable global settings.
+
+Password changes require a signaling connection. The console reports submission, server confirmation and reconnection, using the GUI's existing persistence and timeout recovery flow. Invalid input, offline changes and pending requests produce concise messages. A password change reconnects the host.
+
+Startup prints the existing log location. Logs retain their original `crossdesk-YYYYMMDD-HHMMSS.log` and `minirtc-YYYYMMDD-HHMMSS.log` names and rotation policy, with no extra headless log file. Bootstrap diagnostics use the CrossDesk logger; terminal log copies and direct third-party stdout/stderr output are silenced. Credential display goes directly to the terminal, not through the logger. Noninteractive output (services or redirection) hides the plaintext password. End-of-input does not terminate a background service.
+
+The interactive console stays in the foreground regardless of the built-in daemon setting. Exit any older instance and start the new build to use these commands.
+
+## Create a separate virtual desktop
+
+Debian/Ubuntu packages require Xvfb, Xfce and the D-Bus session tools through `Depends`. APT installs them even with `--no-install-recommends`. Source builds need the same runtime prerequisites in the development environment; the project build image and CI include them.
+
+For a host without a desktop session, or to start an independent Xfce session (package users do not need to reinstall the dependencies):
+
+```bash
+sudo apt install xvfb xfce4 dbus
+crossdesk --headless-size 1920x1080 --headless-session startxfce4
+```
+
+The default size is 1920×1080; dimensions must be even, between 320 and 8192. `--headless-session` accepts an executable name or path and runs it under a private `dbus-run-session`. Use an executable script ending in `exec` if arguments are required.
+
+For capture debugging, explicitly request a bare display:
+
+```bash
+sudo apt install xvfb
+crossdesk --headless-session none
+```
+
+Bare Xvfb only provides a screen. It has no Dock, panel or existing application windows. Specifying only `--headless-size` also creates a bare display and records a diagnostic in the log. This explains a screen that shows CrossDesk against a black background.
+
+## Selection and limits
+
+- Ordinary graphical launches retain the supplied X11 or Wayland session. X11 root capture works without active RandR outputs or a RandR extension.
+- `--headless`, or startup without an accessible X11 display or advertised Wayland session, automatically selects an existing desktop before falling back to Xvfb. Bare Xvfb fallback explicitly reports that it has no desktop environment or existing apps.
+- `--headless-display` cannot be combined with `--headless-size` or `--headless-session`.
+- `--no-headless` disables automatic discovery/fallback; `--headless-help` prints usage.
+- Applications are not migrated between sessions. Creating Xvfb cannot recover applications from an unavailable graphical session.
+
+## Run as a service
+
+When creating a private display, the foreground supervisor owns Xvfb, the optional desktop session and CrossDesk. Application exit, SIGINT/SIGTERM/SIGHUP, or a monitored process exiting tears down that session's child processes and temporary authorization file. Xvfb allocates an unused display number, disables TCP listening and requires a random authentication cookie. The authority file is private to the current user. Startup diagnostic logs record `DISPLAY` and `XAUTHORITY`; use them from a terminal as the same user to launch additional applications on the virtual desktop.
+
+Example `~/.config/systemd/user/crossdesk-headless.service` (adjust the executable path):
+
+```ini
+[Unit]
+Description=CrossDesk virtual desktop
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/crossdesk --headless-size 1920x1080 --headless-session startxfce4
+Restart=on-failure
+RestartSec=5
+KillMode=mixed
+TimeoutStopSec=15
+
+[Install]
+WantedBy=default.target
+```
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now crossdesk-headless.service
+journalctl --user -u crossdesk-headless.service -f
+```
+
+To reuse an existing desktop instead, set `ExecStart=/usr/bin/crossdesk`; discovery and selection are automatic, but a graphical session must already be logged in. An administrator can enable a user service before login with `sudo loginctl enable-linger USERNAME`. The built-in daemon setting is bypassed when creating a private Xvfb; systemd can restart the whole session. Save work before stopping the service, which also closes applications on the virtual desktop.
+
+## Runtime limitations
+
+The GUI uses software rendering and capture uses X11 → NV12. Video encoding follows the configured codec and available encoders. Audio requires an available user audio service; Xvfb does not provide a sound device. This implementation targets Linux. For Windows hosts without monitors, see the [FAQ](FAQ.md).