Skip to content
Back to search

vamp-mcp

Run AI computer-use agents in VMs on your own hardware.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wayfarer6--vamp-mcp/badge.svg)](/listings/wayfarer6--vamp-mcp)

HTML

<a href="/listings/wayfarer6--vamp-mcp"><img src="/api/listings/wayfarer6--vamp-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Use MCP without VS Code

With Node.js 22 or later, install the VAMP bundle in an MCPB-compatible client. Add the separate Vault bundle if you use it. On Windows, the bundle requires an already elevated host. For manual downloads, verify the file against the release’s `SHA256SUMS`. [VAMP MCP](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.wayfarer6%2Fvamp-mcp/versions/latest) · [Vault MCP](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.wayfarer6%2Fvamp-mcp-vault/versions/latest) · [GitHub Releases](https://github.com/wayfarer6/vamp-mcp/releases)

On Apple Silicon, install the Mac registry entries. Call `utm_candidates` to check VAMP and `vault_status` to check the optional Vault and its KeePassXC and VeraCrypt CLIs. [VAMP MCP · macOS](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.wayfarer6%2Fvamp-mcp-macos/versions/latest) · [VAMP Vault · macOS](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.wayfarer6%2Fvamp-mcp-vault-macos/versions/latest)

On first local startup, VAMP prepares Packer and Vagrant. Check `host_cli_status` for the paths and set `VAMP_AUTO_DOWNLOAD=0` to opt out. Vault prepares VeraCrypt through WinGet on Windows, native Installer on macOS (including FUSE-T when required), and verified portable downloads on supported Linux hosts. Vault also prepares a missing KeePassXC CLI through WinGet on Windows, a verified app bundle on macOS, or a verified AppImage on supported Linux hosts. Check `vault_status` for the result. Set `VAULT_AUTO_DOWNLOAD=0` to opt out.

2. Use the VS Code extensions

1. Download both VSIX files from [GitHub Releases](https://github.com/wayfarer6/vamp-mcp/releases). Use **Extensions: Install from VSIX** separately for each file. Install VAMP MCP Tools first, wait for it to finish, then install VAMP Vault and reload VS Code. 2. Open the **VAMP** activity bar. Use **Open VM Manager** for VMs, **Open Containers** for the Podman inventory and desktop actions, and **RPA Library** for reviewed workflows. Manage credentials in **VAMP Vault** separately. 3. For WSL, follow the [manual setup guide](vscode-extension/CONTAINERS_WSL.md). See [Container desktops](docs/CONTAINER_DESKTOP.md) for rootless Podman, noVNC, capture, and limitations.

For Windows host PowerShell policy and separate Hyper-V/CIM permission checks, see the [Windows host guide](docs/INSTALL.md#windows-powershell-host).

After installing, check the VAMP entries with `code --list-extensions --show-versions`. The versions should match the two downloaded file names. If a bundled Marketplace version appears, reinstall the corresponding VSIX separately.

Record, replay, and repair a task

1. Set up the guest and use the same guest resolution for recording and replay. The Windows VirtualBox setup uses 1920×1080 after initialization. 2. In **RPA Library**, search for a reviewed workflow first. To create a new one, record the task in the guest, review the captured actions, and remove sensitive input before saving. For a standalone Robot Framework package, use the [PyAutoGUI conversion guide](docs/RECORDING_CONVERSION.md). 3. Replay the reviewed workflow on the selected guest. Check the expected screen or output file before treating it as successful. 4. If the screen changed, inspect the affected area and propose a targeted repair. Test the repair in a separate VirtualBox guest, then review the verified revision before using it again. See the [recording and repair workflow](docs/WORKFLOWS.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 412 lines · 3 findings marked
  1. <p align="center">
  2. <img src="vscode-extension/icon.png" width="140" height="140" alt="VAMP Logo">
  3. </p>
  4. <h1 align="center">VAMP · Virtual Agent Machine Platform</h1>
  5. <p align="center">
  6. <strong>Run AI computer-use agents in VMs on your own hardware.</strong>
  7. </p>
  8. <p align="center">
  9. <a href="https://github.com/wayfarer6/vamp-mcp/actions/workflows/ci.yml"><img src="https://github.com/wayfarer6/vamp-mcp/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI checks on main"></a>
  10. <a href="https://github.com/wayfarer6/vamp-mcp/releases"><img src="https://img.shields.io/github/v/release/wayfarer6/vamp-mcp?style=flat-square&color=8A2BE2" alt="Latest Release"></a>
  11. <a href="https://marketplace.visualstudio.com/items?itemName=wayfarer6.vamp-mcp-tools"><img src="https://img.shields.io/badge/VS%20Code-vamp--mcp-007ACC?style=flat-square&logo=visual-studio-code&logoColor=white" alt="VS Code Extension"></a>
  12. <a href="https://wayfarer6.github.io/vamp-script-hub/"><img src="https://img.shields.io/badge/Community-Script%20Hub-blueviolet?style=flat-square" alt="Script Hub"></a>
  13. <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg?style=flat-square" alt="License: MIT"></a>
  14. </p>
  15. <p align="center">
  16. <a href="README.md">English</a> · <a href="README.ko.md">한국어</a> · <a href="docs/USER_GUIDE.md">User Guide</a> · <a href="https://wayfarer6.github.io/vamp-script-hub/">Script Hub</a> · <a href="docs/ROADMAP.md">Roadmap</a>
  17. </p>
  18. ---
  19. ## One-line MCP install
  20. With Codex CLI and Node.js 22 or later installed, run the command for your computer. On Apple Silicon, use native arm64 Node.js.
  21. **Windows PowerShell**
  22. ```powershell
  23. irm https://raw.githubusercontent.com/wayfarer6/vamp-mcp/6c31f9b5a60b26124f52948d099295865a586eeb/scripts/windows/install-mcp.ps1 | iex
  24. ```
  25. **Ubuntu Desktop, Ubuntu Server, or Ubuntu in WSL 2 (Bash)**
  26. Open Bash on your Ubuntu PC or in an SSH session to your Ubuntu server. For WSL 2, open the Ubuntu terminal in Windows. In that shell, check that `node --version` reports v22 or later and `codex --version` finds the Linux CLI. The installer also uses curl and Python 3.
  27. ```bash
  28. (set -o pipefail; curl -fsSL https://raw.githubusercontent.com/wayfarer6/vamp-mcp/6c31f9b5a60b26124f52948d099295865a586eeb/scripts/linux/install-mcp.sh | bash)
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 40 on GitHub
  29. ```
  30. Run the installer as the user who runs Codex. It writes to `~/.vamp/mcp/vamp-mcp-linux/0.3.24/`. Paste the printed prompt into Codex on that same Ubuntu host and account to register the server and verify it with `rpa_search`. An empty list is a successful connection. On WSL, this registration belongs to Ubuntu and is separate from Windows.
  31. **Apple Silicon Mac terminal**
  32. ```bash
  33. curl -fsSL https://raw.githubusercontent.com/wayfarer6/vamp-mcp/6c31f9b5a60b26124f52948d099295865a586eeb/scripts/macos/install-mcp.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 48 on GitHub
  34. ```
  35. Paste the English prompt printed by the installer into Codex. On Windows, open Codex as administrator. If this is the first registration, reopen Codex and paste the same prompt again to verify the connection.
  36. ## Reuse part of a GUI recording
  37. A pair of Python comments marks an editable step. Choose **Block between step comments** and enter its ID to keep the step attached to the code when lines move.
  38. ```python
  39. # vamp-step: open-menu
  40. p.press('f2')
  41. # vamp-end: open-menu
  42. ```
  43. For an existing recording, ask the agent to preview step comments with `rpa_revision(action="annotate")`. The preview includes the source and updated step plan. Applying it creates a revision that needs review.
  44. In **RPA Library**, select a Python recording and choose **Create GUI RPA → Reusable steps → Add step**. Give the step a name, select its first and last source lines, and enter visible text for its starting and finished screens. After review, a second RPA can select **Step from a reviewed revision** and append its own local steps. VAMP pins the original Git commit and saves the combined actions in the new RPA.
  45. ```mermaid
  46. flowchart LR
  47. A["Reviewed menu step at a fixed revision"] --> B["Check Inventory menu"]
  48. B --> C["Warehouse report step"]
  49. B --> D["Factory report step"]
  50. D --> E{"Production balance visible?"}
  51. E -->|Yes| F["Record checkpoint"]
  52. E -->|No| G["Stop and inspect effects"]
  53. G --> H["Edit report step and review"]
  54. H --> I["Recheck entry and resume report"]
  55. ```
  56. Select the script in the source preview and click **Edit** to open the file in VS Code. For a saved skill, use **Edit details and steps** to review and save the new revision. When a run stops, inspect the reported step and any changes already made. To resume in MCP, provide the reviewed `expected_commit`, `from_step`, and `effects_reconciled: true` with the usual target, inputs and confirmation. VAMP checks that step’s entry screen before sending input. [English demo](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.18/reusable-steps-en.mp4) · [Captions](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.18/reusable-steps-en.srt)
  57. After annotating a shared step, existing workflows still reference their original commit. Review the new shared revision, then update the pin in the workflows that should adopt it. [Watch the preview, review and pin update](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.19/review-and-repin-en.mp4) · [Captions](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.19/review-and-repin-en.srt)
  58. ## See VAMP in 30 seconds
  59. **Try a warehouse close.** Ask “Close the warehouse for the month.” Codex finds a reviewed GUI recording and LibreOffice Calc writes an Excel workbook for four synthetic SKUs. The demo checks all 24 formulas and the closing value after saving. [English video](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.16/warehouse-close-workflow-en.mp4) · [Example and setup](examples/warehouse-close/README.md) · [Finished XLSX](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.16/warehouse-close-2026-12.xlsx)
  60. **Record a task yourself.** Open the guest recorder, enable button crops for later YOLO review, and choose **Save Python**. A writable recording share makes the source visible on the host. Review and save it in RPA Library for agent reuse. Manual demonstrations do not generate fallback code. A failed verified click stops replay. [Watch the guide](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.17/manual-recorder-en.mp4) · [Captions](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.17/manual-recorder-en.srt)
  61. From the VAMP VS Code extension, open a VirtualBox guest and verify that its Debian desktop is live.
  62. [![Demo preview: open a VirtualBox guest by name and verify its live Debian desktop in VAMP](docs/media/vamp-demo-preview-en.gif)](https://raw.githubusercontent.com/wayfarer6/vamp-mcp/main/docs/media/vamp-result-en.mp4)
  63. [▶ Watch the English demo (0:30)](https://raw.githubusercontent.com/wayfarer6/vamp-mcp/main/docs/media/vamp-result-en.mp4)
  64. [English and Korean video guides](docs/VM_LAB.md) include the 30-second demo, installation and AI connection, architecture, and a hands-on VM lab.
  65. See which Linux KVM calls were recorded automatically, how to read the two outcomes, and what a Vault credential lookup proves. [Audit log video · English, 1:51](docs/media/vamp-audit-log-en.mp4)
  66. Find a saved run by script and agent, then open its queued and verified events in VS Code. [SQLite audit walkthrough · English, 0:47](docs/media/vamp-sqlite-audit-en.mp4) · [GUI and CLI library design proposal](docs/WORKFLOW_LIBRARY_DESIGN.md)
  67. ## Build the automation today. Tomorrow, just change the order number.
  68. Today, work with a large model to export an order from your ERP to CSV. Save the steps along with a check that the new file contains the requested order number. Tomorrow, ask a smaller model to **“export order 1042 the same way.”** It finds the workflow in the RPA Library and passes the new order number through MCP. VAMP runs the saved steps on your device and checks the CSV.
  69. **You can share a reviewed workflow with a colleague.** Export a specific version of a GUI RPA as a source ZIP. Your colleague can inspect the code and inputs, then reuse it in a compatible environment on their device with their own order number. Leave passwords and real order data out of the package. Reusing the steps can lower model costs on repeat runs because a large model no longer has to plan each click or command anew.
  70. VAMP 0.3.21 uses Apple Neural Engine and CPU through Core ML for YOLO and PaddleOCR on Apple Silicon. Run the vision setup with native Python 3.12 after upgrading. [Mac setup](docs/MACOS_UTM_SETUP.md#run-yolo-and-paddleocr-on-the-neural-engine)
  71. Import a saved GUI RPA ZIP or unpacked export folder with `vamp-mcp rpa install ./workflow.zip`. Import a shared Python or Playwright workflow JSON from a terminal with `vamp-mcp rpa install ./workflow.json` (add `--dry-run` to preview), and inspect the catalog with `vamp-mcp rpa list`. Import neither runs the workflow nor installs dependencies. Set up the VM workspace and review the exact revision in VS Code before running it. [Catalog and revision options](docs/CLI_WORKFLOWS.md#import-a-workflow-without-vs-code)
  72. VAMP 0.3.20 streams CLI workflow artifacts over SSH. Upgrade the host and guest worker together for files larger than 1 MiB. [Guest worker setup](docs/CLI_WORKFLOWS.md)
  73. **VAMP 0.3.15 includes saved Python and Playwright workflows alongside GUI recordings.** Open the RPA Library to import an order-export example, review its code for your VM and run it with a different order number. The CLI worker supports Linux guests on VirtualBox, KVM and Hyper-V. [GUI RPA guide](docs/WORKFLOWS.md) · [CLI setup and order example](docs/CLI_WORKFLOWS.md)
  74. ```mermaid
  75. flowchart TD
  76. A["Define steps and success checks with a large model"] --> G["GUI RPA · available today"]
  77. A --> C["Python or Playwright workflow"]
  78. G --> L["Review and save a version on your device"]
  79. C --> L
  80. L --> M["Your small model calls it with its ID and inputs"]
  81. L --> P["Share a reviewed version"]
  82. P --> T["Colleague reviews and sets it up on their device"]
  83. T --> N["Their small model calls it with their own inputs"]
  84. M --> R["VAMP runs and verifies the task on each device"]
  85. N --> R
  86. R --> DB["SQLite audit log for this profile"]
  87. V["Vault credential use and volume mounts"] --> DB
  88. DB --> Q["MCP search by time, script or agent"]
  89. DB --> U["VS Code audit log and run details"]
  90. ```
  91. If an AI provider raises its API prices or discontinues its service, you can keep using the saved workflow by maintaining its execution environment and connecting another small model that supports MCP. You decide how to edit the script and whom to share it with.
  92. **Even if you switch models, the workflows you’ve built stay on your device.**
  93. ## Which agent ran a script?
  94. **VAMP: Open Audit Log** shows the latest matching event per run over the last 24 hours. Combine a local time range, script name or UUID, agent ID and activity type. Select a row to open its timeline.
  95. Ask your AI to “Find runs of the order export script by `orders-agent` between 9 and 10 this morning and show their verification results.” It can use `audit_search` and `audit_run_details`. For a stable ID across restarts, set `VAMP_AGENT_ID=orders-agent` on that agent’s dedicated MCP server. Otherwise the server automatically assigns a process-session ID. [SQLite location, profiles and query examples](docs/AUDIT_LOG.md)
  96. ### Verify a recorded click
  97. When saving a recording, enter the text on each button or its specific YOLO class. Replay checks the guest before each press. The default minimum score is 90%. In **RPA Library → Recorded click verification**, set 1–100% or turn verification off. You can also tell your agent “Use 95% for this run only.” [Recognition, fallback and MCP examples](docs/RECORDED_CLICKS.md)
  98. ## Ask your AI to install VAMP
  99. In Claude Code or Codex with terminal access, paste the request for your operating system.
  100. ```text
  101. https://github.com/wayfarer6/vamp-mcp
  102. Install VAMP MCP on my Windows PC from the latest official release. Verify the package
  103. checksum, connect it to this AI client, and list my VMs using the backend I use on
  104. this PC (VirtualBox or Hyper-V) to confirm it works.
  105. ```
  106. ```text
  107. https://github.com/wayfarer6/vamp-mcp
  108. Install VAMP MCP on my Linux PC from the latest official release. Verify the package
  109. checksum, connect it to this AI client, and list my VMs using the backend I use on
  110. this PC (VirtualBox or KVM) to confirm it works.
  111. ```
  112. **macOS (Apple Silicon)**
  113. ```text
  114. https://github.com/wayfarer6/vamp-mcp
  115. Install VAMP MCP on my Apple Silicon Mac and connect it to this AI client.
  116. Check that Node.js 22 or later and UTM are installed. Use the official MCP Registry
  117. entry io.github.wayfarer6/vamp-mcp-macos to find the current darwin-arm64.mcpb
  118. and verify its SHA-256. If this client needs a stdio command, use Node.js and
  119. the entry point in the extracted bundle’s manifest. Then call utm_candidates
  120. and show me the VM names and power states, or confirm that the inventory is empty.
  121. ```
  122. [English first-run guide: web-chat prompts, install commands, screenshots, and the order CSV demo](docs/FIRST_RUN.en.md) · [English walkthrough video (3:02)](https://github.com/wayfarer6/vamp-mcp/raw/refs/heads/main/docs/media/vamp-first-run-en.mp4) · [한국어 가이드](docs/FIRST_RUN.ko.md)
  123. Next video · [VAMP MCP architecture in Korean (3:04)](https://github.com/wayfarer6/vamp-mcp/raw/refs/heads/main/docs/media/vamp-architecture-ko.mp4). Follow a request from the AI client to the guest and compare VirtualBox, KVM, and Hyper-V.
  124. **English architecture video** · [VirtualBox, KVM and Hyper-V architecture (1:53)](https://github.com/wayfarer6/vamp-mcp/raw/refs/heads/main/docs/media/vamp-architecture-en.mp4).
  125. ## How to use
  126. **Supported hosts:** Windows, Linux, and macOS on Apple Silicon. On Apple Silicon, UTM is the only local VM backend. The Mac VSIX and MCPB packages support Debian 13 arm64 guests, rootless Podman in the guest, and remote SSH targets. [macOS setup guide and videos](docs/MACOS_UTM_SETUP.md)
  127. **Hyper-V on Windows.** Enable Hyper-V and select **VM Manager → Connection → Virtualization platform → Hyper-V**. VAMP supports VM creation and lifecycle management, the external VMConnect console, and file transfer with supported Windows guests. The Robot Framework console workflow can start the VM and open VMConnect. It is distinct from embedded screenshot and input control and from saved GUI device replay. [Hyper-V setup and Robot console workflow](backends/hyperv/README.md)
  128. **Windows MCP requirement.** VAMP and VAMP Vault MCP servers require Windows administrator privileges. The `vamp-mcp` CLI can request UAC to start the server in a separate elevated process while the MCP client stays open. For a direct server command, start it from an administrator terminal. To use the MCP servers provided by the VS Code extensions, start VS Code with **Run as administrator**. Direct server startup exits when Windows has not granted administrator privileges.
  129. Contributions are welcome. See the [contribution guide](CONTRIBUTING.md) and [AI contributor instructions](AGENTS.md).
  130. Run GUI automation inside a guest while you keep using your host desktop. With saved RPA, local replay can check the screen and output files without sending frames to a model. An external agent can receive screen data if its client requests it during exploration or targeted fallback. Vault-managed secrets can be delivered through the approved guest connection.
  131. For SSH-based remote GUI automation, see the [WSL2 remote MCP worker guide](docs/WSL2_REMOTE_WORKER.md).
  132. WSL2 remote MCP guides ([English](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.13/17-VAMP-WSL-Remote-MCP-Guide-QHD-en.mp4) · [한국어](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.13/17-VAMP-WSL-Remote-MCP-Guide-QHD-ko.mp4)).
  133. Watch the [VAMP overview in English](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.11/14-VAMP-Overview-en.mp4) for the architecture and first steps. The [English installation guide](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.11/11-VAMP-Install-Guide-X-en.mp4) starts on the Windows host with MCP package and VSIX installation and follows both routes through Debian startup in VirtualBox.
  134. - VAMP MCP and Vault in an AI client ([English](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.12/15-VAMP-MCP-Vault-AI-Walkthrough-QHD-en.mp4) · [Korean](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.12/15-VAMP-MCP-Vault-AI-Walkthrough-QHD-ko.mp4))
  135. - Create and replay a manual RPA ([English](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.12/16-VAMP-Manual-RPA-Guide-QHD-en.mp4) · [Korean](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.12/16-VAMP-Manual-RPA-Guide-QHD-ko.mp4))
  136. Watch the [Windows VirtualBox Notepad verification in English](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.10/04-Windows-VirtualBox-Notepad-QHD-en.mp4) or [Korean](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.10/04-Windows-VirtualBox-Notepad-QHD-ko.mp4). The Robot Framework run opens Notepad and checks the `Windows (CRLF)` status bar in a 1920×1080 guest.
  137. - Podman · Debian / VirtualBox setup video ([Korean](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.10/03-Podman-VirtualBox-QHD-ko.mp4) · [English](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.10/03-Podman-VirtualBox-QHD-en.mp4))
  138. - [Robot Framework source for the Korean and English editions](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.10/VAMP-setup-editions-robot-source.zip)
  139. - [Robot Framework sources and QA results](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.10/VAMP-v0.3.10-demo-source-and-qa.zip)
  140. - [Record in VirtualBox and add the Python script to the VS Code RPA Library](docs/USER_GUIDE.md#2-make-a-vm-recording-appear-in-the-library)
  141. - [Generate a standalone Robot Framework package for a VirtualBox, SPICE, or VNC guest](docs/RECORDING_CONVERSION.md#b-게스트-안에서-기록한-pyautogui-코드-변환) using the [Windows Notepad sample recording](examples/notepad_recording.py).
  142. - [Standalone Demo ERP for replay and repair](https://github.com/wayfarer6/vamp-demo-erp)
  143. - ERP replay verification in VirtualBox ([English](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.10/05-VirtualBox-ERP-Replay-QHD-en.mp4) · [Korean](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.10/05-VirtualBox-ERP-Replay-QHD-ko.mp4))
  144. - Scratch repair verification in VirtualBox ([English](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.10/06-VirtualBox-Scratch-Repair-QHD-en.mp4) · [Korean](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.10/06-VirtualBox-Scratch-Repair-QHD-ko.mp4))
  145. - Codex ERP rehearsal, edited from actual guest captures and the reviewed source ([English](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.11/07-ERP-Rehearsal-QHD-en.mp4) · [Korean](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.11/07-ERP-Rehearsal-QHD-ko.mp4))
  146. - [Codex ERP Robot Framework evidence](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.11/vamp-erp-codex-scratch-evidence.zip) includes the verification suite, reports, and sample CSVs.
  147. - Installed MCP replay after the ERP layout change ([English labels](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.11/08-Installed-MCP-ERP-v2-QHD-en.mp4) · [Korean labels](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.11/08-Installed-MCP-ERP-v2-QHD-ko.mp4)).
  148. - Five-step synthetic modal recovery demo ([English](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.11/09-Modal-Recovery-QHD-en.mp4) · [Korean](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.11/09-Modal-Recovery-QHD-ko.mp4)).
  149. - Continuous Codex ERP showcase with captions, from authoring to the installed MCP rerun ([English](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.11/10-ERP-Continuous-QHD-en.mp4) · [Korean](https://github.com/wayfarer6/vamp-mcp/releases/download/v0.3.11/10-ERP-Continuous-QHD-ko.mp4)).
  150. - [ERP run results and comparison method](docs/ROADMAP.md#observed-erp-run)
  151. - [Run a reviewed VirtualBox scenario and get its CSV in MCP chat](docs/USER_GUIDE.md#get-an-erp-csv-in-chat) (current source build)
  152. - [Export a decrypted copy of a file from a mounted VeraCrypt container with Vault MCP or VS Code](vscode-vault-extension/README.md#export-a-file-from-a-mounted-container) (current source build)
  153. ## 💡 Why VAMP?
  154. When you export an ERP order every day, the order number changes but the steps often stay the same. Keep the reviewed workflow and its outcome check on your own machine. On the next run, give an MCP-capable model the new order number. GUI replay checks buttons on the guest screen. CLI workflows run their scripts inside a bound Linux guest. Reusing the steps can reduce repeated vision API calls and lets colleagues run the same workflow with their own inputs.
  155. ---
  156. ## ⚖️ How VAMP Compares
  157. | Metric | Screen-driven CUA | Fixed recorded RPA | VAMP saved RPA |
  158. | --- | --- | --- | --- |
  159. | Vision token cost | Provider usage depends on screenshot calls | No provider calls during fixed replay | Local replay and verification use no provider vision tokens. AI-assisted repair is measured separately. |
  160. | Execution latency | Includes screen-driven model calls | Includes scripted inputs and waits | Includes guest inputs, waits, and configured local checks |
  161. | After a layout change | Can inspect the new screen before acting | Requires explicit starting-screen and outcome checks to detect a mismatch | Can stop before input on a configured starting-screen mismatch and hand off for targeted repair |
  162. | Windows VirtualBox ERP check | Elapsed time | Verified outcome |
  163. | --- | ---: | --- |
  164. | Saved replay on the original layout | 35.97 s | 17 actions and a fresh CSV with all three expected orders |
  165. | Saved replay after scratch verification and review | 54.44 s | 30 actions and a fresh CSV with the expected SHA-256 |
  166. | Robot Framework scenario across both layouts | 239.05 s | Two matching CSVs and zero inputs from the stale replay |
  167. In a separate matched comparison with three runs per method and layout, VAMP saved replay verified all three v1 CSVs and stopped all three v2 runs before sending input. Fixed keyboard replay produced three incorrect v2 CSVs, and screen-driven CUA verified all six CSVs across both layouts. [Median timings and evidence](docs/ROADMAP.md#matched-erp-comparison)
  168. ---
  169. ## ⚡ Core Architecture & Highlights
  170. ### Guest control and VM management
  171. VirtualBox, KVM and Hyper-V provide VM lifecycle operations. Saved GUI device replay (`rpa_run_saved`) supports VirtualBox and KVM with local VNC. On Hyper-V, open the guest console in VMConnect directly or with the Robot console workflow. Python and Playwright CLI workflows have been validated in Linux guests on all three backends. The runner sends the reviewed version over SSH and runs it in rootless Podman inside the bound guest. [CLI guest setup and examples](docs/CLI_WORKFLOWS.md)
  172. ### Screen verification and Vault
  173. OCR and YOLO workers on the replay host analyze guest frames. VAMP Vault is a separate MCP server. For managed Windows mounts, it checks approval and the KeePassXC entry’s binding to the volume file, then sends the stored key to the WSL VeraCrypt CLI over stdin. After initial setup and Vault unlock, subsequent approved mounts can reuse the key. [Screen verification](docs/RECORDED_CLICKS.md) · [Vault setup](vscode-vault-extension/README.md)
  174. ### 📦 Guest bootstrapping
  175. VirtualBox fetches post-install resources over its build NAT. Hyper-V Windows uses the selected switch's host IPv4, while Hyper-V Debian reads offline answer media and uses a static network profile after installation. QEMU's default build NAT reaches the host at `10.0.2.2`, independently of the deployed libvirt network. [VM MCP setup and troubleshooting](docs/VM_MCP.md)
  176. For a Debian golden image on Hyper-V, prepare a dedicated internal switch with WinNAT and reserve a static guest address before starting the build. If an older image build stalled at Default Switch DHCP or network preseed, start a fresh build with the offline answer ISO. Keep the golden export separate from the live VM disk. [Debian Hyper-V setup and recovery](backends/packer/debian-hyperv/README.md)
  177. ---
  178. ## 🚀 Quick Start
  179. ### 1. Use MCP without VS Code
  180. With Node.js 22 or later, install the VAMP bundle in an MCPB-compatible client. Add the separate Vault bundle if you use it. On Windows, the bundle requires an already elevated host. For manual downloads, verify the file against the release’s `SHA256SUMS`. [VAMP MCP](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.wayfarer6%2Fvamp-mcp/versions/latest) · [Vault MCP](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.wayfarer6%2Fvamp-mcp-vault/versions/latest) · [GitHub Releases](https://github.com/wayfarer6/vamp-mcp/releases)
  181. On Apple Silicon, install the Mac registry entries. Call `utm_candidates` to check VAMP and `vault_status` to check the optional Vault and its KeePassXC and VeraCrypt CLIs. [VAMP MCP · macOS](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.wayfarer6%2Fvamp-mcp-macos/versions/latest) · [VAMP Vault · macOS](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.wayfarer6%2Fvamp-mcp-vault-macos/versions/latest)
  182. On first local startup, VAMP prepares Packer and Vagrant. Check `host_cli_status` for the paths and set `VAMP_AUTO_DOWNLOAD=0` to opt out. Vault prepares VeraCrypt through WinGet on Windows, native Installer on macOS (including FUSE-T when required), and verified portable downloads on supported Linux hosts. Vault also prepares a missing KeePassXC CLI through WinGet on Windows, a verified app bundle on macOS, or a verified AppImage on supported Linux hosts. Check `vault_status` for the result. Set `VAULT_AUTO_DOWNLOAD=0` to opt out.
  183. ### 2. Use the VS Code extensions
  184. 1. Download both VSIX files from [GitHub Releases](https://github.com/wayfarer6/vamp-mcp/releases). Use **Extensions: Install from VSIX** separately for each file. Install VAMP MCP Tools first, wait for it to finish, then install VAMP Vault and reload VS Code.
  185. 2. Open the **VAMP** activity bar. Use **Open VM Manager** for VMs, **Open Containers** for the Podman inventory and desktop actions, and **RPA Library** for reviewed workflows. Manage credentials in **VAMP Vault** separately.
  186. 3. For WSL, follow the [manual setup guide](vscode-extension/CONTAINERS_WSL.md). See [Container desktops](docs/CONTAINER_DESKTOP.md) for rootless Podman, noVNC, capture, and limitations.
  187. For Windows host PowerShell policy and separate Hyper-V/CIM permission checks, see the [Windows host guide](docs/INSTALL.md#windows-powershell-host).
  188. After installing, check the VAMP entries with `code --list-extensions --show-versions`. The versions should match the two downloaded file names. If a bundled Marketplace version appears, reinstall the corresponding VSIX separately.
  189. ### Record, replay, and repair a task
  190. 1. Set up the guest and use the same guest resolution for recording and replay. The Windows VirtualBox setup uses 1920×1080 after initialization.
  191. 2. In **RPA Library**, search for a reviewed workflow first. To create a new one, record the task in the guest, review the captured actions, and remove sensitive input before saving. For a standalone Robot Framework package, use the [PyAutoGUI conversion guide](docs/RECORDING_CONVERSION.md).
  192. 3. Replay the reviewed workflow on the selected guest. Check the expected screen or output file before treating it as successful.
  193. 4. If the screen changed, inspect the affected area and propose a targeted repair. Test the repair in a separate VirtualBox guest, then review the verified revision before using it again. See the [recording and repair workflow](docs/WORKFLOWS.md).
  194. For Windows replay on VirtualBox or KVM with a local VNC display that may encounter a guest UAC prompt, enable `pause_on_uac`. The recording and guest display must both be 1920×1080. VAMP checks the guest screen with local OCR and stops for operator review. To continue the same run after approval in the guest console, also set `uac_wait_seconds` and a unique `uac_resume_text` that appears in the expected app. See the [guest UAC replay workflow](docs/WORKFLOWS.md#guest-uac-replay).
  195. ---
  196. ## 🏗️ Architecture Overview
  197. ```mermaid
  198. flowchart TD
  199. subgraph Host ["Host machine"]
  200. Agent["AI agent / MCP client"]
  201. MCP["VAMP MCP (vamp-mcp)"]
  202. subgraph VaultService ["VAMP Vault MCP (vamp-mcp-vault)"]
  203. Vault["Vault tools · user approval"]
  204. DB["KeePassXC KDBX · credentials and volume owner agent IDs"]
  205. VC["VeraCrypt"]
  206. Vault --> DB
  207. Vault -->|Approved Windows mount| WSL["WSL VeraCrypt CLI"]
  208. WSL --> VC
  209. Vault --> VC
  210. end
  211. HTTP["Postinstall Script Server :8421"]
  212. RPA["Robot Framework / Python RPA runner"]
  213. Vision["Local YOLO / OCR workers"]
  214. Desktop["Desktop adapter"]
  215. Agent <-->|MCP Stdio Protocol| MCP
  216. Agent <-->|MCP stdio · tools and receipts| Vault
  217. MCP --> HTTP
  218. UI["VS Code · RPA Library"]
  219. Catalog["Reviewed workflows and click settings"]
  220. CLI["CLI runner over SSH"]
  221. Audit["Profile-scoped SQLite audit log"]
  222. MCP --> Catalog
  223. UI --> Catalog
  224. Catalog --> RPA
  225. Catalog --> CLI
  226. RPA --> Audit
  227. CLI --> Audit
  228. Vault --> Audit
  229. Audit --> Query["MCP audit queries and VS Code audit panel"]
  230. RPA -->|Recorded press with verification enabled| Guard{"One target above threshold and stable after pointer move?"}
  231. Guard -->|Yes| Desktop
  232. Guard -->|Blocked| Audit
  233. RPA -->|Keyboard or explicitly unchecked press| Desktop
  234. Desktop -->|Captured frames| RPA
  235. RPA -->|Selected images| Vision
  236. Vision -->|Detections and text| RPA
  237. end
  238. subgraph Infrastructure ["Virtualization Abstraction Layer"]
  239. Packer["Packer (Golden Image Provisioning)"]
  240. Vagrant["Vagrant & DesktopAdapter"]
  241. MCP --> Packer
  242. MCP --> Vagrant
  243. Packer -->|Golden Images| Vagrant
  244. Vagrant -->|VirtualBox / KVM / Hyper-V| VM
  245. end
  246. VM["Isolated VM desktop"]
  247. Container["Isolated desktop container"]
  248. CLI --> GuestJob["Linux guest · rootless Podman · script and outcome check"]
  249. Disk["Assigned VeraCrypt volume"]
  250. VC --> Disk
  251. Disk -->|Secondary disk| VM
  252. Disk -->|Scoped workspace| Container
  253. Vault -->|Approved credential to configured receiver| VM
  254. Vault -->|Approved credential to configured receiver| Container
  255. Desktop <-->|Console capture and input| VM
  256. Desktop <-->|Managed RFB capture and input| Container
  257. ```
  258. Robot Framework and Python run on the controller host, alongside the local YOLO
  259. and OCR workers. The desktop adapter captures the target's screen and sends
  260. keyboard and mouse events, as a person would through a VM console. With a
  261. remote VM, the remote hypervisor host handles console capture and input over
  262. SSH while the controller can analyze the returned frames locally. Supported
  263. operations depend on the desktop backend.
  264. The MCP client calls VAMP MCP for desktop control and calls VAMP Vault MCP
  265. separately for credentials and encrypted volumes. After user approval,
  266. `vault_deliver_credential` sends a value directly to the configured receiver
  267. and returns a delivery receipt over MCP.
  268. ---
  269. ### When the screen changes between checking and clicking (TOCTOU)
  270. An ERP’s **Save** button can be correctly recognized, then covered by a tooltip as the pointer moves. A list refresh can also put a different order at the same coordinates. This gap between observing state (**time of check**) and acting on it (**time of use**) creates a TOCTOU race. A 99% recognition score describes the first frame. The interface can still change before the press. [TOCTOU definition](https://cwe.mitre.org/data/definitions/367.html)
  271. 1. **Identify the target on the first frame.** Require one matching reviewed OCR label or specific YOLO class, a score at or above the configured minimum (90% by default), and a location consistent with the recording.
  272. 2. **Move the pointer and capture again.** Check the guest geometry and compare pixels around the target and click point. Press only if the region is stable. Repeat the check for each press in a multi-click action.
  273. 3. **Hold the click when the target changes.** A missing target, low score or changed region gets one fresh attempt. A second failure stops later input. Duplicate matches stop immediately. Explicit coordinate-only replay skips this visual check.
  274. The final capture and input delivery are separate operations. Identical-looking buttons can also refer to different records. Give the workflow an independent outcome check, such as verifying that the newly exported CSV contains the requested order ID. [Click guard implementation](backends/library/click_guard.py) · [Proposed hover handling](docs/HOVER_TARGETS.md)
  275. ### Where the code lives
  276. | Component | Source |
  277. | --- | --- |
  278. | Recording and conversion | [vamp-recorder.py](guest_setup/recorder/vamp-recorder.py) · [recording_converter.py](recording_converter.py) |
  279. | GUI replay and click checks | [replay.py](backends/library/replay.py) · [click_guard.py](backends/library/click_guard.py) |
  280. | CLI catalog and runs | [cli-catalog.cjs](backends/library/cli-catalog.cjs) · [cli-runs.cjs](backends/library/cli-runs.cjs) |
  281. | Audit storage and UI | [audit.cjs](backends/common/audit.cjs) · [audit-panel.cjs](backends/common/audit-panel.cjs) |
  282. | Vault MCP and mounting | [server.mjs](vscode-vault-extension/backends/vault/server.mjs) · [vault_cli.mjs](vscode-vault-extension/src/vault_cli.mjs) |
  283. | VS Code extensions and MCP distribution | [vscode-extension](vscode-extension) · [registry](registry) |
  284. ## 🌐 Community Script Hub
  285. Don't reinvent the wheel. Browse pre-built, community-verified RPA packages on the **[VAMP Script Hub](https://wayfarer6.github.io/vamp-script-hub/)**:
  286. - Portal logins (Naver, Google, GitHub, Slack)
  287. - Enterprise PDF document generation
  288. - File extraction and scheduled status reporting
  289. ---
  290. ## 🔒 Responsible Use & Security
  291. VAMP is built for research, productivity, and secure local automation.
  292. - **User approval**: Require explicit confirmation for sensitive actions.
  293. - **Isolated Sandbox**: Use sandboxed credentials and test environments. You remain responsible for all operations executed inside guest VMs.
  294. - **Open Source**: Licensed under the [MIT License](LICENSE). Third-party components retain their respective licenses (see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.