macvm
/macvm
Create and operate macOS / Linux / Windows (ARM64) virtual machines on a Mac with the macvm command line — create, start, stop, suspend, run commands in the guest, SSH, port forwarding, snapshots and templates, and drive the guest desktop (UI automation, screenshots). Use this skill whenever a task involves running something in a VM or an isolated guest, testing on another OS, needing a clean Linux / Windows / macOS environment, or mentions macvm or MacVM — even if the user never says "virtual machine" and only says things like "spin up an Ubuntu to try this", "click something in Windows", or
- Author
- macvm-dev ↗
- Repository
- macvm ↗
- Licence
- MIT
- Last repository change
- 13.11.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Create and operate macOS / Linux / Windows (ARM64) virtual machines on a Mac with the macvm command line — create, start, stop, suspend, run commands in the guest, SSH, port forwarding, snapshots and templates, and drive the guest desktop (UI automation, screenshots). Use this skill whenever a task involves running something in a VM or an isolated guest, testing on another OS, needing a clean Linux / Windows / macOS environment, or mentions macvm or MacVM — even if the user never says "virtual machine" and only says things like "spin up an Ubuntu to try this", "click something in Windows", or
Triggers from the description
Original author description
Create and operate macOS / Linux / Windows (ARM64) virtual machines on a Mac with the macvm command line — create, start, stop, suspend, run commands in the guest, SSH, port forwarding, snapshots and templates, and drive the guest desktop (UI automation, screenshots). Use this skill whenever a task involves running something in a VM or an isolated guest, testing on another OS, needing a clean Linux / Windows / macOS environment, or mentions macvm or MacVM — even if the user never says "virtual machine" and only says things like "spin up an Ubuntu to try this", "click something in Windows", or
How it works
- Finding the command
- Always pass --json
- Basic flow
- Confirm before acting
- Read details as needed
SKILL.md preview
---
name: macvm
description: Create and operate macOS / Linux / Windows (ARM64) virtual machines on a Mac with the macvm command line — create, start, stop, suspend, run commands in the guest, SSH, port forwarding, snapshots and templates, and drive the guest desktop (UI automation, screenshots). Use this skill whenever a task involves running something in a VM or an isolated guest, testing on another OS, needing a clean Linux / Windows / macOS environment, or mentions macvm or MacVM — even if the user never says "virtual machine" and only says things like "spin up an Ubuntu to try this", "click something in Windows", or "run it in a sandbox".
---
# macvm
`macvm` is the command line that ships with MacVM. It is built on Apple Virtualization.framework (with an optional QEMU engine) and runs only on Apple silicon Macs.
## Finding the command
Try in order: `macvm` (the App puts a link in `~/.local/bin`), `/usr/local/bin/macvm`, `/Applications/MacVM.app/Contents/Resources/bin/macvm`. If none exists, MacVM is not installed: tell the user to install it, and do not substitute some other virtualization tool on your own.
`macvm <command> --help` is the authority on options; this skill only covers how to use them reliably.
## Always pass `--json`
With `--json`, standard output is exactly one line:
- Success: `{"schemaVersion":1,"result":…}`
- Failure: `{"schemaVersion":1,"error":{"code":"…","message":"…"}}`; some errors carry extra fields in `error` (see `stop` below)
Branch on `error.code` or the exit code; do not parse the human-readable output (its format is not stable). Exceptions: `exec`, `ssh` and `proxy` do not support `--json`, because their input and output belong to the guest command; the exit code of `exec` is the guest command's exit code.
| code | Exit code | Meaning and usual handling |
| --- | --- | --- |
| — (no code) | 1 | Other error; read the message |
| `vm_not_found` | 10 | Wrong name; run `macvm ls --json` first |
| `already_exists` | 11 | A VM or template with that name exists; pick another name or confirm the existing one is meant |
| `already_running` | 12 | Already running; changing configuration requires shutting down first |
| `not_running` | 13 | Run `start` first |
| `invalid_config` | 14 | Invalid argument or configuration; also returned when changing configuration while suspended |
| `unsupported` | 15 | Not supported on this host, engine or guest; also used when the agent is missing or too old — follow the message (usually `macvm agent install <name>`) |
| `entitlement_missing` | 16 | An unsigned macvm was used; use the copy bundled with the App. Also: a VM set to bridged networking in the app was run with `macvm run` (use `macvm start`) or with a macvm outside the App bundle |
| `timeout` | 17 | Timed out waiting; retry with a larger `--timeout` |
| `io` | 18 | File or socket read/write failed |
| `engine` | 19 | The virtualization engine reported an error; in UI automation it also means an element ID is stale |
| `snapshot_not_found` | 20 | Snapshot does not exist |
| `template_not_found` | 21 | Template does not exist |
| `permission_denied` | 22 | The guest has not granted the agent a permission (Accessibility or Screen Recording on macOS); the user must grant it inside the guest |
## Basic flow
```bash
macvm ls --json # result is an array of VMSummary: name, os, state (stopped|running|suspended), cpuCount, memorySize, ipAddress…
macvm start dev --json # start in the background, return once ready
macvm wait dev --json # wait for the agent (or SSH); starts the VM if it is not running
macvm exec dev -- uname -a # run in the guest; starts the VM if it is not running
macvm stop dev --json # graceful shutdown
```
- `stop` waits `--timeout` seconds (default 90) and then fails with `timeout`. In a macOS guest, apps that haven't quit can block the shutdown; the error then lists them in `error.blockingApps` (each with `name`, `pid` and usually `bundleId`). Tell the user which apps are blocking. Quitting an app in the guest can lose its unsaved work, so ask the user before doing it — they can quit it themselves, or with their consent run `macvm exec <vm> -- osascript -e 'quit app id "<bundleId>"'` — then run `stop` again. `stop --force` is the last resort and also needs confirmation.
- Run `ls` first and reuse an existing VM when one fits: creating a new one means downloading an image and installing an OS, which takes minutes to tens of minutes.
- Creating a VM (especially installing macOS, Windows or Ubuntu Desktop) takes a long time; run it in the background and tell the user what you are waiting for.
- The default VM directory holds the user's own VMs. When you create a VM just for testing, ask the user whether to delete it when you are done.
## Confirm before acting
These operations lose data or interrupt something the user is using; confirm with the user before running them: `rm`, `stop --force` (cuts power), `snapshot restore` (overwrites the current disk), `template rm`, `set` on a VM the user already had (changes its configuration), quitting apps in the guest (unsaved work is lost), and shutting down a VM you did not start yourself.
## Read details as needed
| Task | Read |
| --- | --- |
| Create a VM: choose the OS, image, engine, network, shared folders, templates | `references/create.md` |
| Run commands in the guest, SSH, ports, shared folder paths, snapshots and clones | `references/guest.md` |
| Drive the guest desktop: accessibility tree snapshots, clicking, typing, screenshots | `references/ui.md` |
Files in this package (4)
- SKILL.md 6 KB
- references/create.md 3 KB
- references/guest.md 6 KB
- references/ui.md 3 KB
Versions
The database has no other skills named macvm.
Database snapshot: 13.11.2026 · package version f2041a15be21 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100linux-desktop-remote
Control a remote or local Linux X11 desktop over SSH with AT-SPI semantic UI lookup plus xdotool and ImageMagick: locate and click widgets by name (no screenshots needed), take screenshots, type text, manage windows, and launch applications. Use when asked to open apps, click… - 98gcloud-vm
Provision, start, reach and use Google Cloud VMs — for any real-OS work the macOS host and Docker cannot do. Above all: REAL WINDOWS, which is the only way to check that Frizz still runs there now that tmux is gone. Invoke whenever you think "I need a Windows box" or "I need a… - 93ssh-server-ops
Use when Codex needs to bootstrap, diagnose, transfer files, or operate SSH access from Windows, macOS, or Linux to Linux, POSIX, gateway, bastion, or Slurm/HPC targets using the bundled SSH Server Ops toolkit. - 98ssh-remote-desktop
Deploy and use the SSH Remote Desktop Windows helper over SSH to transfer files, launch programs, inspect UIA, take screenshots, operate a Windows desktop, sign in to a Windows 11 local account, and prepare a headless Windows 11 x64 display. Use for remote Windows GUI tasks, not… - 98windows-vm
Create, manage, or connect to a headless Windows 11 VM running in Docker with SSH access. Use when the user wants to spin up, stop, restart, or SSH into a Windows VM. - 100dd-agent-install-macos
Install the Datadog Agent on a macOS machine with the macOS installer, with infrastructure metrics, logs, and APM trace intake on by default, plus optional live processes, APM instrumentation, custom tags, and service management. Use when the user wants to install the Datadog…