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

# macOS rigs

> Run macOS rigs as VMs on your own Apple silicon Mac, with Lume.

A macOS rig is a macOS VM on your own Mac. It runs on a
[BYOC host](https://docs.amika.dev/guides/byoc.md) with the `lume` runtime, which uses
[Lume](https://github.com/trycua/cua). Use it to build and test software that
needs macOS, such as iOS or macOS apps.

## Requirements

* A Mac with Apple silicon. Intel Macs and Linux can't run macOS rigs.
* About 50 GB of free disk.
* A [BYOC host](https://docs.amika.dev/guides/byoc.md#set-up-a-host) on that Mac.

## Turn on macOS rigs

On a new host, answer yes to macOS VMs when `amika-hostd setup` asks. On a
host that's already set up, run:

```bash theme={null}
amika-hostd capabilities update --enable lume
```

Either way, this:

1. Installs Lume 0.6.1 into `~/.local/bin`, if it's missing. No `sudo`.
2. Turns on the `lume` runtime in the config file.
3. Adds the `macos-coder` preset, which starts the `amika-macos-coder` image.

## Wait for the image

The daemon builds the macOS image in the background when it starts. Nothing
waits for it, but it takes 30 minutes or more:

1. Lume downloads a macOS restore image from Apple (about 20 GB).
2. Lume installs macOS into a base VM, `amika-macos-base`.
3. The daemon copies the base VM and installs Amika's tools into the copy,
   `amika-macos-coder`.
4. The daemon keeps the restore image in `~/.cache/amika-hostd/macos/`. If
   the build fails, or the base VM is deleted later, the next build skips
   the 20 GB download. It also keeps the base VM, so a new image starts from
   it.

Until the image is ready, the host refuses macOS rigs with "Lume has not
finished setting up". Watch the progress in the daemon log:

```bash theme={null}
tail -f ~/.local/state/amika-hostd/log/amika-hostd.log
```

If the build fails, the log says why. The next `amika-hostd up` or
`amika-hostd reload` tries again.

## Create a macOS rig

> [tab] CLI
>
> ```bash theme={null}
> amika rig create --name mac-dev --host my-mac --preset macos-coder
> ```

> [tab] Web UI
>
> 1. Open **Create a rig** at [app.amika.dev](https://app.amika.dev).
> 2. Under **Runs on**, select **Your hosts**.
> 3. Select **MacOS VM**, then select your Mac.
> 4. Click **Create rig**.
>
> The form shows no presets, sizes or snapshots. The rig gets the
> `macos-coder` preset and the host's first macOS size.

> [tab] TypeScript
>
> Pass the host's ID as `hostId`. `amika host get my-mac` prints it.
>
> ```ts theme={null}
> const rig = await client.rigs.create({
>   name: "mac-dev",
>   hostId: "host_123",
>   preset: "macos-coder",
> });
> await rig.wait();
> ```

> [tab] HTTP API
>
> Send the host's ID as `host_id`, and `"preset": "macos-coder"`.
>
> ```bash theme={null}
> curl -X POST https://app.amika.dev/api/v0beta1/rigs \
>   -H "Authorization: Bearer $AMIKA_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"name":"mac-dev","host_id":"host_123","preset":"macos-coder"}'
> ```

Each rig is a copy of the image. The copy takes seconds and almost no disk,
because macOS copies files on write (APFS clones).

## Limits

* **Two running macOS rigs per Mac.** Apple's license allows two macOS VMs at
  a time. A third start is refused with "host is full".
* **The disk is the image's.** A size that asks for less disk than the image
  has is refused.
* **No snapshots.** You can't snapshot a macOS rig.

## Remove macOS rigs

To stop offering macOS rigs, delete the rigs, then run:

```bash theme={null}
amika-hostd capabilities update --disable lume
```

The base VM and the image stay in Lume's storage (`~/.lume`). The restore
image stays in `~/.cache/amika-hostd/macos/`. To delete them,
[uninstall the daemon](https://docs.amika.dev/guides/byoc-manage-hosts.md#uninstall-the-daemon). Type
`remove macos images` and `remove macos restore image` when it asks. Lume
itself stays installed, since other tools can use it.


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