n2ns/hyper-hand

**Give your AI agent a Windows VM it can see, operate and roll back.**
HyperHand is an MCP server for Windows and Hyper-V. Connect Claude Code, Codex or another MCP client to let your agent test installers, operate desktop software, run commands and check the results in a virtual machine.
The host-to-guest connection needs no guest network access, and you do not need to give the AI your guest password. Screenshots, mouse and keyboard input work through Hyper-V, including on sign-in screens and UAC prompts.
Download · Quick start · User guide · Tool reference
For example, after setup, ask your agent:
> In the Win10 VM, create a checkpoint, copy D:\build\setup.exe from the host and install it. Open the installed app, take a screenshot and report whether it starts. Then restore the checkpoint.
> [!WARNING]
> HyperHand gives an AI full control of your virtual machines. Use VMs you can afford to lose, and keep checkpoints. Any program on your computer can reach HyperHand's local MCP endpoint, which has no password.
What you can use it for
- **Test Windows installers and builds**: copy in a build, click through setup, check that the application opens and restore a checkpoint for the next run.
- **Automate desktop software without an API**: let the agent read buttons and fields through Windows UI Automation, or use screenshots, mouse and keyboard where controls are not exposed.
- **Reproduce bugs from a known starting point**: save a checkpoint before a test, collect screenshots and command output, then restore it to try again.
Requirements
- A Windows 10 or 11 Pro or Enterprise host with Hyper-V enabled. The release binaries are for x64 Windows.
- An existing Windows VM with a user logged on to the desktop. Sign in manually or configure automatic sign-in after boot; a stored unlock password only unlocks a session that was already signed in.
- Virtual Machine Connection in basic session mode, not enhanced session.
- An MCP client that supports Streamable HTTP, such as Claude Code, Codex or Cursor.
Administrator approval is required to install, update or uninstall HyperHand on the host. Everyday host use does not prompt for UAC; guest applications have their own elevation requirements.
Quick start
1. **Install HyperHand on the host.** Download hyperhand-X.Y.Z-windows-amd64.zip from the latest release, extract both executables to the same folder and open PowerShell in that folder:
Approve the UAC prompt once. HyperHand installs to %ProgramFiles%\HyperHand, and its tray icon appears.
2. **Connect your AI client.** Run the command for your client:
Claude Code:
Codex:
Other clients: add a Streamable HTTP server with the URL http://127.0.0.1:8770/mcp. Start a new client session to load the tools.
3. **Connect your VM.** Start it, log on and switch the guest keyboard to English. Ask the AI: "Install the HyperHand agent in Win10." Replace Win10 with your VM's name. The guest agent starts at every logon from then on.
4. **Try a first task.** Ask the AI:
> In the Win10 VM, open Notepad, type "Hello from HyperHand", save it as hello.txt on the guest desktop and take a screenshot of the result.
The user guide covers optional guest setup, updates and troubleshooting. To check a connection, ask the AI to run vm_doctor for your VM and report the results.
Features
- **Screenshots and UI controls**: inspect the whole desktop or one window, read exposed buttons and fields, and act on them by control reference or image coordinates.