Return the primary screen resolution in pixels.

Returns: str: JSON like {"ok": true, "width": 1920, "height": 1080}.

Return the current mouse cursor position in screen pixels.

Returns: str: JSON like {"ok": true, "x": 100, "y": 200}.

Move the mouse cursor to an absolute screen coordinate.

Args: params (MoveInput): x, y target and optional animation duration.

Returns: str: JSON with the resulting cursor position.

Click a mouse button, optionally at a specific coordinate.

Use clicks=2 for a double-click. If x/y are omitted the click happens at the current cursor position.

BACKGROUND TARGETING: set hwnd or window_title to click a specific window WITHOUT bringing it to the foreground (Win32 PostMessage). In that mode x/y are client coordinates of the target window and the deepest child control at that point receives the click.

Args: params (ClickInput): position, button, click count, interval, optional target.

Returns: str: JSON describing the click that was performed.

Press a mouse button at a start point and release it at an end point.

Args: params (DragInput): optional start, required end, button and duration.

Returns: str: JSON describing the drag.

Scroll the mouse wheel vertically.

Args: params (ScrollInput): amount (positive up / negative down) and optional position.

Returns: str: JSON confirming the scroll amount.

Type a string of text into the currently focused window/control.

BACKGROUND TARGETING: set hwnd or window_title to deliver the text to a specific window WITHOUT focusing it (Win32 WM_CHAR to its focused control). For edit controls, win_set_control_text is more reliable.

Args: params (TypeInput): the text, optional per-key interval, optional target.

Returns: str: JSON confirming how many characters were typed.

Press a keyboard combination (hotkey), e.g. Ctrl+C or Alt+Tab.

A single-element list presses one key; multiple elements are pressed together.

Args: params (HotkeyInput): list of pyautogui key names.

Returns: str: JSON confirming the keys pressed.

Run a system/shell command and capture its stdout, stderr and exit code.

This executes arbitrary commands on the host with the server's privileges.

Args: params (RunCommandInput): command, shell flag, cwd and timeout.

Returns: str: JSON like {"ok": true, "returncode": 0, "stdout": "...", "stderr": "...", "timed_out": false}.

List top-level windows with their titles, handles, positions and sizes.

Args: params (ListWindowsInput): optional title filter and empty-title toggle.

Returns: str: JSON {"ok": true, "count": N, "windows": [{title, handle, left, top, width, height, is_minimized, is_maximized, is_active}, ...]}.

Return information about the currently focused (active) window.

Returns: str: JSON with the active window's title, handle, position and size, or {"ok": true, "window": null} if none is active.

Move a window to a new top-left screen position.

Identify the window by handle (preferred, exact) or title (substring).

Args: params (MoveWindowInput): target window plus new x, y.

Returns: str: JSON with the window's updated geometry, or an error if not found.

Resize a window to a new width and height.

Args: params (ResizeWindowInput): target window plus new width, height.

Returns: str: JSON with the window's updated geometry, or an error if not found.

Focus, minimize, maximize, restore or close a window.

close is destructive - it sends the window a close request and the app may prompt to save. Identify the window by handle or title.

Args: params (WindowActionInput): target window plus the action to run.

Returns: str: JSON confirming the action, or an error if the window was not found.

List running processes with pid, name, memory and CPU usage.

Args: params (ListProcessesInput): optional name filter, sort key and limit.

Returns: str: JSON {"ok": true, "count": N, "processes": [{pid, name, username, memory_mb, cpu_percent}, ...]}.

Kill a process by PID, or all processes matching an exact name.

Provide either pid (preferred) or name. force=true kills hard; otherwise a graceful terminate is requested first. This is destructive and may cause the target application to lose unsaved data.

Args: params (KillProcessInput): pid or name, and force flag.

Returns: str: JSON {"ok": true, "killed": [{pid, name}], "count": N}, or an error.

Capture a screenshot of a monitor (or a pixel region) and save it as PNG.

BACKGROUND CAPTURE: set hwnd or window_title to capture one specific window via Win32 PrintWindow - this works even when the window is NOT focused, is hidden behind other windows, or runs on an off-screen/headless desktop.

Args: params (ScreenshotInput): monitor index, optional region, output path, optional window target and client_only flag.

Returns: str: JSON {"ok": true, "path": "...", "width": W, "height": H}.

Crop an existing image file to a rectangular sub-region.

Args: params (CropInput): source path, crop box (left/top/width/height), output path.

Returns: str: JSON {"ok": true, "path": "...", "width": W, "height": H}.

Begin recording the screen to an mp4 file in a background thread.

Only one recording can run at a time. Call stop_screen_recording to finish and flush the file.

Args: params (StartRecordingInput): fps, monitor, optional region and output path.

Returns: str: JSON {"ok": true, "path": "...", "fps": N, "recording": true}.

Stop the active screen recording and finalize the mp4 file.

Returns: str: JSON {"ok": true, "path": "...", "frames": N, "duration_seconds": S}.

Report whether a screen recording is currently active.

Returns: str: JSON {"ok": true, "recording": bool, "path": str|null, "frames": N, "elapsed_seconds": S|null}.

Enumerate the child controls of a window (class, text, client rect, handle).

Useful for finding the exact control handle to target with background input - e.g. the 'Edit' control inside Notepad - and its position for background clicks.

Args: params (WinTargetInput): the parent window by hwnd or title.

Returns: str: JSON {"ok": true, "parent_hwnd": N, "count": N, "children": [ {handle, class, text, left, top, width, height, visible}, ...]}. Coordinates are relative to the parent window's top-left.

Post key presses to a specific window WITHOUT focusing it (Win32 messages).

Args: params (WinSendKeysInput): target window plus key names.

Returns: str: JSON confirming the keys posted to the resolved control.

Set a control's text directly via WM_SETTEXT (reliable, no focus needed).

Pass the control's hwnd (from list_child_windows) - e.g. the Edit control of a background Notepad - to replace its text without bringing the window forward.

Args: params (WinSetTextInput): target control by hwnd (preferred) or title, plus text.

Returns: str: JSON {"ok": true, "target_hwnd": N, "text_len": N}.

Create an off-screen Win32 desktop for running GUI apps invisibly.

Apps launched on this desktop have a real GUI (so they run and can be automated and captured via PrintWindow) but never appear on the visible desktop. This is the 'headless but with GUI' mode.

Args: params (HeadlessDesktopInput): desktop name.

Returns: str: JSON {"ok": true, "name": "...", "handle": N, "full": "WinSta0\..."}.

Launch a GUI application on an off-screen desktop (creates it if needed).

The process runs with a full GUI on the hidden desktop. Use list_headless_windows to find its windows, then drive them with background input and capture them with screenshot(hwnd=...). The visible desktop is never touched.

Args: params (LaunchHeadlessInput): desktop name and command line.

Returns: str: JSON {"ok": true, "desktop": "...", "pid": N, "command": "..."}.

List the top-level windows living on an off-screen desktop.

Args: params (HeadlessDesktopInput): desktop name.

Returns: str: JSON {"ok": true, "name": "...", "count": N, "windows": [ {handle, title, class, width, height}, ...]}.

Release this server's handle to an off-screen desktop.

The desktop is fully freed by Windows once no process is still running on it, so close any apps you launched there first.

Args: params (HeadlessDesktopInput): desktop name.

Returns: str: JSON {"ok": true, "name": "...", "closed": bool}.

Make a hidden/minimized window visible and bring it to the foreground.

Useful when an automated app on the normal desktop hits a step that needs the human - typically an interactive LOGIN. Show it, let the user sign in, then call hide_window to tuck it away and resume background automation.

Args: params (WinTargetInput): the window by hwnd or title.

Returns: str: JSON {"ok": true, "hwnd": N, "visible": true}.

Hide a window again after it was shown (e.g. once login is complete).

Args: params (HideWindowInput): the window by hwnd or title, and a minimize flag.

Returns: str: JSON {"ok": true, "hwnd": N, "visible": false}.

Temporarily switch the live screen to a headless desktop for human interaction.

The entire off-screen desktop (and the apps running on it) becomes interactive and visible, so a person can complete a LOGIN or any manual step. Call hide_headless_desktop to switch back to the normal desktop afterwards.

Args: params (HeadlessDesktopInput): the off-screen desktop name.

Returns: str: JSON {"ok": true, "name": "...", "visible": true, "note": "..."}.

Switch the live screen back to the normal desktop after show_headless_desktop.

Args: params (HeadlessDesktopInput): the off-screen desktop name (for symmetry).

Returns: str: JSON {"ok": true, "restored": true}.

Report whether AutoHotkey is installed and where.

Returns: str: JSON {"ok": true, "installed": bool, "path": "...", "version": "v2", ...}.

Run an inline AutoHotkey script and capture its output.

The script MUST terminate (call ExitApp, or be non-persistent) or it runs until the timeout. Emit output with FileAppend to the target "*" (stdout). AHK is ideal for reliable background input (ControlSend/ControlClick) and real hotkeys.

Args: params (RunAhkInput): script source, optional args, timeout, optional exe path.

Returns: str: JSON {"ok": bool, "returncode": int, "stdout": "...", "stderr": "...", "exe": "..."}.

Send text or keystrokes to a background window/control via AutoHotkey ControlSend.

Works without focusing the window and is often more reliable than raw WM_CHAR for complex apps. Target a HWND with 'ahk_id '.

Args: params (AhkControlSendInput): text, window/control targets, as_keys, timeout.

Returns: str: JSON with the AHK run result.

Report Linux X11 automation tooling availability (xdotool, wmctrl, Xvfb, …).

Returns: str: JSON {"ok": true, "display": ":0", "session_type": "x11", "xdotool": bool, ...}.

Start an Xvfb virtual display — the Linux 'headless but with GUI' mode.

GUI apps launched on it run with a real X server but no physical screen, so they can be automated (xdotool) and screenshotted (mss) without occupying the visible desktop. The Linux counterpart of the Windows headless desktop.

Args: params (CreateVirtualDisplayInput): display number, width, height, depth.

Returns: str: JSON {"ok": true, "display": ":99", "size": "1280x800x24", "pid": N}.

Launch a GUI app on an Xvfb virtual display (creates it if needed).

Args: params (LaunchVirtualInput): display number and command line.

Returns: str: JSON {"ok": true, "display": ":99", "pid": N, "command": "..."}.

List the windows present on an Xvfb virtual display.

Args: params (VirtualDisplayInput): display number.

Returns: str: JSON {"ok": true, "count": N, "windows": [...]}.

Capture the whole Xvfb virtual display to a PNG.

Args: params (ScreenshotVirtualInput): display number and output path.

Returns: str: JSON {"ok": true, "path": "...", "width": W, "height": H}.

Stop an Xvfb virtual display and terminate the apps launched on it.

Args: params (VirtualDisplayInput): display number.

Returns: str: JSON {"ok": true, "display": ":99", "stopped": true}.

Report whether WSL is available on this Windows host.

Returns: str: JSON {"ok": true, "available": bool, "version": "...", ...}.

List installed WSL distros with state, version and default flag.

Returns: str: JSON {"ok": true, "count": N, "distros": [{name, state, version, default}, ...]}.

Provision a throwaway WSL distro on demand for running Linux software.

By default downloads a tiny Alpine minirootfs (a few MB) and imports it, leaving existing distros untouched. Use wsl_run to run commands in it and wsl_destroy to tear it down. Alternatively clone_from an existing distro or import base_tar.

Args: params (WslCreateInput): optional name, rootfs_url, clone_from, base_tar, timeout.

Returns: str: JSON {"ok": true, "name": "...", "install_dir": "...", "source": "alpine"}.

Run a shell command inside a WSL distro and capture stdout/stderr/exit code.

Args: params (WslRunInput): distro, command, optional user, cwd and timeout.

Returns: str: JSON {"ok": true, "distro": "...", "returncode": N, "stdout": "...", "stderr": "..."}.

List the throwaway distros this server session provisioned.

Returns: str: JSON {"ok": true, "count": N, "distros": [{name, install_dir, source, created_at}, ...]}.

Terminate and unregister a WSL distro, deleting its files (irreversible).

Args: params (WslDestroyInput): distro name and whether to delete files.

Returns: str: JSON {"ok": true, "name": "...", "destroyed": true}.

Tear down every throwaway distro provisioned in this session.

Returns: str: JSON {"ok": true, "destroyed": [...], "count": N}.

Report whether this server process is running elevated (as Administrator).

Returns: str: JSON {"ok": true, "is_admin": bool, "platform": "Windows"}.

Run a shell command with Administrator privileges.

If the server is not already elevated this triggers a Windows UAC prompt that the user must approve. Output is captured and returned. This runs commands with full administrative rights - use with care.

Args: params (RunAsAdminInput): the command line and a timeout.

Returns: str: JSON {"ok": bool, "returncode": int, "output": "...", "elevated_prompt": bool}.

Install a scheduled task so this server starts automatically at user logon.

By default the task runs with Administrator privileges (RunLevel Highest) and launches the server in HTTP mode so it is always available after boot. Registering the task requires elevation - a UAC prompt appears if the server is not already elevated.

Args: params (InstallStartupInput): run_as_admin, http, host and port options.

Returns: str: JSON {"ok": bool, "output": "...", "task_name": "...", "run_as_admin": bool}.

Remove the boot-startup scheduled task (requires elevation; may prompt UAC).

Returns: str: JSON {"ok": bool, "output": "...", "task_name": "..."}.

Report whether the boot-startup scheduled task is installed and its state.

Returns: str: JSON {"ok": bool, "installed": bool, "details": "...", "task_name": "..."}.