@ricsam/r5d-macos-vm

r5d-macos-vm creates and runs a local macOS VM for r5d.dev on Apple silicon. The npm package contains the CLI and guest bootstrap scripts, but no Apple software or prebuilt VM image. It downloads a signed and notarized r5d native runner from downloads.r5d.dev; that runner downloads the current compatible macOS restore image directly from Apple and installs it locally.

Requirements

• An Apple-silicon Mac running macOS 14 or newer.
• Node.js 18 or newer.
• Enough free storage for the Apple restore image and the VM disk. The default disk is sparse, but macOS installation can still use tens of gigabytes.
• Internet access to Apple, r5d.dev, npm, and downloads.r5d.dev.

No Xcode installation, Apple Developer account, or prebuilt macOS image is required on the user's Mac.

Quick start

npx @ricsam/r5d-macos-vm doctor
npx @ricsam/r5d-macos-vm create

The default VM is named r5d-macos. To use a different name or size:

r5d-macos-vm create build-mac \
  --cpus 4 \
  --memory-bytes 8589934592 \
  --disk-bytes 85899345920

Complete macOS Setup Assistant in the VM, then double-click /Volumes/My Shared Files/r5d Setup/Install r5d.command. It installs development tools and the r5d CLIs, then opens a Terminal window that authorizes the VM with r5dctl auth login --worker-label <label> and runs r5d-worker start --label <label> --auto-update, so the worker installs each r5d release by itself. A login item opens that window again at each login to the VM. The installer also offers to give agents full access to a VM dedicated to them (bootstrap/grant-agent-access.sh): passwordless sudo, automatic login, no sleep or screen lock, an unlocked login keychain, and the Privacy & Security permissions a person switches on for Terminal.

Useful commands:

r5d-macos-vm list
r5d-macos-vm status build-mac
r5d-macos-vm start build-mac
r5d-macos-vm stop build-mac
r5d-macos-vm delete build-mac --yes          # move the VM to Trash
r5d-macos-vm delete build-mac --yes --purge  # permanently delete it
r5d-macos-vm cache prune                     # remove restore images and old native runners

Add --json for newline-delimited progress events suitable for automation. --state-root <path> and --bootstrap-dir <path> are development/test overrides. Interactive progress updates one terminal line in place. When output is redirected to a file or pipeline, progress is limited to one line per five percent.

Storage and security

• VM bundles: ~/Library/Application Support/r5d/macos-vms/
• Apple restore-image cache: ~/Library/Caches/dev.r5d.macos-vm/restore/
• Versioned native runners: ~/Library/Caches/dev.r5d.macos-vm/runtimes/<package-version>/

Every npm version pins the native archive's exact HTTPS URL, SHA-256, byte length, Apple Team ID, bundle ID, arm64 architecture, and macOS deployment target. Before execution, the CLI uses built-in macOS security tools to verify the checksum, Mach-O metadata, Developer ID signature, exact virtualization-only entitlement set, hardened runtime, stapled notarization ticket, and Gatekeeper's notarization assessment. It does not invoke Xcode or its command-line tools. Downloads and extraction are locked and promoted into the cache atomically.

The package never distributes an IPSW, installed macOS disk, auxiliary storage, hardware model, or machine identifier. Restore images come from Apple and remain in the local cache only when requested or needed for installation.

Updating and removing

Updating the npm package installs a new versioned native runner and does not modify existing VM bundles. The guest's r5d-worker and r5dctl use their normal r5d update flow.

npm uninstall -g @ricsam/r5d-macos-vm removes only the CLI. For complete removal, revoke the worker in r5d.dev, delete or purge each VM, run r5d-macos-vm cache prune, and then uninstall the npm package. Native runtime caches can be removed manually after the CLI is uninstalled; VM bundles are intentionally never removed by npm lifecycle scripts.

Troubleshooting

• Run r5d-macos-vm doctor --json for machine-readable host and Virtualization.framework diagnostics.
• A checksum, signature, Team ID, entitlement, or notarization error is treated as unsafe. Reinstall the npm package and retry; do not bypass the check.
• If an install was interrupted, rerun create with the same name. After acquiring the per-VM lock, the CLI moves incomplete staging data to Trash, rebuilds it from scratch, and reuses the resumable restore-image cache.
• Clipboard sharing is not required to authorize the VM; use the short code or QR code shown in the guest Terminal.
• If the worker stops with pty_native_helper_*, the rest of that line names the file or directory to fix.

Use of macOS virtual machines is subject to Apple's software license terms. This tool is intended for eligible local use on Apple-branded hardware; it does not grant rights to host or relay macOS environments as a service.