Headless GUI

Headless-with-GUI

Run real GUI apps that have a full interface (so they work and can be automated and screenshotted) but never occupy the visible desktop. Two implementations:

• Windows → a separate Win32 off-screen desktop.
• Linux → an Xvfb virtual display (see Linux Support).

Windows: off-screen desktop

Create the desktop:

create_headless_desktop { "name": "work" }

Launch an app onto it:

launch_on_headless_desktop { "name": "work", "command": "notepad.exe" }

List its windows (to get handles):

list_headless_windows { "name": "work" }

Drive + capture it with the Background Targeting tools using the handle:

win_set_control_text { "hwnd": 2495156, "text": "running invisibly" }

screenshot { "hwnd": 2495156 }

Release the desktop (close the apps on it first):

close_headless_desktop { "name": "work" }

Showing it for an interactive login

Some steps need a human (sign-in). Temporarily switch the live screen to the off-screen desktop:

show_headless_desktop { "name": "work" }

…let the user log in, then switch back:

hide_headless_desktop { "name": "work" }

show_headless_desktop uses SwitchDesktop, so the whole off-screen desktop (and its apps) becomes interactive. The desktop has no taskbar/shell — just the app windows.

Linux: Xvfb virtual display

Mirror flow with create_virtual_display → launch_on_virtual_display → list_virtual_display_windows → drive with the display field → screenshot_virtual_display → stop_virtual_display. Full details in Linux Support.

Resource hygiene

Always pair create with close/stop, and terminate any apps you launched (use kill_process or wsl_*/stop_*) so the desktop/display can be freed.