How to use VM Peek and testvm
VM Peek and testvm
Set up the bundled testvm CLI, test a Mac app in a separate VM, and inspect agent activity in VM Peek.
Bought VM Peek and testvm? Sign in with the email you bought it with to download the latest version or ask me a question.
On this page
VM Peek shows the Mac test environment your coding agents use. The included testvm command copies builds there and controls them. VM Peek watches the screen and command history, so you can see what happened.
Install the app and CLI
After buying, download the Mac app ZIP from your purchase page, unzip it, and move VM Peek to Applications. The app needs macOS 15 or later. Running a local Tart VM needs an Apple silicon Mac, even though the viewer app also has an Intel build.
Download the source ZIP and open Terminal in the unzipped folder. Install the ready-to-run script:
mkdir -p ~/.local/bin
install -m 755 testvm/testvm ~/.local/bin/testvm.new
mv ~/.local/bin/testvm.new ~/.local/bin/testvm
Make sure ~/.local/bin is on your shell’s PATH. The temporary file and rename avoid overwriting a script while another command is reading it.
Create the test VM
Install Tart, then run the included setup command:
brew install openai/tools/tart
testvm setup
Setup downloads and configures a macOS VM. Allow enough disk space for the image and your test apps. The default VM uses four cores and 8 GB of memory. It runs in the background.
The VM is a separate test Mac. Files, accounts and application data inside it are separate from your normal Mac unless you explicitly copy them.
Test your first build
Build your own app normally. Suppose the build produced dist/Recipe Box.app. Open that build in the VM:
testvm note 'Checking the recipe search'
testvm open 'dist/Recipe Box.app'
testvm shot 'Recipe Box'
testvm ui 'Recipe Box'
open copies the app, replaces its running test copy and waits for a window. shot prints a screenshot path. ui lists controls and their coordinates. Use those current coordinates for testvm click, then testvm type or testvm key as needed.
Run testvm help for command syntax. Install the bundled agent skill from the combined source, or copy its instructions into your agent setup. Tell agents to test in the VM so their clicks do not take over your working desktop.
Watch the session
Open VM Peek’s Live view while a test is running. It shows the VM screen and recent agent sessions. The screen refreshes while the window is visible.
The activity list describes commands in plain language. Select a command to inspect its screenshot, command line and output. Search finds earlier commands. The chat and app timelines help answer which agent installed a build and what it checked.
An overlap warning means multiple chats are using the same test environment. Their clicks go to whichever app has focus there. Let one test finish before another starts.
Logs and connection problems
The command log lives in ~/Library/Logs/testvm. It can contain agent prompts, command output and screenshots. Treat it as project data when backing it up or sharing it.
VM Peek uses the same test connection as testvm. If the screen is unavailable, run a simple testvm operation first and read its error. Check that Tart is installed, setup completed and the VM can start. VM Peek observes the VM; it does not perform the test clicks itself.
Use VM Peek → Check for Updates… to update the app. For the latest CLI or full source, download the source ZIP again from your purchase page.
More examples
VM Peek and testvm is $20, a one-time purchase.