> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octomerge.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a worker in a macOS VM

> Create an isolated macOS worker on an Apple-silicon Mac with the r5d macOS npm CLI.

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

```bash theme={null}
npm install -g @ricsam/r5d-macos-vm --registry https://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**

```bash theme={null}
r5d-macos-vm doctor
```

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

```bash theme={null}
r5d-macos-vm create \
  --name r5d-macos \
  --worker-label macos-vm
```

To choose explicit resources:

```bash theme={null}
r5d-macos-vm create \
  --name build-mac \
  --worker-label ios-build \
  --cpus 4 \
  --memory-bytes 8589934592 \
  --disk-bytes 85899345920
```

**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](#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](https://docs.octomerge.dev/get-started/add-worker.md#automatic-updates), so it follows r5d releases without a restart.

You can also start the worker from any terminal inside the VM:

```bash theme={null}
r5d-worker start --label macos-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:

```bash theme={null}
"/Volumes/My Shared Files/r5d Setup/grant-agent-access.sh"
```

> [!WARNING]
>
> 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

```bash theme={null}
r5d-macos-vm list
r5d-macos-vm status r5d-macos
r5d-macos-vm start r5d-macos
r5d-macos-vm stop r5d-macos
```

`run` is an alias for `start`.

## Update

Update the host-side VM CLI with npm:

```bash theme={null}
npm install -g @ricsam/r5d-macos-vm@latest --registry https://npm.r5d.dev
```

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

```bash theme={null}
r5d-macos-vm delete r5d-macos --yes
r5d-macos-vm cache prune
npm uninstall -g @ricsam/r5d-macos-vm
```

The default delete operation moves the VM to Trash. Add `--purge` only when you intend to delete it permanently:

```bash theme={null}
r5d-macos-vm delete r5d-macos --yes --purge
```

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.

> [!WARNING]
>
> Using macOS virtual machines is subject to Apple's software license terms. The CLI is intended for eligible local use on Apple-branded hardware.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.