# @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

```bash
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:

```bash
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 a visible executor launcher. The installation operator must provision the private `~/Library/Application Support/r5d/executor.json` and matching manager, workspace, and network configuration. The launcher invokes `r5d-worker executor` with that file; there is no device-pairing endpoint.

Useful commands:

```bash
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.