Skip to main content
@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, and downloads.r5d.dev
  • Enough free storage for a macOS restore image and VM disk; installation can use tens of gigabytes
You do not need Xcode, an Apple Developer account, or a prebuilt macOS image on the host Mac.

Create the VM and connect a worker

1

Install the macOS VM CLI

The CLI comes from r5d.dev’s npm registry, npm.r5d.dev:
You can also run individual commands without a global install by prefixing them with npx --registry https://npm.r5d.dev @ricsam/r5d-macos-vm.
2

Check the host

Add --json for machine-readable diagnostics.
3

Create the VM

The default VM is named r5d-macos. This example also assigns the worker label macos-vm:
To choose explicit resources:
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 sudo without 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 git never 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.
Only a person can switch those permissions on, so the installer opens each pane and waits. If Terminal is missing from a list, click + and choose Applications → Utilities → Terminal. If macOS offers to quit Terminal, choose Later: the permissions take effect when you quit Terminal at the end of setup. System Integrity Protection stays on. To set this up later, or again, run the same step from a Terminal in the VM, then quit and reopen Terminal:
Full access lets agents read and change everything in the VM. Use it only for a VM dedicated to r5d agents, and do not sign the VM in to your Apple Account, iCloud or personal browser accounts.

Start and stop the VM

run is an alias for start.

Update

Update the host-side VM CLI with npm:
This installs a new versioned native runner without modifying existing VM bundles. Inside the guest, the worker updates itself: it downloads each r5d release in the background and switches to it without closing the window. The worker window of a VM set up with a current 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

The default delete operation moves the VM to Trash. Add --purge only when you intend to delete it permanently:
Before removing a VM, revoke its worker credential under Settings → CLI & API → Authorized devices. To replace a VM, create the new one with the same worker label. Once the old VM’s worker is offline, the new VM takes over the label when it connects, and the old VM’s worker credential is revoked.
Using macOS virtual machines is subject to Apple’s software license terms. The CLI is intended for eligible local use on Apple-branded hardware.