Flavio's app supportAll guides · Sign in

← All guides

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.