Windows VM Control
Treat Windows as a separate, persistent computer. Invoking this skill authorizes a background launch of Fusion and the configured VM.
Run the bundled commands from this skill directory, or use absolute paths. Fusion, Keychain, and the private VM network require host access.
System model
The Mac can work with the VM through separate methods. One method can work while another fails.
Mac agent
-> Fusion -> configured VM
|-> Tools -> Guest Operations
| -> interactive launch -> signed-in Windows desktop -> application
|-> virtual network -> SSH route and host key -> Windows account and process
| |-> bounded Windows Codex turn
| `-> managed Windows Codex thread
`-> Fusion screen -> captured image
Each method reaches different Windows components and can confirm different facts.
| Method |
Reaches |
Shows |
Does not show |
vmrun and Tools |
VM, Windows files, and Windows processes |
Power, Tools, address, and the requested file or process check |
SSH or visible windows and dialogs |
| SSH |
One Windows account and its inherited environment |
Route, SSH host key, account, command output, and exit status |
Signed-in Windows desktop or visible windows |
| Interactive launch |
Signed-in Windows desktop |
Output from the launched process |
Which Windows control has input focus |
| Fusion capture |
Windows screen shown by Fusion |
Current Fusion screen image |
An RDP or other Windows desktop |
| Bounded Windows Codex |
One self-contained task where later steps depend on earlier output |
The turn's event stream and report |
Independent confirmation of completion |
| Managed Windows Codex |
A delegated assignment that needs follow-up, steering, interruption, or answered requests |
Correlated thread, turn, item, and request events |
Signed-in desktop state or independent confirmation |
VM disks, files, the SSH host key, settings, and configuration survive restarts. Power, Tools, addresses, routes, process environments, whether a Windows user is signed in, input focus, and running processes can change. A running process does not receive later environment changes. A status field may be unknown because the requested readiness check did not require that capability.
What the agent may do
| Action |
Rule |
| Launch Fusion in the background; start the configured VM |
Proceed |
| Run read-only checks; use SSH, background capture, or Guest Operations |
Proceed for the VM, files, and actions named in the request |
| Bring an app forward; change Mac focus; move or capture the Mac pointer |
Ask first |
| Enter a password, passkey, multifactor response, or approve a prompt that confirms the user's identity or grants account access |
Stop for the user |
| Use another VM or account; suspend or stop Windows; revert a snapshot; delete persistent data; modify another checkout |
Ask first |
Do not let two agents or processes modify the same checkout or process tree at the same time.
Choose how to work
Name the check that would show the requested work is complete.
Choose the method that can run that check.
Check that method. If it fails, find the first component that did not respond as expected:
Tools: Fusion -> VM -> Tools -> Guest Operations
SSH: Fusion -> VM -> network -> route and SSH host key -> Windows account -> process
Desktop: Fusion -> VM -> Tools -> interactive launch -> signed-in Windows desktop -> application
Use the linked recipe. Read its output before acting again.
| Goal |
Method |
Recipe |
| VM startup, power, Tools, or address |
vmrun |
Lifecycle |
| One or two commands known before execution |
SSH |
Direct SSH |
| A multiline PowerShell script known before execution |
SSH PowerShell helper |
Scripted PowerShell |
| One self-contained task where each next step can depend on earlier output |
Bounded Windows Codex |
Bounded Windows Codex run |
| A delegated assignment across turns, or work that may need steering or answered requests |
Managed Windows Codex |
Managed delegation |
| Which window or dialog is visible and has Windows input focus |
Interactive launch |
Desktop work |
| SSH or route recovery |
Tools, then SSH |
Access recovery |
After one quoting failure, nested logic, or about 30 seconds of command composition, move from direct SSH to scripted PowerShell, bounded Windows Codex, or managed delegation.
When managed delegation starts, make Windows Codex the sole executor for that checkout. The Mac agent coordinates, answers requests, and performs host-only desktop or UAC support. It does not run independent checkout commands or duplicate the delegated work until the active turn ends.
Finish
Use the method that can show completion. For managed delegation, treat item/completed and turn/completed as terminal protocol state; treat deltas as progress only. Do not treat an agent report as completion until the relevant file, process, test, or visible Windows check agrees. Remove only temporary files and processes created for the current task.
1---2name: windows-vm-control3description: Control and automate a VMware Fusion Windows VM from Codex running on the Mac host. Use for Windows commands, files, builds, tests, VM lifecycle, native Windows UI, screenshots, Windows login and UAC prompts, and delegation to Codex inside the VM.4---56# Windows VM Control78Treat Windows as a separate, persistent computer. Invoking this skill authorizes a background launch of Fusion and the configured VM.910Run the bundled commands from this skill directory, or use absolute paths. Fusion, Keychain, and the private VM network require host access.1112## System model1314The Mac can work with the VM through separate methods. One method can work while another fails.1516```text17Mac agent18 -> Fusion -> configured VM19 |-> Tools -> Guest Operations20 | -> interactive launch -> signed-in Windows desktop -> application21 |-> virtual network -> SSH route and host key -> Windows account and process22 | |-> bounded Windows Codex turn23 | `-> managed Windows Codex thread24 `-> Fusion screen -> captured image25```2627Each method reaches different Windows components and can confirm different facts.2829| Method | Reaches | Shows | Does not show |30| --- | --- | --- | --- |31| `vmrun` and Tools | VM, Windows files, and Windows processes | Power, Tools, address, and the requested file or process check | SSH or visible windows and dialogs |32| SSH | One Windows account and its inherited environment | Route, SSH host key, account, command output, and exit status | Signed-in Windows desktop or visible windows |33| Interactive launch | Signed-in Windows desktop | Output from the launched process | Which Windows control has input focus |34| Fusion capture | Windows screen shown by Fusion | Current Fusion screen image | An RDP or other Windows desktop |35| Bounded Windows Codex | One self-contained task where later steps depend on earlier output | The turn's event stream and report | Independent confirmation of completion |36| Managed Windows Codex | A delegated assignment that needs follow-up, steering, interruption, or answered requests | Correlated thread, turn, item, and request events | Signed-in desktop state or independent confirmation |3738VM disks, files, the SSH host key, settings, and configuration survive restarts. Power, Tools, addresses, routes, process environments, whether a Windows user is signed in, input focus, and running processes can change. A running process does not receive later environment changes. A status field may be `unknown` because the requested readiness check did not require that capability.3940## What the agent may do4142| Action | Rule |43| --- | --- |44| Launch Fusion in the background; start the configured VM | Proceed |45| Run read-only checks; use SSH, background capture, or Guest Operations | Proceed for the VM, files, and actions named in the request |46| Bring an app forward; change Mac focus; move or capture the Mac pointer | Ask first |47| Enter a password, passkey, multifactor response, or approve a prompt that confirms the user's identity or grants account access | Stop for the user |48| Use another VM or account; suspend or stop Windows; revert a snapshot; delete persistent data; modify another checkout | Ask first |4950Do not let two agents or processes modify the same checkout or process tree at the same time.5152## Choose how to work53541. Name the check that would show the requested work is complete.552. Choose the method that can run that check.563. Check that method. If it fails, find the first component that did not respond as expected:5758 ```text59 Tools: Fusion -> VM -> Tools -> Guest Operations60 SSH: Fusion -> VM -> network -> route and SSH host key -> Windows account -> process61 Desktop: Fusion -> VM -> Tools -> interactive launch -> signed-in Windows desktop -> application62 ```63644. Use the linked recipe. Read its output before acting again.6566| Goal | Method | Recipe |67| --- | --- | --- |68| VM startup, power, Tools, or address | `vmrun` | [Lifecycle](references/lifecycle.md) |69| One or two commands known before execution | SSH | [Direct SSH](references/command-work.md#direct-ssh) |70| A multiline PowerShell script known before execution | SSH PowerShell helper | [Scripted PowerShell](references/command-work.md#scripted-powershell) |71| One self-contained task where each next step can depend on earlier output | Bounded Windows Codex | [Bounded Windows Codex run](references/command-work.md#bounded-windows-codex-run) |72| A delegated assignment across turns, or work that may need steering or answered requests | Managed Windows Codex | [Managed delegation](references/managed-delegation.md) |73| Which window or dialog is visible and has Windows input focus | Interactive launch | [Desktop work](references/desktop-work.md) |74| SSH or route recovery | Tools, then SSH | [Access recovery](references/access-recovery.md) |7576After one quoting failure, nested logic, or about 30 seconds of command composition, move from direct SSH to scripted PowerShell, bounded Windows Codex, or managed delegation.7778When managed delegation starts, make Windows Codex the sole executor for that checkout. The Mac agent coordinates, answers requests, and performs host-only desktop or UAC support. It does not run independent checkout commands or duplicate the delegated work until the active turn ends.7980## Finish8182Use the method that can show completion. For managed delegation, treat `item/completed` and `turn/completed` as terminal protocol state; treat deltas as progress only. Do not treat an agent report as completion until the relevant file, process, test, or visible Windows check agrees. Remove only temporary files and processes created for the current task.
sandover