hello-agent/README.md

hello-agent

A headless, RustDesk-protocol-compatible remote-support agent for Windows.

One self-contained binary, no Flutter UI. Designed for one-line MDM deployment against a self-hosted rustdesk-server (or the Pro/admin variant). A supporter using the stock rustdesk.exe client can connect; the controlled-side user gets a native approval prompt and clicks Yes / No.

CLI

hello-agent.exe --install              # register + start service
hello-agent.exe --uninstall            # stop, delete, clean up
hello-agent.exe --config <BLOB>        # import 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 (0nI900VsFHZ…)
• the host=server,key=…,api=…,relay=… filename form

If --config is omitted and no prior install left a rendezvous configuration behind, hello-agent falls back to a built-in default pointing at the cybnet rustdesk-server:

custom-rendezvous-server = rd.gamecom.ch
api-server               = https://rd.gamecom.ch
relay-server             = rd.gamecom.ch
key                      = tcxma69cN3OWt25jQ75apSCtaZGIfDqIIP6yGNj3dgs=

Operators who run their own rustdesk-server must pass --config with their deploy blob; defaults are only applied when the config slot is empty, so --config always wins.

Architecture

hello-agent.exe --install
        │
        └──> creates Windows service "HelloAgent", binPath ends in --service
                │
hello-agent.exe --service                      # Session 0, LocalSystem
        │
        └──> spawns into the active console session as SYSTEM token:
                │
hello-agent.exe --server                       # user session, SYSTEM token
        │
        ├── default ipc listener (rustdesk core)
        ├── RendezvousMediator   ──> rustdesk-server registration + NAT
        ├── hbbs_http::sync      ──> /api/heartbeat + /api/sysinfo
        │
        │   at startup, --server proactively spawns (via WTSQueryUserToken
        │   + CreateProcessAsUserW with lpDesktop = winsta0\default —
        │   librustdesk's run_as_user uses lpDesktop=NULL which inherits
        │   the invisible Session 0 service desktop):
        ▼
hello-agent.exe --cm                           # user session, USER token,
        │                                        # winsta0\default desktop
        ├── binds `_cm` IPC pipe (long-running — one child per session)
        ├── reads Data::Login from parent's start_ipc
        ├── shows MessageBoxW on the user's interactive desktop
        └── replies Data::Authorize / Data::Close (per peer), keeps listening

The protocol stack (rendezvous, login validation, screen capture, input, relay) is the upstream librustdesk code, vendored under vendor/rustdesk/ for an independent build. This crate is the thin shell that gives us the new CLI surface, the Windows service shell, and the native approval popup that replaces the stock Flutter Connection Manager.

Repo layout

hello-agent/
├── src/                    hello-agent sources (~600 lines)
├── vendor/rustdesk/        vendored RustDesk crate + workspace libs
│   ├── Cargo.toml          rustdesk's own workspace + package manifest
│   ├── src/                librustdesk source
│   └── libs/               hbb_common, scrap, enigo, clipboard, …
├── Cargo.toml              hello-agent package manifest, path-deps on vendor
├── .gitea/workflows/       Gitea CI
└── README.md

The vendored source has a few local divergences from upstream — all documented inline at the patch site so they're easy to spot when re-syncing:

1. vendor/rustdesk/src/lib.rs: mod custom_server → pub mod custom_server so hello-agent can call the deploy-blob decoder.
2. vendor/rustdesk/Cargo.toml: [lib] crate-type reduced from ["cdylib", "staticlib", "rlib"] to ["rlib"]. We statically link the rlib into hello-agent.exe; the cdylib link step (used by upstream for Flutter FFI) trips LNK1169 multiply-defined symbols from overlapping windows-targets/windows_x86_64_msvc versions and we don't need it.
3. Heartbeat intervals lowered 15s → 1s so device-online status in the admin UI reacts faster: vendor/rustdesk/libs/hbb_common/src/config.rs (REG_INTERVAL, UDP rendezvous re-register) and vendor/rustdesk/src/hbbs_http/sync.rs (TIME_HEARTBEAT, HTTP /api/heartbeat).

Build

Local (Windows)

$env:VCPKG_ROOT = "C:\vcpkg"
cd vendor\rustdesk
& "$env:VCPKG_ROOT\vcpkg" install --triplet x64-windows-static
cd ..\..
cargo build --release --bin hello-agent
# → target\release\hello-agent.exe

The first build is slow (~15 min) because cargo compiles the entire RustDesk crate plus its workspace libraries. Subsequent builds are incremental.

CI

.gitea/workflows/build-windows.yml builds on a self-hosted Windows runner. It checks out hello-agent (self-contained, no submodules), runs vcpkg against the vendored vcpkg.json, builds, and uploads SignOutput\hello-agent-<version>-x86_64.exe.

Re-syncing the vendored copy

To pull updates from upstream RustDesk:

1. Sync the upstream rustdesk repo locally and git submodule update --init for libs/hbb_common.
2. rsync -a --delete --exclude=.git --exclude=target --exclude=flutter --exclude=appimage … upstream-rustdesk/ vendor/rustdesk/
3. Re-apply the one-line pub mod custom_server patch in vendor/rustdesk/src/lib.rs.
4. cargo build --release --bin hello-agent — fix any breakage from upstream API drift in our src/ modules.

Stale keys / supporter "stuck on connecting"

The agent's identity (id) and key_pair live in HelloAgent.toml. They're generated once on first run, registered with the rendezvous server, and re-used forever after. If the rendezvous server's cached entry and the agent's local keypair drift apart, the encrypted handshake silently fails on the supporter side — the supporter's stock rustdesk client shows "Please wait for the remote side…" / similar, the agent log shows a Connection opened followed by ~30 seconds of nothing then Peer close, and the popup never fires (because no LoginRequest ever decrypts).

How to recognize it: agent log says register_pk of rd due to key not confirmed followed by Generated new keypair for id:, and the rustdesk-server admin UI already has a record for that agent id from prior runs.

How to recover:

1. Delete the device record for that agent id from the rustdesk-server admin UI's device list. The next agent heartbeat re-creates it with the current public key.
2. Restart the supporter's stock rustdesk app (clears its in-process pubkey cache).
3. Reconnect — the supporter now resolves the current pubkey, the handshake succeeds, the popup fires.

hello-agent --uninstall deliberately preserves the LocalService config dir so the agent keypair survives an uninstall→reinstall cycle. To force a fresh keypair, also run after --uninstall:

rmdir /s /q "%SystemRoot%\ServiceProfiles\LocalService\AppData\Roaming\HelloAgent"

…and then delete the device record from the admin UI as above.

Verifying end-to-end

1. Install: hello-agent.exe --install --config <BLOB> from elevated PowerShell.
2. Confirm: sc query HelloAgent → RUNNING.
3. From another machine running stock rustdesk.exe, enter the agent's ID and click Connect.
4. The agent's logged-in user sees HelloAgent — Allow remote support?. Click Yes; session opens, mouse/keyboard/screen all work.
5. Uninstall: hello-agent.exe --uninstall. Confirm sc query returns 1060.

Namespacing

hbb_common ships a single global, APP_NAME, that drives the location of every piece of on-disk state (config dir, log dir) and the prefix of every named pipe. Upstream defaults it to "RustDesk". Hello-agent rewrites it to "HelloAgent" as the very first line of main() — identical to the write path the upstream Flutter build uses for OEM rebrands (read_custom_client). Because APP_NAME is a RwLock<String> read lazily on first use, doing the write before any path code runs is enough to redirect every hbb_common consumer in the same process tree.

In practice that means:

What	Stock rustdesk	hello-agent
User-mode config / logs	%APPDATA%\RustDesk\	%APPDATA%\HelloAgent\
Service-mode config / logs	…\LocalService\AppData\Roaming\RustDesk\	…\LocalService\AppData\Roaming\HelloAgent\
Identity file (id + keypair)	RustDesk.toml	HelloAgent.toml
IPC pipe namespace	\\.\pipe\RustDesk\query…	\\.\pipe\HelloAgent\query…
Windows service name	RustDesk	HelloAgent
Install dir	%ProgramFiles%\RustDesk\	%ProgramFiles%\hello-agent\

The two binaries can therefore coexist on the same machine without clobbering each other's state. The override is set in src/main.rs (pub const APP_NAME: &str = "HelloAgent") — change it there if you ever need to re-brand.

Where logs go

hbb_common's logger writes per-mode rolling files under <config_dir>/log/<mode>/:

Mode (CLI flag)	Effective user	Log dir
--install / --uninstall	calling user (must be admin)	%APPDATA%\HelloAgent\log\install\ (or …\uninstall\)
--service	LocalSystem (mirrored)	%SystemRoot%\ServiceProfiles\LocalService\AppData\Roaming\HelloAgent\log\service\
--server (worker)	LocalSystem (mirrored)	%SystemRoot%\ServiceProfiles\LocalService\AppData\Roaming\HelloAgent\log\server\
no flags (dev mode)	calling user	%APPDATA%\HelloAgent\log\hello-agent\

The cm_popup module also writes a parallel diagnostic trace at %TEMP%\hello-agent-cm.log (kept around for debugging the IPC handshake; it duplicates info that's already in the main log).

Status

• ✅ Windows x64 (physical console and RDP sessions — the agent picks whichever session the user is actively using)
• ✅ Coexists with stock RustDesk on the same box — config dir, log dir, and named pipes are namespaced under HelloAgent rather than the upstream default of RustDesk (see Namespacing below). The only residual contention is the optional direct-server port (TCP 21118) and LAN-discovery port (UDP 21119); both default to off, so a vanilla install of each side can run simultaneously.
• ⏳ Linux / macOS (out of scope for v0)
• ⏳ Code signing (CI warns, doesn't sign)
• ⏳ Multiple simultaneous interactive users (only one can receive the approval popup at a time — the one in the WTSActive session)