Index of every page on this site: llms.txt
All skills
Run it yourself

Provision and control a disposable Tart macOS VM, cloned from the shared base image, for clean-install, release, integration, or developer-tool testing. Use for "test in the VM", "Tart", guest clipboard/input problems, or before pulling a macOS image. Keep application-specific assertions in the project's test procedure.

  • 4 files
  • 20.4 KB
  • Updated 5 days ago
  • GitHub
Use this Skill: https://skilld.dev/gh/nielsmadan/agentic-coding/macos-vm

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈83 tokens for metadata: the name and description. ≈1.7k when used: this file. ≈2.2k more on demand in 2 files.

Description uses 4.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈332 characters, or 4.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

macOS VM (Tart)

Instructions

1. Choose the test state

Read the project's docs/tests/ procedure for artifacts, setup, expected results, and cleanup ownership. This skill owns VM transport and interaction; the project owns fixtures, product UI selectors, and assertions.

tart list
memory_pressure | tail -1

Start from the shared base, base-macos-27. The base image reference lists what it contains and which permissions it already grants. Never boot or change a base-* VM, and do not pull an image unless the user asks: an OCI name absent from tart list may download tens of GB. The host runs at most two macOS guests in total, across all sessions. A third fails at start. If two are already running, wait or tell the user. Run one guest per task. Each guest holds its configured memory (8 GB by default); do not start one when the system-wide free percentage is below about 20%. APFS clones share disk blocks with their source and grow only with the guest's writes.

Distinguish a clean base from a prepared, authenticated guest. For repeat tests, shut down the prepared guest before cloning it; retain the original and its login. Record this difference instead of calling the clone a fresh install. Credentials remain private in the VM.

2. Clone and boot

Set base to base-macos-27, or to a prepared guest the user named. Name the clone <project>-<purpose>-<YYYYmmdd-HHMMSS>. Set shared to an absolute staging directory in the workspace.

env TART_NO_AUTO_PRUNE=1 tart clone "$base" "$vm"
tart set "$vm" --memory 8192
tart run --capture-system-keys --dir="shared:$shared:ro" "$vm"

Keep tart run attached in a long-lived terminal/tool session. Use another invocation for commands. Visible mode helps with authentication and permission dialogs. Leave clipboard sharing enabled: do not pass --no-clipboard when the user needs to paste a login link into the guest browser. --capture-system-keys routes shortcuts to the focused guest window.

Add --dir="evidence:$evidence" as a separate writable share when exporting screenshots. Shares mount under /Volumes/My Shared Files/<name>. Stage executables on a read-only share; copy applications into the guest before running them.

3. Establish guest command access

tart exec "$vm" /bin/sh -c 'sw_vers; printf "%s\n" "$HOME"'

Allow boot time and put a bounded timeout around this readiness probe. The prepared Cirrus image includes a guest agent; vanilla images may not. Prefer tart exec over SSH or scp: it needs no SSH credentials and supports stdin with -i. Quote guest shell expressions so the guest, rather than the host, expands $HOME.

tart exec -i "$vm" /usr/bin/osascript - <<'APPLESCRIPT'
tell application "System Events" to get name of every application process
APPLESCRIPT

4. Use the most direct working interface

  1. Use guest CLI commands for installation, files, processes, and diagnostics.
  2. Use an application's API for structured input and observations. For iTerm2, use the terminal helper.
  3. Use guest AppleScript/System Events for native UI and keys, and cliclick for mouse input; see native UI control.
  4. Use visible guest interaction or VNC when Accessibility/Automation is unavailable, or for permission dialogs.

In a clone of the shared base, System Events, cliclick and screencapture work through tart exec with no prompt. Use them rather than compiling or installing your own input helper, which would need its own grants. A tart exec command that hangs usually means a consent dialog is waiting in the guest: take a VNC screenshot before assuming a transport failure. Do not rewrite TCC databases or disable SIP. Grant needed permissions through the guest's normal macOS UI, then repeat the actual operation.

5. Capture evidence and clean up

Read state through the product's interface as well as backend diagnostics. A delivered event does not prove that the visible UI changed. Screenshots must exclude login pages, codes, credentials, and unrelated windows. Inspect them locally before retaining them.

tart exec "$vm" /usr/sbin/screencapture -x "/Volumes/My Shared Files/evidence/desktop.png"

Screen Recording permission varies by image. A black frame is a failed observation, not an empty desktop. Use a file share to keep large image payloads off the command transport.

Sanitize guest names, home paths, and session identifiers before exporting evidence. Preserve identity relationships with consistent placeholders and meaningful terminal-ID prefixes. Never retain cookies, login links, VNC passwords, or account screenshots in the repo.

Quit test processes, then shut down only the disposable guest:

tart exec "$vm" /usr/bin/sudo -n /sbin/shutdown -h now
tart list
tart delete "$vm"

Shutdown may disconnect tart exec and return nonzero; confirm stopped in tart list before deleting. If graceful shutdown is unavailable, use tart stop on that exact disposable guest. Do not delete the base or prepared source. Restore any original guest to its prior running or stopped state. Do not discard an authenticated guest as the first troubleshooting step.

Examples

  • Clean installer test: clone a local base, boot with a read-only artifact share, install the signed release, let the user authenticate, then follow the project's checks.
  • Existing-install upgrade: stop the prepared guest, clone it, stage the version fixture, run the product installer, compare state, and delete only the test clone.
  • CLI inside iTerm2: list sessions with scripts/iterm.py, explicitly select the target ID, submit text, then read the screen. Keep product-specific assertions in the repo.

Troubleshooting

  • Clipboard does not paste: inspect the Tart command for --no-clipboard. Reboot with sharing enabled if necessary, focus the guest browser, and let the user paste there. Never put a login link into command logs or saved data.
  • System Events times out or denies access: inspect guest Automation and Accessibility permissions; use visible input/VNC while resolving them. A transport timeout alone does not establish a macOS permission denial.
  • iTerm2 API returns 401: use the helper's explicit AppleScript cookie/key handshake; verify Enable Python API and the guest approval prompt. Do not print the cookie/key.
  • Guest command channel fails: check tart list and the desktop. Preserve evidence and distinguish transport failure from application failure. Avoid large inline captures.
  • Virtualization or filesystem denial: apply nono-sandbox diagnostics to the failing operation. A footer probe is not proof; do not change grants or try SSH as a bypass.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 9fbe49f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 days ago.

Activeupdated 5 days ago
effort
low

README badge

README badge for nielsmadan/agentic-coding/macos-vm