# Vm Lab

Parallels macOS VM lab: GUI automation, Peekaboo, TCC, Ghostty.

- Repository: https://github.com/steipete/agent-scripts (7431 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add steipete/agent-scripts --skill vm-lab -g -a claude-code -y`
Codex: `npx skills add steipete/agent-scripts --skill vm-lab -g -a codex -y`
Cursor: `npx skills add steipete/agent-scripts --skill vm-lab -g -a cursor -y`
Gemini CLI: `npx skills add steipete/agent-scripts --skill vm-lab -g -a gemini-cli -y`

## Description

Parallels macOS VM lab: GUI automation, Peekaboo, TCC, Ghostty.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# VM Lab

Use this when the task needs a clean macOS VM to test GUI automation, TCC prompts, screenshot capture, clicking, typing, performance, or "two-way validation" of Peekaboo-like tools.

Core idea: run the tool under test inside the guest, but verify it from outside the guest with Parallels screenshots and host-side observations. Do not close apps you do not own.

## Safety Rules

- Only task-owned clones are disposable. Preserve source/golden snapshots, recovery VMs, and other tasks' VMs; never reset, revert, or delete their snapshots.
- Never access inherited guest credentials or bypass login/startup security to bootstrap a clone.
- Never print secrets. If `op` is needed, follow the 1Password skill and run it only inside `tmux`.
- Prefer fresh app windows you create yourself: TextEdit, a local HTML test page, or a small test app.
- Limit host writes to task-owned temporary diagnostics and explicitly authorized clone recovery. Never change global Bash/Codex settings for a lab workaround.
- For git repos inside the VM, use HTTPS remotes and normal branch discipline.

## Bootstrap Preflight

Before guest automation, confirm the exact task-owned VM UUID and snapshot provenance; the names below are examples, not permission to operate an existing VM.

- Apple-VZ clone fails to boot: verify the active raw disk's contents, not just clone success or logical size. A sparse linked child alone does not prove a broken chain; `clone --unlink` creates another clone, not an in-place repair.
- Packaging hangs before its first output: inspect the task-owned shell process and heredoc redirection before changing product code or build guards. A system-Bash retry must also pin PATH-resolved child shells, for that invocation only.

Use [Bootstrap diagnostics](references/bootstrap-diagnostics.md) for read-only checks, evidence limits, and narrowly scoped recovery boundaries.

## VM Discovery

List VMs:

```bash
prlctl list --all
```

Get VM status/IP:

The rest: https://github.com/steipete/agent-scripts/blob/HEAD/skills/vm-lab/SKILL.md