Initial commit: hello-agent — headless RustDesk-protocol-compatible Windows agent

A single-binary, Flutter-free remote-support agent that speaks the stock
RustDesk wire protocol. Designed for one-line MDM deployment against a
self-hosted rustdesk-server: a supporter using the unmodified rustdesk.exe
client connects, the controlled-side user gets a native Win32 approval
prompt, click Yes / No.

CLI surface

    hello-agent.exe --install                # register + start service
    hello-agent.exe --uninstall              # stop, delete, clean up
    hello-agent.exe --config <BLOB>          # admin-UI deploy string
    hello-agent.exe --install --config <BLOB>   # MDM one-liner

--config accepts both forms emitted by the rustdesk-server admin UI: the
reversed-base64 deploy string and the host=,key=,api=,relay= filename
form. Decoded via the upstream custom_server module, persisted via
hbb_common::config::Config::set_option.

Architecture

    --service runs as a Session 0 LocalSystem service. It polls
    WTSGetActiveConsoleSessionId and (re)spawns hello-agent.exe --server
    into the active console session via librustdesk::platform::run_as_user,
    handling the Session 0 → user-session token impersonation.

    --server is the worker. It boots three concurrent components:
      1. cm_popup: an IPC listener on the rustdesk `_cm` named pipe
      2. librustdesk::start_server(true, false): the upstream protocol
         stack — rendezvous mediator, NAT punch, IPC server, screen
         capture, login validation, hbbs_http heartbeat / sysinfo sync
      3. (implicit) ApproveMode::Click is pinned in config, so every
         incoming connection routes through cm_popup

The popup mechanism reuses an existing upstream contract without any
patches to the protocol code: when a peer connects with no password,
Connection::start in the upstream code calls try_start_cm_ipc, which
ipc::connect-s the `_cm` pipe before falling back to spawning a Flutter
CM child. Since cm_popup is up first, step 1 succeeds; we read the
Data::Login{authorized:false} frame, show MessageBoxTimeoutW (Yes/No,
60s, top-most, system-modal), and reply Data::Authorize or Data::Close.

Source tree

    src/main.rs             CLI dispatcher + run_server() composition
    src/cli.rs              hand-rolled argv parser + unit tests
    src/service.rs          windows-service install/uninstall/dispatcher
    src/config_import.rs    --config blob decoding + persistence
    src/cm_popup.rs         _cm IPC listener + Win32 approval dialog

Vendoring

The upstream RustDesk crate is vendored under vendor/rustdesk/ — full
workspace including libs/{hbb_common, scrap, enigo, clipboard,
virtual_display, remote_printer}. This makes the build self-contained
(no submodules, no sibling-repo checkout in CI) and gives us freedom to
fork in a different direction later. Excluded from the vendor: .git,
target/, flutter/, appimage/, flatpak/, fastlane/, docs/, examples/,
ci/, build.py, Dockerfile, upstream README/CLAUDE/AGENTS/GEMINI.

One local divergence vs. upstream: vendor/rustdesk/src/lib.rs flips
`mod custom_server` → `pub mod custom_server` so config_import.rs can
call get_custom_server_from_string without going through the
ui_interface shim. Documented in README.md → "Re-syncing the vendored
copy".

CI

.gitea/workflows/build-windows.yml builds on a self-hosted Windows
runner with Rust 1.75, LLVM 15.0.6 (libclang for bindgen via libvpx-sys),
and a vcpkg cache. The vendored vcpkg.json drives x64-windows-static
deps. The workflow stages the resulting hello-agent.exe into
SignOutput\, reports authenticode signing status (warns on unsigned),
and uploads as artifact. ~15 min full build, faster on incremental.

Out of scope for this commit: Linux/macOS builds, code signing, MSI
packaging, coexistence with stock rustdesk on the same box (currently
shares the RustDesk APP_NAME and config dir).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

vendor/rustdesk/src/hbbs_http/sync.rs

@@ -0,0 +1,325 @@
+use std::{
+    collections::HashMap,
+    sync::{Arc, Mutex},
+    time::Duration,
+};
+
+#[cfg(not(any(target_os = "ios")))]
+use crate::{ui_interface::get_builtin_option, Connection};
+use hbb_common::{
+    config::{self, keys, Config, LocalConfig},
+    log,
+    tokio::{self, sync::broadcast, time::Instant},
+};
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+
+// hello-agent local patch: lowered from 15s to 5s so device-online status in
+// the admin UI reacts faster. Re-apply on vendor resync.
+const TIME_HEARTBEAT: Duration = Duration::from_secs(1);
+const UPLOAD_SYSINFO_TIMEOUT: Duration = Duration::from_secs(120);
+const TIME_CONN: Duration = Duration::from_secs(3);
+
+#[cfg(not(any(target_os = "ios")))]
+lazy_static::lazy_static! {
+    static ref SENDER : Mutex<broadcast::Sender<Vec<i32>>> = Mutex::new(start_hbbs_sync());
+    static ref PRO: Arc<Mutex<bool>> = Default::default();
+}
+
+#[cfg(not(any(target_os = "ios")))]
+pub fn start() {
+    let _sender = SENDER.lock().unwrap();
+}
+
+#[cfg(not(target_os = "ios"))]
+pub fn signal_receiver() -> broadcast::Receiver<Vec<i32>> {
+    SENDER.lock().unwrap().subscribe()
+}
+
+#[cfg(not(any(target_os = "ios")))]
+fn start_hbbs_sync() -> broadcast::Sender<Vec<i32>> {
+    let (tx, _rx) = broadcast::channel::<Vec<i32>>(16);
+    std::thread::spawn(move || start_hbbs_sync_async());
+    return tx;
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct StrategyOptions {
+    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
+    pub config_options: HashMap<String, String>,
+    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
+    pub extra: HashMap<String, String>,
+}
+
+struct InfoUploaded {
+    uploaded: bool,
+    url: String,
+    last_uploaded: Option<Instant>,
+    id: String,
+    username: Option<String>,
+}
+
+impl Default for InfoUploaded {
+    fn default() -> Self {
+        Self {
+            uploaded: false,
+            url: "".to_owned(),
+            last_uploaded: None,
+            id: "".to_owned(),
+            username: None,
+        }
+    }
+}
+
+impl InfoUploaded {
+    fn uploaded(url: String, id: String, username: String) -> Self {
+        Self {
+            uploaded: true,
+            url,
+            last_uploaded: None,
+            id,
+            username: Some(username),
+        }
+    }
+}
+
+#[cfg(not(any(target_os = "ios")))]
+#[tokio::main(flavor = "current_thread")]
+async fn start_hbbs_sync_async() {
+    let mut interval = crate::rustdesk_interval(tokio::time::interval_at(
+        Instant::now() + TIME_CONN,
+        TIME_CONN,
+    ));
+    let mut last_sent: Option<Instant> = None;
+    let mut info_uploaded = InfoUploaded::default();
+    let mut sysinfo_ver = "".to_owned();
+    loop {
+        tokio::select! {
+            _ = interval.tick() => {
+                let url = heartbeat_url();
+                let id = Config::get_id();
+                if url.is_empty() {
+                    *PRO.lock().unwrap() = false;
+                    continue;
+                }
+                if config::option2bool("stop-service", &Config::get_option("stop-service")) {
+                    continue;
+                }
+                let conns = Connection::alive_conns();
+                if info_uploaded.uploaded && (url != info_uploaded.url || id != info_uploaded.id) {
+                    info_uploaded.uploaded = false;
+                    *PRO.lock().unwrap() = false;
+                }
+                // For Windows:
+                // We can't skip uploading sysinfo when the username is empty, because the username may
+                // always be empty before login. We also need to upload the other sysinfo info.
+                //
+                // https://github.com/rustdesk/rustdesk/discussions/8031
+                // We still need to check the username after uploading sysinfo, because
+                // 1. The username may be empty when logining in, and it can be fetched after a while.
+                //    In this case, we need to upload sysinfo again.
+                // 2. The username may be changed after uploading sysinfo, and we need to upload sysinfo again.
+                //
+                // The Windows session will switch to the last user session before the restart,
+                // so it may be able to get the username before login.
+                // But strangely, sometimes we can get the username before login,
+                // we may not be able to get the username before login after the next restart.
+                let mut v = crate::get_sysinfo();
+                let sys_username = v["username"].as_str().unwrap_or_default().to_string();
+                // Though the username comparison is only necessary on Windows,
+                // we still keep the comparison on other platforms for consistency.
+                let need_upload = (!info_uploaded.uploaded || info_uploaded.username.as_ref() != Some(&sys_username)) &&
+                    info_uploaded.last_uploaded.map(|x| x.elapsed() >= UPLOAD_SYSINFO_TIMEOUT).unwrap_or(true);
+                if need_upload {
+                    v["version"] = json!(crate::VERSION);
+                    v["id"] = json!(id);
+                    v["uuid"] = json!(crate::encode64(hbb_common::get_uuid()));
+                    // Optional rebrand identity: `AGENT_NAME` / `AGENT_VERSION`
+                    // are empty by default (vanilla rustdesk) and populated by
+                    // OEM shells like hello-agent. We only stamp the field
+                    // when set so older servers parsing the payload don't see
+                    // empty strings they have to special-case.
+                    let agent_name = config::AGENT_NAME.read().unwrap().clone();
+                    if !agent_name.is_empty() {
+                        v["agent_name"] = json!(agent_name);
+                    }
+                    let agent_version = config::AGENT_VERSION.read().unwrap().clone();
+                    if !agent_version.is_empty() {
+                        v["agent_version"] = json!(agent_version);
+                    }
+                    let ab_name = Config::get_option(keys::OPTION_PRESET_ADDRESS_BOOK_NAME);
+                    if !ab_name.is_empty() {
+                        v[keys::OPTION_PRESET_ADDRESS_BOOK_NAME] = json!(ab_name);
+                    }
+                    let ab_tag = Config::get_option(keys::OPTION_PRESET_ADDRESS_BOOK_TAG);
+                    if !ab_tag.is_empty() {
+                        v[keys::OPTION_PRESET_ADDRESS_BOOK_TAG] = json!(ab_tag);
+                    }
+                    let ab_alias = Config::get_option(keys::OPTION_PRESET_ADDRESS_BOOK_ALIAS);
+                    if !ab_alias.is_empty() {
+                        v[keys::OPTION_PRESET_ADDRESS_BOOK_ALIAS] = json!(ab_alias);
+                    }
+                    let ab_password = Config::get_option(keys::OPTION_PRESET_ADDRESS_BOOK_PASSWORD);
+                    if !ab_password.is_empty() {
+                        v[keys::OPTION_PRESET_ADDRESS_BOOK_PASSWORD] = json!(ab_password);
+                    }
+                    let ab_note = Config::get_option(keys::OPTION_PRESET_ADDRESS_BOOK_NOTE);
+                    if !ab_note.is_empty() {
+                        v[keys::OPTION_PRESET_ADDRESS_BOOK_NOTE] = json!(ab_note);
+                    }
+                    let username = get_builtin_option(keys::OPTION_PRESET_USERNAME);
+                    if !username.is_empty() {
+                        v[keys::OPTION_PRESET_USERNAME] = json!(username);
+                    }
+                    let strategy_name = get_builtin_option(keys::OPTION_PRESET_STRATEGY_NAME);
+                    if !strategy_name.is_empty() {
+                        v[keys::OPTION_PRESET_STRATEGY_NAME] = json!(strategy_name);
+                    }
+                    let device_group_name = get_builtin_option(keys::OPTION_PRESET_DEVICE_GROUP_NAME);
+                    if !device_group_name.is_empty() {
+                        v[keys::OPTION_PRESET_DEVICE_GROUP_NAME] = json!(device_group_name);
+                    }
+                    let device_username = Config::get_option(keys::OPTION_PRESET_DEVICE_USERNAME);
+                    if !device_username.is_empty() {
+                        v["username"] = json!(device_username);
+                    }
+                    let device_name = Config::get_option(keys::OPTION_PRESET_DEVICE_NAME);
+                    if !device_name.is_empty() {
+                        v["hostname"] = json!(device_name);
+                    }
+                    let note = Config::get_option(keys::OPTION_PRESET_NOTE);
+                    if !note.is_empty() {
+                        v[keys::OPTION_PRESET_NOTE] = json!(note);
+                    }
+                    let v = v.to_string();
+                    let mut hash = "".to_owned();
+                    if crate::is_public(&url) {
+                        use sha2::{Digest, Sha256};
+                        let mut hasher = Sha256::new();
+                        hasher.update(url.as_bytes());
+                        hasher.update(&v.as_bytes());
+                        let res = hasher.finalize();
+                        hash = hbb_common::base64::encode(&res[..]);
+                        let old_hash = config::Status::get("sysinfo_hash");
+                        let ver = config::Status::get("sysinfo_ver"); // sysinfo_ver is the version of sysinfo on server's side
+                        if hash == old_hash {
+                            // When the api doesn't exist, Ok("") will be returned in test.
+                            let samever = match crate::post_request(url.replace("heartbeat", "sysinfo_ver"), "".to_owned(), "").await {
+                                Ok(x)  => {
+                                    sysinfo_ver = x.clone();
+                                    *PRO.lock().unwrap() = true;
+                                    x == ver
+                                }
+                                _ => {
+                                    false // to make sure Pro can be assigned in below post for old
+                                            // hbbs pro not supporting sysinfo_ver, use false for ensuring
+                                }
+                            };
+                            if samever {
+                                info_uploaded = InfoUploaded::uploaded(url.clone(), id.clone(), sys_username);
+                                log::info!("sysinfo not changed, skip upload");
+                                continue;
+                            }
+                        }
+                    }
+                    match crate::post_request(url.replace("heartbeat", "sysinfo"), v, "").await {
+                        Ok(x)  => {
+                            if x == "SYSINFO_UPDATED" {
+                                info_uploaded = InfoUploaded::uploaded(url.clone(), id.clone(), sys_username);
+                                log::info!("sysinfo updated");
+                                if !hash.is_empty() {
+                                    config::Status::set("sysinfo_hash", hash);
+                                    config::Status::set("sysinfo_ver", sysinfo_ver.clone());
+                                }
+                                *PRO.lock().unwrap() = true;
+                            } else if x == "ID_NOT_FOUND" {
+                                info_uploaded.last_uploaded = None; // next heartbeat will upload sysinfo again
+                            } else {
+                                info_uploaded.last_uploaded = Some(Instant::now());
+                            }
+                        }
+                        _ => {
+                            info_uploaded.last_uploaded = Some(Instant::now());
+                        }
+                    }
+                }
+                if conns.is_empty() && last_sent.map(|x| x.elapsed() < TIME_HEARTBEAT).unwrap_or(false) {
+                    continue;
+                }
+                last_sent = Some(Instant::now());
+                let mut v = Value::default();
+                v["id"] = json!(id);
+                v["uuid"] = json!(crate::encode64(hbb_common::get_uuid()));
+                v["ver"] = json!(hbb_common::get_version_number(crate::VERSION));
+                if !conns.is_empty() {
+                    v["conns"] = json!(conns);
+                }
+                let modified_at = LocalConfig::get_option("strategy_timestamp").parse::<i64>().unwrap_or(0);
+                v["modified_at"] = json!(modified_at);
+                if let Ok(s) = crate::post_request(url.clone(), v.to_string(), "").await {
+                    if let Ok(mut rsp) = serde_json::from_str::<HashMap::<&str, Value>>(&s) {
+                        if rsp.remove("sysinfo").is_some() {
+                            info_uploaded.uploaded = false;
+                            config::Status::set("sysinfo_hash", "".to_owned());
+                            log::info!("sysinfo required to forcely update");
+                        }
+                        if let Some(conns)  = rsp.remove("disconnect") {
+                                if let Ok(conns) = serde_json::from_value::<Vec<i32>>(conns) {
+                                    SENDER.lock().unwrap().send(conns).ok();
+                                }
+                        }
+                        if let Some(rsp_modified_at) = rsp.remove("modified_at") {
+                            if let Ok(rsp_modified_at) = serde_json::from_value::<i64>(rsp_modified_at) {
+                                if rsp_modified_at != modified_at {
+                                    LocalConfig::set_option("strategy_timestamp".to_string(), rsp_modified_at.to_string());
+                                }
+                            }
+                        }
+                        if let Some(strategy) = rsp.remove("strategy") {
+                            if let Ok(strategy) = serde_json::from_value::<StrategyOptions>(strategy) {
+                                log::info!("strategy updated");
+                                handle_config_options(strategy.config_options);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+fn heartbeat_url() -> String {
+    let url = crate::common::get_api_server(
+        Config::get_option("api-server"),
+        Config::get_option("custom-rendezvous-server"),
+    );
+    if url.is_empty() || crate::is_public(&url) {
+        return "".to_owned();
+    }
+    format!("{}/api/heartbeat", url)
+}
+
+fn handle_config_options(config_options: HashMap<String, String>) {
+    let mut options = Config::get_options();
+    let default_settings = config::DEFAULT_SETTINGS.read().unwrap().clone();
+    config_options
+        .iter()
+        .map(|(k, v)| {
+            // Priority: user config > default advanced options.
+            // Only when default advanced options are also empty, remove user option (fallback to built-in default);
+            // otherwise insert an empty value so user config remains present.
+            if v.is_empty() && default_settings.get(k).map_or("", |v| v).is_empty() {
+                options.remove(k);
+            } else {
+                options.insert(k.to_string(), v.to_string());
+            }
+        })
+        .count();
+    Config::set_options(options);
+}
+
+#[allow(unused)]
+#[cfg(not(any(target_os = "ios")))]
+pub fn is_pro() -> bool {
+    PRO.lock().unwrap().clone()
+}