@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. The shared bootstrap opens a visible Terminal, installs Homebrew and the r5d command-line tools, and starts worker enrollment. On another device, visit https://r5d.dev/auth and enter the displayed code, or scan its QR code. The worker starts only after authorization succeeds.

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 for enrollment; use the short code or QR code shown in the guest Terminal.

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.