Files
rvbox/test/rdp-access/README.md
T

32 KiB
Raw Blame History

Interactive Windows VM access

This directory is an explicitly temporary, manual-recovery path to the Helium Windows fixture desktop. It is for the small class of actions that require an interactive UAC consent dialog. Normal setup, testing, collection, and reset remain scripts/windows/test-host plus VirtualBox Guest Control.

The helper builds this private path:

browser -- HTTPS/self-signed --> nginx + Guacamole containers
       (IPv4 and, in public mode, a tracked IPv6 forward)
                                      |
                                 private Docker gateway
                                      |
controller SSH watchdog/tunnel --> Helium 127.0.0.1:3389 --> VirtualBox VRDE --> VM console

Only the HTTPS listener can be made public, and that requires an explicit --bind 0.0.0.0. The VirtualBox VRDE endpoint stays on Helium loopback and the SSH tunnel binds only to the Docker network gateway; neither is publicly exposed. Guacamole requires the fixture login before it forwards the entered password to the VM. Clipboard, drives, printing, audio, microphone input, GFX, and display-resize extensions are disabled because the fixture's VirtualBox RDP4 server does not handle them reliably.

The optional LAN-only RDP relay below is a separate, explicitly requested path on Helium. It leaves the VM's VRDE socket on loopback, binds only a private host IPv4 address, and restricts peers to the selected private LAN subnet. It does not expose the guest NAT address or enable Windows Remote Desktop.

Network and graphics quality

Use --graphics minimal|low|normal|high on up, or set RDP_ACCESS_GRAPHICS:

Mode Requested display Color Intended use
minimal 800×600, 96 DPI 8-bit / 256 colors Lowest pixel/color budget; substantial color loss
low 1024×768, 96 DPI 16-bit Slow/metered networks, terminal work
normal Browser dimensions/DPI 24-bit Default, same behavior as the original helper
high 1920×1080, 96 DPI 24-bit Fast connections and larger desktops
test/rdp-access/rdp-access up --bind 0.0.0.0 --public-host x1.xcel.me --graphics minimal
test/rdp-access/rdp-access up --bind 0.0.0.0 --public-host x1.xcel.me --graphics low
test/rdp-access/rdp-access up --bind 0.0.0.0 --public-host x1.xcel.me --graphics normal

The choice is saved per gateway profile and reused when omitted. status prints the saved graphics mode. A change rewrites the connection mapping while retaining the gateway and tunnels; log out of Guacamole and sign in again to apply it. Disconnecting/reconnecting the desktop or refreshing the page alone is insufficient: file-based authentication keeps a copy of the connection settings in each authenticated user's context. Existing logins continue with their original display settings even when they create another desktop connection. This follows the Guacamole 1.6 authentication implementation. To clear cached logins and workers without rebooting the VM or replacing the gateway/tunnels, run test/rdp-access/rdp-access repair, then sign in again. If an old browser connection holds the single VRDE slot, close it or use the documented repair action before reconnecting.

All modes keep wallpaper, themes, font smoothing, menu animation, full-window drag, audio/device redirection, and GFX disabled. Lossy compression remains available to Guacamole's normal heuristics. Display dimensions/color depth are requests to the RDP server; the negotiated framebuffer can differ if the server restricts them. A smaller display reduces pixel traffic; it cannot eliminate network latency. See the Guacamole 1.6 display settings. There is no RDP black-and-white/grayscale parameter: minimal requests a 256-color palette. Static terminal work and smaller windows generally cost less than scrolling images or video. The RDP backend does not provide VNC's quality-level/compress-level knobs; those must not be added to this RDP mapping as if they controlled its encoding.

Direct RDP on Helium's LAN

For an already-running fixture, one command detects the host's primary private IPv4 address/subnet and starts a small Docker Compose TCP relay on Helium:

test/rdp-access/rdp-access lan-up
test/rdp-access/rdp-access lan-status

The current endpoint is 192.168.50.162:3389, restricted to 192.168.50.0/24 (the helper may print its equivalent host-prefix notation, 192.168.50.162/24). Use rvboxtest and the same test-only fixture password as Guacamole, obtained from the host-local password file in docs/testing-vm.md. Authentication is passed through to the existing VBoxAuthSimple endpoint; the relay stores no password.

Disconnect the Guacamole desktop before connecting an RDP app. Both routes use the same single VirtualBox console slot. Changing the access route does not log off Windows or create another WTS user session. Leave multi-connection and connection reuse disabled; do not "fix" a rejected second connection by changing that fixture contract. You can keep the web gateway running for later use, or stop it with rdp-access down while the LAN relay remains available.

This is the working VirtualBox VRDE endpoint, not Windows TermService. Native Windows RDP remains disabled, and its old NAT port 3390 is not this LAN endpoint. The VRDE backend currently uses legacy security=rdp; a client that requires NLA/TLS or newer RDP extensions may not be compatible. This relay changes reachability, not VirtualBox's protocol compatibility. Do not forward this debug endpoint through a WAN router or expose it publicly.

To start Guacamole and the independent LAN relay together:

test/rdp-access/rdp-access up \
  --bind 0.0.0.0 --public-host x1.xcel.me --graphics minimal --lan

Stop, remove, or recreate only the LAN route:

test/rdp-access/rdp-access lan-down           # retain small generated config
test/rdp-access/rdp-access lan-clean          # remove that profile's config
test/rdp-access/rdp-access lan-clean --images # also try removing its unused image
test/rdp-access/rdp-access lan-up             # recover/reproduce after cleanup

These commands do not stop/reset the VM, change Windows/firewall settings, stop Guacamole, or affect another LAN profile. Conversely, web down/clean do not disable LAN access: use lan-down/lan-clean explicitly. Before the usual final VM reset, close both routes if both were enabled. Cleanup checks profile/VM ownership labels, stops only that Compose project, deletes only its known generated files, and never force-removes a shared image or runs a global Docker prune. Unexpected files are retained for inspection.

All fixture settings have overridable defaults; the most useful overrides are:

Variable / option Default Purpose
RDP_ACCESS_LAN_BIND / --lan-bind auto Detect primary LAN IP; override for another private host interface
RDP_ACCESS_LAN_PORT / --lan-port 3389 Client-facing port; choose a free port on conflicts
RDP_ACCESS_LAN_CIDR / --lan-cidr auto Allow only the selected interface's subnet; override for a specific private subnet
RDP_ACCESS_PROFILE / --profile default Independent relay per VM/access profile
RVBOX_TEST_VBOX_HOST helium-remote SSH host for Docker/VBoxManage
RDP_ACCESS_VRDE_PORT 3389 Existing VM's loopback-only backend; verified against its actual VRDE port
RDP_ACCESS_LAN_REMOTE_ROOT /home/cabbage/.local/state/rvbox-rdp-access/lan Small generated per-profile Compose/state directories on Helium

Explicit example for another LAN interface or a port conflict:

test/rdp-access/rdp-access lan-up \
  --lan-bind 192.168.50.162 --lan-port 3391 --lan-cidr 192.168.50.0/24

lan-up rejects wildcard, loopback, public, unassigned, and malformed bind addresses, excessive subnet masks, unowned port listeners, and a mismatched VM or backend. It never kills an unrelated listener. Startup is idempotent, and four bounded SSH attempts handle interruptions. Status/down/clean use saved remote configuration, so they work even with the VM off; status distinguishes the LAN listener from the VM's private backend being active/inactive. Rerun lan-up to reconstruct missing generated state once the VM is running. After a host DHCP address change, rerun lan-up and use its newly printed endpoint. Existing host/network firewalls still apply; the helper does not grant broad firewall access or configure router forwarding.

For multiple VMs, export each VM's recorded RVBOX_TEST_VBOX_VM, VM UUID, snapshot name/UUID, and loopback VRDE port, choose a unique profile and LAN port, then repeat that profile/host/VM identity on its lifecycle commands. Do not reuse default to take over another VM's relay. The host-side projects are rvbox-rdp-lan-<profile> and state lives under the remote root's <profile>/ directory, independent of the web gateway's local .runtime/.

The relay uses a digest-pinned Alpine socat image and Linux Docker host networking to reach the existing loopback backend without changing its bind address. It runs non-root, read-only, without Linux capabilities or host mounts, with 32 MiB/32-PID limits, at most 16 children, and bounded logs. No host package, Windows service, or persistent broker is installed.

Current fixture quick start

The following is the copy/paste path for the documented rvbox-win10-test fixture. Run it from the repository root. The first command acquires the exclusive VM lease, restores the clean Python/administrator-enabled snapshot, starts the VM, and applies the VRDE display keepalive. The second command starts the Docker-only gateway at the currently published endpoint:

scripts/windows/test-host prepare --run-id interactive-rdp
test/rdp-access/rdp-access up \
  --bind 0.0.0.0 \
  --public-host x1.xcel.me

up prompts for the fixture password. If the password is not already in the operator's secure notes, the test-only value is available only in the Helium host's mode-600 file documented in docs/testing-vm.md. For an unattended first start, pass that file through the existing SSH alias without putting the value in an argument, environment variable, or log:

ssh helium-remote 'cat /home/cabbage/.local/share/rvbox-secrets/rvbox-win10-test.password' |
  test/rdp-access/rdp-access up \
    --bind 0.0.0.0 \
    --public-host x1.xcel.me \
    --web-password-stdin

The browser URL is https://x1.xcel.me:5002/guacamole/; accept the temporary self-signed certificate warning and sign in as rvboxtest. The same command is safe to rerun after a tunnel interruption. If the stack is already running, up reuses it and repairs only missing forwarding; it does not consume stdin. Use --reset-auth only after down when intentionally replacing the saved verifier, for example:

test/rdp-access/rdp-access down
ssh helium-remote 'cat /home/cabbage/.local/share/rvbox-secrets/rvbox-win10-test.password' |
  test/rdp-access/rdp-access up \
    --bind 0.0.0.0 \
    --public-host x1.xcel.me \
    --reset-auth \
    --web-password-stdin

Do not run clean or test-host reset while another agent owns the fixture lease or has a live browser session. The generated verifier, certificate, tunnel state, and logs are disposable and live only under the ignored test/rdp-access/.runtime/ directory.

Before a first prepare, run scripts/windows/test-host status. If it reports state=running, another run may already own the fixture lease; do not restore or reset it. Reuse that run's access path or coordinate with its owner. If it reports state=poweroff, the quick-start sequence above is safe. The helper does not guess at ownership or silently take over a running VM.

Lifecycle

Run commands from the repository root. First prepare the disposable VM using a dedicated run ID. This restores the snapshot, starts the VM headlessly, and holds the exclusive fixture lease while the manual action is in progress:

scripts/windows/test-host prepare --run-id interactive-rdp

For browser access from another machine, deliberately expose the temporary HTTPS listener and name the host or IP users will enter in the browser:

test/rdp-access/rdp-access up \
  --bind 0.0.0.0 \
  --public-host x1.example.net

The command prompts without echo for the fixture password. It stores only its MD5 verifier in test/rdp-access/.runtime/config/user-mapping.xml, mode 600; the plaintext password is not placed in a command line, environment variable, log, or repository file. Browse to the printed https://.../guacamole/ URL, accept the short-lived self-signed certificate warning, and sign in as rvboxtest with the fixture password.

For localhost-only use, omit --bind and --public-host. The default listener is 127.0.0.1:5002; use a local SSH forward or a browser on the controller. Choose alternate ports with --http-port and --tunnel-port if either is in use. The VM must already be running. up checks the documented VM/snapshot identity but intentionally does not restore, start, stop, or reset the VM. It starts a small host-side watchdog for the SSH master. Before printing the URL, up waits until the HTTPS gateway can serve /guacamole/; this prevents a browser login from racing Tomcat's Guacamole WAR deployment. The watchdog reconnects after a transient Helium/SSH failure while preserving the same Docker-gateway listener, so an already-open Guacamole session can recover without restarting the containers. Its PID, stop marker, and diagnostic log are kept under the ignored .runtime/ directory.

All fixture-specific values have embedded, working defaults: the helium-remote SSH alias, Helium's loopback VRDE endpoint (127.0.0.1:3389), rvboxtest, the browser listener (127.0.0.1:5002), and the private tunnel port (54001). They can be overridden without editing tracked files through RVBOX_TEST_VBOX_HOST, RDP_ACCESS_VRDE_HOST, RDP_ACCESS_VRDE_PORT, RDP_ACCESS_PROFILE, RDP_ACCESS_WEB_USER, RDP_ACCESS_RDP_USER, RDP_ACCESS_BIND, RDP_ACCESS_HTTP_PORT, RDP_ACCESS_TUNNEL_PORT, and RDP_ACCESS_PUBLIC_HOST, RDP_ACCESS_IPV6_BIND, and RDP_ACCESS_IPV6_FORWARD. The helper deliberately limits the VRDE host to Helium loopback (127.0.0.1 or localhost) so an override cannot accidentally turn the diagnostic server into a remote target. Set RDP_ACCESS_GUACD_LOG_LEVEL=debug temporarily when collecting detailed guacd/RDP negotiation diagnostics; the default is info.

The VM selector and the gateway profile are separate. Set the matching RVBOX_TEST_VBOX_* identity variables (and RDP_ACCESS_VRDE_PORT) for the VM you want; the complete identity set is listed in docs/testing-vm.md. For two already-running VMs, give the second gateway a distinct profile and listener ports, for example:

RDP_ACCESS_PROFILE=vm-b \
RVBOX_TEST_VBOX_HOST=helium-remote-b \
RDP_ACCESS_VRDE_PORT=3391 \
RDP_ACCESS_HTTP_PORT=5003 \
RDP_ACCESS_TUNNEL_PORT=54002 \
test/rdp-access/rdp-access up --bind 0.0.0.0 --public-host vm-b.example.net

Replace helium-remote-b, 3391, and the public hostname with the second fixture's recorded values, and export its matching VM/snapshot UUID variables before running up or status. A non-default profile stores its verifier, certificate, tunnel state, and logs under .runtime/<profile>/ and uses the Compose project rvbox-rdp-access-<profile>. Keep the HTTP port, public hostname, and profile unique so IPv4/IPv6 listeners and browser sessions do not collide. Inspect, repair, stop, or clean that instance by repeating the same RDP_ACCESS_PROFILE and endpoint variables on status, repair, down, or clean.

Profile isolation does not bypass the native controller's exclusive lease: test-host prepare/reset must still be coordinated when VMs share one fixture host and staging root. For VMs that are already running, the profile and matching identity/VRDE variables are sufficient to select the endpoint.

When --bind 0.0.0.0 is used, up also starts a tracked socat listener on [::]:$RDP_ACCESS_HTTP_PORT and forwards it to the IPv4 gateway listener. This matters when the public hostname has an AAAA record: some browsers choose IPv6 for the WebSocket even if the initial page used IPv4. The listener is recorded under .runtime/ipv6-forward.pid and is removed by down and clean. Its default bind is :: (RDP_ACCESS_IPV6_BIND); set RDP_ACCESS_IPV6_FORWARD=never to deliberately use IPv4 only, always to make IPv6 startup a hard requirement, or leave the default auto for a warning and an IPv4-only fallback when socat is unavailable. status reports ipv6_forward=active, active_external, inactive, or disabled.

If up is run again while the Compose services are still running, it is idempotent: an existing healthy tunnel is reused, and a missing tunnel is recreated in place. status reports a helper-owned tunnel as private_tunnel=active and a listener supplied by an external/interactive SSH supervisor as private_tunnel=active_external. A missing listener is reported as private_tunnel=inactive; inspect .runtime/tunnel.log and run up again to trigger a bounded reconnect attempt.

If up reports that an existing gateway has a different configuration, or a previous start left only part of the Compose stack, run down once and then repeat up. Changing the bind address, browser host, or either port likewise requires down first; refusing to mutate a live stack prevents an old browser session from silently reaching a different endpoint.

The XML mapping intentionally uses Guacamole's ${GUAC_PASSWORD} connection parameter token. Guacamole resolves this to the password entered at web login; it is not a host environment variable and must remain in the template.

After the interactive action, close the browser connection and remove the temporary access path before releasing the fixture lease:

test/rdp-access/rdp-access down
scripts/windows/test-host reset --run-id interactive-rdp

down stops containers and the SSH watchdog/master/tunnel but retains the one-day certificate and password verifier for a quick restart. To remove all generated state, including the certificate, verifier, watchdog PID, and tunnel log:

test/rdp-access/rdp-access clean

To also reclaim the exact Guacamole and nginx images when they have no container dependency, use:

test/rdp-access/rdp-access clean --images

clean --images deliberately leaves alpine:3.20 alone because it may be shared by unrelated containers. Docker will refuse removal if any other container still depends on an image.

Operational checks and recovery

test/rdp-access/rdp-access status
test/rdp-access/rdp-access logs --tail=100
test/rdp-access/rdp-access url

If the browser reaches Guacamole but stays on “Waiting for response”, run status first. Confirm private_tunnel=active (or active_external) and, for a public dual-stack hostname, ipv6_forward=active (or a known-good external forward). Then check the VM state and the last lines of .runtime/tunnel.log. A tunnel can be recreated without losing the Compose stack by running up again. This helper already uses security=rdp and disables Guacamole's GFX extension, which are required by the fixture's legacy VRDE server. Do not switch the helper to native Windows RDP: TermService is intentionally disabled in the baseline. If VRDE remains unusable, stop this helper and use Guest Control for the deterministic portion of the work; record the blocked interactive step in the native test report.

If guacd has a stale worker and the VM reports that multiple connections are disabled, run:

test/rdp-access/rdp-access repair

repair restarts guacd and the Guacamole web application, clearing stale workers and cached login connection settings. It retains the VM, SSH tunnel, HTTPS gateway, and IPv6 forward, and does not alter the Windows guest. It restarts those services sequentially and reloads nginx's upstream DNS address so Docker service IP reassignment cannot leave a 502 Bad Gateway behind. Close old browser tabs and sign in again after it completes.

For quick recovery, use this decision table:

Need Command Effect
Inspect everything test/rdp-access/rdp-access status Read-only VM, Compose, tunnel, and IPv6-forward state
Start or reconnect access test/rdp-access/rdp-access up --bind 0.0.0.0 --public-host x1.xcel.me Reuses healthy services; recreates only missing tunnel/forward
Browser says “Waiting for response”, or resolution remains from an old preset test/rdp-access/rdp-access status; test/rdp-access/rdp-access logs --tail=100; test/rdp-access/rdp-access repair, then sign in again Diagnoses tunnel/dual-stack issues; clears cached web logins and stale guacd workers without restarting the VM
Clock updates but keyboard/mouse cannot control Windows Follow the input recovery procedure below; do not assume a frozen guest or restore a snapshot Separates video, keyboard, and mouse health; preserves the current disk
Partial stack or changed endpoint test/rdp-access/rdp-access down, then test/rdp-access/rdp-access up --bind 0.0.0.0 --public-host x1.xcel.me Recreates the exact project with the new settings
Print the current URL test/rdp-access/rdp-access url Read-only URL from the saved session
Stop temporary access test/rdp-access/rdp-access down Stops gateway, IPv6 forward, SSH watchdog/tunnel; retains verifier/cert
Reclaim generated state test/rdp-access/rdp-access clean Stops access and removes only .runtime/
Reclaim exact unused images too test/rdp-access/rdp-access clean --images Also removes owned Guacamole/nginx images; leaves shared Alpine intact
Return VM to clean baseline scripts/windows/test-host reset --run-id interactive-rdp Stops/ restores the exact leased VM snapshot and leaves it powered off

Live video but missing input

Video updates do not prove keyboard or mouse input is working. First close other desktop tabs, run rdp-access repair, and sign in again. Verify a harmless keyboard shortcut (Windows+R, then Escape) and an actual button click, not just pointer movement. Do not run a second independent RDP probe while the browser owns the fixture's single VRDE connection slot.

On this Windows 10 / VirtualBox 7.2.16 fixture, the PS/2 pointing device accepted pointer movement but did not activate buttons through Guacamole. A normal Windows restart did not repair that mouse path. Switching to a USB tablet with an OHCI controller initially passed a single-click check, but the failure recurred. Do not treat that check as proof of a durable fix. The interactive Windows probe then recorded 106 changing pointer samples, no left/right button-down samples, and no accepted OK clicks, despite Guacamole receiving browser mouse-down/up events. Guest Control, the updating clock, and Get-PnpDevice reporting OK all remained healthy during the failure.

The guest mouse class had UpperFilters = VBoxMouse, mouclass. A USB tablet alone does not necessarily bypass mouse integration: VirtualBox's mouse-routing implementation prefers the Guest Additions absolute-pointer path when advertised and can send buttons separately through the emulated relative mouse. After an explicitly approved, backed-up removal of only VBoxMouse from that class filter and a normal Windows restart, VBoxMouse was stopped, the standard drivers remained running, and input counters moved to the USB-tablet queue. Ten controlled clicks through the existing Guacamole/guacd connection produced ten button-down/up transitions and ten accepted OK results in Windows. This supports a workaround for this fixture's mouse-integration path; it does not establish the precise VirtualBox driver defect or prove every browser/hardware combination.

scripts/windows/test-host prepare now configures the USB tablet and enables VRDE input after each snapshot restore, before boot. The canonical baseline also records the detached VBoxMouse filter; prepare verifies it remains detached, with healthy standard drivers and USB input, before reporting success. The older snapshots are retained unchanged for rollback. A manual restore of an older snapshot followed by VBoxManage startvm bypasses this normalization and can restore both the PS/2-only configuration and the problematic filter. Oracle documents the USB tablet's absolute-coordinate input in its pointing-device settings.

To repair a currently running VM without discarding its disk changes, first ask the desktop user to save work. Use Guest Control to request a normal Windows shutdown, wait until this exact VM is poweroff, then run on Helium:

# Defaults shown; substitute the verified VM name for another fixture.
VBoxManage modifyvm rvbox-win10-test --usb-ohci on --mouse usbtablet \
  --vrde-property 'Client/DisableInput='
VBoxManage startvm rvbox-win10-test --type headless

Check the VM UUID and lease owner before changing it. Do not force a poweroff if normal shutdown is blocked by unsaved work. Repair the Guacamole connection and sign in again if necessary. This preserves installed files, Python and its machine PATH; it closes running applications. Do not use test-host reset or prepare for state-preserving recovery: both restore a baseline and discard current disk changes. rdp-access repair alone never changes the virtual input hardware or restarts Windows.

Opt-in mouse-filter workaround and rollback

The canonical baseline already records this workaround, so normal preparation does not need an extra driver change or restart. prepare fails visibly if the filter or unhealthy devices return; it does not silently repair a live desktop. When diagnosing an older baseline or an explicit Guest Additions reinstall, with the fixture running and the current lease owner known:

scripts/windows/test-host mouse-status --run-id interactive-rdp
scripts/windows/test-host mouse-bypass --run-id interactive-rdp
scripts/windows/test-host mouse-verify --run-id interactive-rdp

The second action requires the fixture's full-token administrator and a healthy VirtualBox USB-tablet device. It backs up the original ordered filter list to C:\ProgramData\RVBoxFixture\mouse-filter-backup.json, preserving that first backup on repeated runs, and copies it to the Helium run directory. It removes only VBoxMouse; mouclass, other filters, LowerFilters, keyboard devices, driver files/services, and Guest Additions are retained. It refuses unexpected filter changes since the backup. The class property is REG_MULTI_SZ, not a single string.

Only the present mouse devices are reloaded with pnputil /restart-device, which Windows 10 22H2 supports. pnputil_exit=3010 / reboot_required=True means a normal Windows restart is still required. On the current fixture the USB mouse reloaded immediately, but the PS/2 device required that restart. The helper never restarts Windows, force-powers off the VM, or restores a snapshot. Save desktop work before restarting Windows normally, then repeat mouse-verify: it succeeds only when the filters omit VBoxMouse, VBoxMouse is stopped, and mouclass/mouhid and both devices are healthy.

To undo the workaround, keeping the same disk and original backup:

scripts/windows/test-host mouse-restore --run-id interactive-rdp

Restart Windows normally if requested, and inspect mouse-status again. Restore uses the original filter order and also refuses unrelated intervening changes. Neither bypass nor restore is retried automatically after an interrupted remote execution: inspect the resulting state first. Restoring the canonical baseline also restores the known-good detached filter and its rollback record; restoring an older baseline can discard both. Do not disable/delete VBoxMouse.sys while the class still references it, and do not remove mouclass: either can break normal mouse input. This filter supplies VirtualBox's mouse-pointer integration, not an RVBox feature or security restriction. Standard USB-tablet input does not need it. Guest Control and video support use other Guest Additions components and remain installed. Avoid untracked Guest Additions updates/reinstalls; they can register the filter again. After an intentional update, verify/reapply the workaround, restart normally if needed, and re-run real click checks before capturing another clean baseline. No workaround guarantees immunity from all future browser, transport, or unrelated driver failures.

For a Windows-side click check, copy test/rdp-access/mouse-probe.py to the desktop and run it with C:\Python313\python.exe in the interactive desktop session. Guest Control runs in Session 0 and cannot measure the desktop's button state. Ten OK clicks should advance the dialog count and finish the probe; the adjacent .log must contain left: true samples and ten dialog_result entries with result: 1. Logs include only mouse coordinates, button state, and diagnostic results, never typed keys. Mouse sampling lasts ten minutes; monitor_finished marks the limit. Relaunch for a fresh capture (the previous probe log is overwritten, so collect it first).

If Windows+R is intercepted by the browser/host, a verified operator can use VBoxManage controlvm <verified-VM> keyboardputscancode e0 5b 13 93 e0 db on Helium to open remote Run. Inspect a screenshot to verify that Run is open before typing the exact probe command with keyboardputstring; use Ctrl+A to replace old Run history. Do not blindly send Enter or type into the user's existing command prompt. Do not inject the command via guessed Unicode Guacamole keysyms: this fixture did not accept that text reliably. A read-only observer may join the existing guacd connection for diagnostics, but an independent RDP connection would compete for its single slot.

The two scripts have a deliberate ownership boundary. rdp-access manages only the temporary browser gateway, Guacamole/guacd containers, IPv6 forward, and Helium SSH tunnel. scripts/windows/test-host manages the leased VM and its service lifecycle. For a prepared run, the remaining VM-side management actions are:

scripts/windows/test-host inspect --run-id interactive-rdp  # SCM/read-only client state
scripts/windows/test-host logs --run-id interactive-rdp     # bounded startup/client logs
scripts/windows/test-host collect --run-id interactive-rdp  # bounded artifacts
scripts/windows/test-host stop --run-id interactive-rdp     # stop service and request guest shutdown
scripts/windows/test-host recover --run-id interactive-rdp  # inspect an interrupted stopped run

stage, install, run, and logoff are also available in the test-host --help command reference for a complete native-service run; they are not required merely to use the RDP gateway. native-test recover and native-test clean are the corresponding whole-lane recovery/cleanup actions when the Linux server stack is part of the run.

The helper requires Docker/Docker Compose with Docker socket access for the invoking account (docker version must succeed), socat for the optional public dual-stack forward, SSH access through the existing helium-remote alias, and the fixture password file documented in docs/testing-vm.md. It does not install host packages, write credentials into Git, or alter VM identity/settings. The authoritative test-host prepare step applies only the disposable display/sleep keepalive needed by VirtualBox VRDE; all generated content is ignored beneath .runtime/.