Spin up isolated macOS or Linux VMs on Apple Silicon for AI agents to safely run code in.
Built on Apple's Virtualization framework, packaged for the way coding agents actually work in 2026.
Why VM4A · 30s demo · Install · Cookbook · Usage · Developer · 中文
Coding agents — Claude Code, Cursor, OpenAI Codex, your own loop — keep needing one thing: a fresh, isolated machine to try things in. VM4A is local-first, runs on your Mac, and is the only tool in this lane that gives you all of:
| 🖥 macOS and Linux guests | Test iOS/macOS app builds, not just pip install |
| 📸 VZ snapshots (macOS 14+) | --save-on-stop / --restore for sub-second try → fail → reset loops |
| 📦 OCI registry push/pull | Distribute pre-baked agent environments via GHCR / Docker Hub / Harbor |
| 🚀 Apple Silicon native | Virtualization.framework, near-native performance, no QEMU emulation |
| 🪟 GUI as a debugger, not the main UI | When an agent run fails, open the snapshot in the app |
macOS guest install flow.
vm4a create --os macOS --image foo.ipswdrives Apple'sVZMacOSInstallerend-to-end (10–20 min). The resulting VM boots into Setup Assistant on first run; complete that once interactively (account + Remote Login → on), then every other vm4a operation —run,exec,cp,fork,reset,pool, the OCI push/pull, the MCP tools — works on the macOS bundle just like on Linux. Pulling a pre-baked macOS bundle from a registry skips Setup Assistant entirely.
VM4A is "VM for Agent" — pronounced "VM-for-A". The CLI is vm4a.
# 1. Pull a pre-baked Python dev image, start it, wait for SSH.
vm4a spawn dev \
--from ghcr.io/everettjf/vm4a-templates/python-dev:latest \
--storage /tmp/vm4a --wait-ssh
# 2. Run code in the guest. JSON output is machine-readable.
vm4a exec /tmp/vm4a/dev --output json -- python3 -c 'print(1+1)'
# → {"exit_code":0,"stdout":"2\n","stderr":"","duration_ms":312,"timed_out":false}
# 3. Per-task pattern: APFS-clone in a second, run a step, throw away.
vm4a fork /tmp/vm4a/dev /tmp/vm4a/task-42 --auto-start --wait-ssh
vm4a exec /tmp/vm4a/task-42 -- bash /work/agent_step.sh golden bundle per-task fork per-task fork
┌───────────┐ fork → ┌───────────┐ ┌───────────┐
│ /dev │ ──────► │ /task-42 │ │ /task-43 │ ...
└───────────┘ └───────────┘ └───────────┘
pull once APFS clonefile, ~1s throwaway after exec
| Surface | Use when | Entry point |
|---|---|---|
| 🐚 CLI | Shell scripts, CI, manual exploration | vm4a <command> |
| 🤖 MCP | Claude Code, Cursor, Cline, any MCP-aware AI | vm4a mcp (stdio JSON-RPC) |
| 🌐 HTTP + Python SDK | Custom Python harnesses, language bindings | vm4a serve + pip install vm4a |
All three share the same agent primitives: spawn, exec, cp, fork, reset, list, ip, stop. Pick whichever surface fits the consumer.
brew tap everettjf/tap
brew install vm4a # CLI
brew install --cask vm4a # GUI (drag-install)Build from source
git clone https://github.com/everettjf/vm4a.git
cd vm4a
swift build -c release
codesign --force --sign - \
--entitlements Sources/VM4ACLI/VM4ACLI.entitlements \
./.build/release/vm4a
cp ./.build/release/vm4a /usr/local/bin/
⚠️ The CLI must be codesigned withSources/VM4ACLI/VM4ACLI.entitlements. Bridged networking and Rosetta paths silently fail without it.
Requirements: Apple Silicon Mac (M1+), macOS 13+ (snapshots need macOS 14+).
Latest — v2.4 · warm-pool runtime + network sandbox
vm4a pool serve / acquire / release— keep N idle VMs warm, hand one out in milliseconds.--network none | nat | bridged | host— explicit isolation level per VM.
Full release history
| Phase | Goal | Status |
|---|---|---|
| v1.1 | VM lifecycle + OCI distribution + snapshots | ✅ shipped |
| v2.0 P0 | Agent CLI primitives (spawn/exec/cp/fork/reset) |
✅ shipped |
| v2.0 P1 | MCP server (vm4a mcp) — Claude Code / Cursor / Cline |
✅ shipped |
| v2.1 | HTTP API (vm4a serve) + Python SDK |
✅ shipped |
| v2.2 | Curated OCI templates (ubuntu-base, python-dev, xcode-dev) |
✅ shipped (macOS template needs one-time Setup Assistant click-through) |
| v2.3 | Time Machine viewer (vm4a-sessions SwiftUI app + vm4a session CLI) |
✅ shipped (standalone; main-app integration pending) |
| v2.4 | Warm-pool runtime + --network sandbox |
✅ shipped |
See CHANGELOG.md for per-version detail.
| If you want to… | Read |
|---|---|
| Get hands-on with end-to-end recipes | Cookbook.md — macOS / Linux guests, agent loops, sessions, pools, MCP/HTTP setup |
| See full scenarios (golden image + parallel forks, etc.) | UseCases/ |
| Look up a flag or JSON shape | Usage.md — per-command reference |
| Hack on VM4A itself | Developer.md — repo layout, architecture, build, tests, release flow |
| See what changed | CHANGELOG.md |
| Use the Python SDK | sdk/python/README.md |
| Pull / rebuild a template | templates/README.md |
Using Claude Code? The repo ships a local skill at
.claude/skills/vm4a-cli/SKILL.mdthat teaches Claude how to drive every subcommand.
MIT. See LICENSE.