Feature guide · headless desktops
Every agent gets a quiet room.
Windows named desktops and Linux virtual displays keep native GUI work away from the user's visible desktop.
Behavior
Call create_headless_desktops with a count and project/agent prefix, then launch a real application with launch_on_headless_desktop. Windows launches use hidden creation flags and do not switch the user's input desktop.
Configuration
Use explicit names when several agents share a host. The Electron Workspaces tab creates a namespace from project and agent fields, lists owned rooms, and launches commands on a selected room.
Failure modes
- Duplicate desktop names are rejected.
- Missing headless capability returns a factual error instead of falling back to the visible desktop.
- Foreground-only input requires explicit focus-disruption consent.
Security
Headless is isolation from the visible input desktop, not a security sandbox. Commands still run with the server user's permissions.
Verification
The Windows suite covers multi-desktop creation and hidden launch metadata. A live host should additionally verify simultaneous rooms, unchanged foreground HWND, and cleanup.