@ricsam/r5d-macos-vm creates and runs a local macOS virtual machine for r5d on Apple silicon. The VM keeps agent work away from your normal macOS account and can be removed when you no longer need it.
The npm package does not contain macOS or a prebuilt VM image. Its signed and notarized native runner downloads the compatible restore image directly from Apple and installs it locally.
Requirements
- An Apple-silicon Mac running macOS 14 or newer
- Node.js 18 or newer
- Internet access to Apple, r5d.dev,
npm.r5d.dev, anddownloads.r5d.dev - Enough free storage for a macOS restore image and VM disk; installation can use tens of gigabytes
Create the VM and connect a worker
1
Install the macOS VM CLI
The CLI comes from r5d.dev’s npm registry, You can also run individual commands without a global install by prefixing them with
npm.r5d.dev:npx --registry https://npm.r5d.dev @ricsam/r5d-macos-vm.2
Check the host
--json for machine-readable diagnostics.3
Create the VM
The default VM is named To choose explicit resources:
r5d-macos. This example also assigns the worker label macos-vm:4
Complete macOS Setup Assistant
The VM opens in its own window. Finish Apple’s Setup Assistant and sign in to the local VM account.
5
Install tools and connect the worker
In the VM, open My Shared Files → r5d Setup and double-click Install r5d.command. The installer adds the development tools and the r5d CLIs, then opens a Terminal window that authorizes the VM and starts its worker.The installer also asks whether to give agents full access to the VM. If you answer yes, quit Terminal when the installer tells you to; the worker window then opens in a new Terminal that has the new permissions.Approve the device code shown in that window in r5d, then select
macos-vm in the conversation. Keep the window and the VM running. The window opens again each time you log in to the VM; if the worker stops, press Return in it to start the worker again. The worker has automatic updates, so it follows r5d releases without a restart.You can also start the worker from any terminal inside the VM:Give agents full access
Agents run every command inside the worker’s Terminal window, as the VM’s account. Answering yes to the installer’s full-access question:- lets that account use
sudowithout a password, so agents can run administrator commands - turns on automatic login, so the worker window comes back after the VM restarts (macOS does not allow this while FileVault is on)
- turns off sleep, the screen saver and the screen lock, so a macOS dialog never waits behind a locked screen
- keeps the login keychain unlocked, so tools such as
gitnever wait on a hidden keychain prompt - opens each Privacy & Security pane in turn for you to switch on Terminal: Full Disk Access, App Management, Developer Tools, Accessibility, Screen & System Audio Recording and Input Monitoring. macOS also asks once whether Terminal may control System Events and Finder.
Start and stop the VM
run is an alias for start.
Update
Update the host-side VM CLI with npm:r5d-macos-vm also passes --auto-update, which turns updates back on at each login if they were turned off from another terminal.
A VM whose worker runs a release from before automatic updates were on by default needs one manual update. When the worker’s ⋯ menu in Settings → Workers offers Update CLIs, run it, then press Ctrl+C in the worker window and start the worker again (press Return in the window, or run r5d-worker start --label macos-vm in a new Terminal window). From then on the worker updates itself.
Credential rotation and rebooting
Updated account credentials apply to newly started commands. Existing commands retain their original environment. Before shutting down the VM, stop its active conversations and commands; a server deployment alone does not require restarting it.Remove a VM
--purge only when you intend to delete it permanently: