Agent-Skills.md

Agent Skills: UTM VM Automation (macOS)

Control UTM virtual machines on macOS programmatically — create and configure VMs via AppleScript, manage lifecycle with utmctl, run commands and transfer files in guests, and set up Windows 11 ARM for headless automation (SSH, not the guest agent). Use whenever the user mentions UTM, utmctl, VMs on Apple Silicon, creating/cloning/scripting a virtual machine on a Mac, or wants to run commands inside a local Windows or Linux VM — even if they don't name UTM explicitly.

UncategorizedID: connorads/dotfiles/utm

Repository

connorads/dotfiles
connorads
142

Install this agent skill to your local

pnpm dlx add-skill https://github.com/connorads/dotfiles/tree/HEAD/skills/utm

Skill Files

Browse the full folder contents for utm.

Download Skill

Loading file tree…

skills/utm/SKILL.md

Skill Metadata

Name
utm
Description
Control UTM virtual machines on macOS programmatically — create and configure VMs via AppleScript, manage lifecycle with utmctl, run commands and transfer files in guests, and set up Windows 11 ARM for headless automation (SSH, not the guest agent). Use whenever the user mentions UTM, utmctl, VMs on Apple Silicon, creating/cloning/scripting a virtual machine on a Mac, or wants to run commands inside a local Windows or Linux VM — even if they don't name UTM explicitly.

UTM VM Automation (macOS)

UTM wraps QEMU and Apple's Virtualization.framework. There are two automation surfaces, and they are not equivalent:

  • utmctl — bundled CLI. Lifecycle, guest exec/files/IP, clone, USB. It cannot create, import, export, or configure VMs.
  • AppleScript (via osascript) — strict superset: everything utmctl does, plus creating VMs, editing hardware config, and keyboard/mouse input injection.

Rule of thumb: lifecycle and guest ops → utmctl; creation and configuration → AppleScript. Both drive UTM.app over Apple Events (the app auto-launches; there is no true daemon mode).

UTMCTL=/Applications/UTM.app/Contents/MacOS/utmctl   # not on PATH by default

Task routing

| Task | Tool | Read | |---|---|---| | Start/stop/status/clone/delete, exec in guest, push/pull files, get IP, USB | utmctl | references/utmctl.md | | Create a VM, attach an ISO, change CPU/RAM/disk/network, port forwards, serial, input injection | AppleScript | references/applescript.md | | Windows 11 on Apple Silicon: get the ISO, install, drivers, enable SSH/RDP, run PowerShell from the host | both | references/windows.md |

Everyday commands

$UTMCTL list                          # UUID / Status / Name
$UTMCTL start "MyVM"                  # name (exact) or UUID; resumes if suspended
$UTMCTL status "MyVM"
$UTMCTL stop "MyVM"                   # default is --force (power-off); --request asks guest
$UTMCTL clone "template" --name "worker-1"
$UTMCTL ip-address "MyVM" | head -1   # needs guest agent (see matrix below)
$UTMCTL exec "MyVM" --cmd uname --cmd -a            # needs guest agent
echo hi | $UTMCTL file push "MyVM" /tmp/hi          # stdin → guest file
$UTMCTL file pull "MyVM" /etc/hostname              # guest file → stdout

VMs are identified by UUID or exact, complete name — no partial matching.

Guest agent support matrix — read before promising exec

utmctl exec, file, ip-address (and the AppleScript Guest Suite) require a QEMU guest agent running inside the guest. Whether that's possible depends on the guest/backend combination:

| Guest + backend | Agent works? | Automation path | |---|---|---| | Linux on QEMU | ✓ apt/dnf/apk install qemu-guest-agent | utmctl exec or SSH | | Windows x86_64 on QEMU | ✓ via UTM guest tools ISO | utmctl exec or SSH | | Windows ARM64 on QEMU (the normal case on Apple Silicon) | ◑ partial — guest tools ship the x64 qemu-ga (runs emulated): ip-address+file work, AppleScript execute works; utmctl exec returns no stdout. No native ARM64 agent (#5134) | AppleScript Guest Suite, or SSH over the shared IP / port forward — see windows.md | | Any guest on Apple VZ backend | unreliable; no input injection or USB either | SSH |

Prefer the QEMU backend when creating VMs for automation. For Windows ARM, don't burn time trying to make the agent work — set up OpenSSH Server in the guest (reachable on the shared-network IP, or pin a port forward). See windows.md for the full path, including the gotchas below that cost hours.

Three Windows-ARM traps that look like "it's hung" but aren't fixable by waiting (all in windows.md):

  • A >4 GB Win11 24H2 ISO won't boot — hangs at the firmware "Start boot option" screen. Repack the installer onto a FAT32 disk image with a split WIM.
  • virtio-gpu-pci display → "Display output is not active" black screen the moment Windows boots. Use virtio-ramfb-gl (no Windows driver needed).
  • A new scripted disk defaults to VirtIO, which Windows Setup can't see. Use NVMe for the system disk.

Gotchas that waste hours

  • Automation (TCC) permission: the first AppleScript/utmctl call from a new parent app (Terminal, an agent harness) triggers a macOS consent prompt, or fails with -1743 if previously denied. Grant under System Settings → Privacy & Security → Automation → calling app → UTM. The grant is per calling binary; there's no supported headless pre-seed — trigger it once interactively.
  • Config is cached: UTM reads each VM's config.plist once at app launch. Editing the plist on disk while UTM runs does nothing. Use AppleScript update configuration (VM must be stopped), or quit UTM → edit → relaunch. Some fields (e.g. drive ImageType CD-vs-Disk) aren't in the AppleScript dictionary at all → plist edit is the only way (windows.md).
  • Diagnosing boot/firmware issues: set QEMU.DebugLog true in config.plist to dump the exact QEMU launch line (how drives are presented, display device) to Data/debug.log. Far faster than guessing — see windows.md.
  • Headless = no display device: there's no headless flag. Remove the displays entry from the VM config (or omit it at creation) and use SSH or a serial port; --hide only hides the UTM window.
  • Clones share a MAC → same DHCP lease/IP. After clone, blank the MAC via AppleScript so UTM regenerates it (snippet in applescript.md).
  • delete has no confirmation and erases the VM's disks. Confirm with the user before deleting, and prefer --disposable starts (changes discarded on shutdown) for throwaway runs.
  • ping never works from guests (libslirp limitation). Don't gate "is networking up" on ping; use a TCP check (curl, Test-NetConnection).
  • Generated AppleScript must be plain ASCII — the ¬ line-continuation char breaks under some locales. Use single-line records or variables.

Verifying an automation worked

utmctl status reflects the VM process, not guest readiness. After start, poll for the thing you actually need: the SSH port accepting connections (nc -z localhost 2222), the agent responding (utmctl exec ... --cmd true), or ip-address returning a value. Boot can take 30–90s; poll with a timeout rather than sleeping a fixed amount.