Setup: Install macOS from ISO

📘

Known limitation

This guide is applicable only to Intel-based VMs.

For more information, see Apple silicon-based support.

🚧

Quick navigation

Jump to: 1. Get ISO | 2. Create an empty base image | 3. Create and deploy your VM | 4. Connect to the VM via VNC | 5. Format the disk and install the ISO | 6. Create a new base image from the newly installed VM

🚧

Quick command summary

Orka CLIOrka API

orka iso list
orka iso list-remote
orka iso pull -i <CURRENT_NAME> -o <NEW_NAME> -y

orka image generate --image <NAME.img> --size <SIZE> -y
orka vm create -v <NAME> -b <IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> -i <ISO> -y

orka vm status -v <NAME> -y
orka image save -v <VM_ID> -b <IMAGE.img> -y

GET /resources/iso/list
GET /resources/iso/list-remote
POST /resources/iso/pull

POST /resources/image/generate
POST /resources/vm/create
POST /resources/vm/deploy

GET /resources/vm/status/myorkavm
POST /resources/image/save

You can use an ISO to install macOS on a clean VM. On this page, you will learn how to:

• List, pull, and upload ISOs.
• Create a VM with an empty base image and an attached ISO.
• Install macOS from ISO on a bare VM.
• Create a bootable base image from a VM.

1. Get ISO

To use an ISO, it must be available in the local storage of your Orka environment. To add ISOs to the local storage, you can pull them from the remote repo (maintained by MacStadium) or you can upload an ISO yourself.

1. Check what ISOs are available in the local storage of your Orka environment.

orka iso list

curl --location 'http://<ORKA-API-IP>/resources/iso/list' \
--header 'Authorization: Bearer <TOKEN>'

2. If you want to pull an ISO from the remote repo maintained by MacStadium, run the following commands. The pull operation might take a while.

orka iso list-remote

orka iso pull -i <CURRENT_NAME> -o <NEW_NAME> -y

curl --location 'http://<ORKA-API-IP>/resources/iso/list-remote' \
--header 'Authorization: Bearer <TOKEN>'

curl --location 'http://<ORKA-API-IP>/resources/iso/pull' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
	"iso": "<NAME>.iso"
}'

3. If you want to upload an ISO, run the following command. This operation might take a while.

orka iso upload -i <PATH_TO_LOCAL_ISO> -y

curl --location 'http://<ORKA-API-IP>/resources/iso/upload' \
--form 'iso=@"/<PATH>/<TO>/<FILE>"'

The CLI will prompt you to specify a file path to the ISO on your local machine. Provide a fully qualified file path.

2. Create an empty base image

The default base images provided in your Orka environment are bootable disks with macOS installed. To install macOS from ISO, you need an empty disk.

To generate an empty disk of a preferred size (in G for gigabytes or T for terabytes), run the following command. Make sure to specify the .img file extension when prompted to provide a name.

orka image generate --image <NAME>.img --size <SIZE> -y

curl --location 'http://<ORKA-API-IP>/resources/image/generate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
	"file_name": "<NAME>.img",
	"file_size": "<SIZE>"
}'

Make sure that the size of the empty disk meets the installation requirements of the OS on the ISO.

👍

TIP: Forgot to add .img in your file name?

Run the following command and provide the missing file extension.

orka image rename --image <CURRENT_NAME> -o <NEW_NAME>

3. Create and deploy your VM

Create and deploy your VM, using the empty image you generated. Make sure to attach the ISO that you want to use.

orka vm create

OR

orka vm create -v <NAME> -b <IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> -i <ISO> -y

curl --location 'http://<ORKA-API-IP>/resources/vm/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
	"orka_vm_name": "<VM_NAME>",
	"orka_base_image": "<IMAGE_NAME>.img",
	"orka_image": "<VM_NAME>",
	"orka_cpu_core": <CPU_AMOUNT>,
	"vcpu_count": <VCPU_AMOUNT>,
	"iso_image": "<ISO_NAME>.iso"
}'

curl --location 'http://<ORKA-API-IP>/resources/vm/deploy' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
	"orka_vm_name": "<VM_NAME>"
}'

4. Connect to the VM via VNC

Run your preferred VNC client and use the VM's IP and VNC port to connect to the VM.

5. Format the disk and install the ISO

Orka generates unformatted empty storage. To install the OS from the attached ISO, you need to format the disk first.

1. When prompted, select Language and click the arrow to continue.

2. When the Recovery Assistant appears, select DIsk Utility and click Continue.

3. In the left sidebar, select your disk and click Erase.

• If I/O boost is enabled, select Apple Inc. VirtIO Block Media. By default, I/O boost is enabled for macOS Catalina and later.

• If I/O Boost is disabled or the OS version does not support it, select QEMU HARDDISK Media with the largest disk size. I/O boost is available on Mojave 10.14.5 and later.

4. Fill in the required configuration.
   • Set Name: to Macintosh HD.
     This ensures that macOS can auto-boot from that disk.
   • Set Format: to APFS.
   • Set Scheme: to GUID Partition Map.

5. Click Erase and wait for the operation to complete. Click Done.
6. Return to the Recovery screen, select Install macOS (or Reinstall macOS) and click Continue. If prompted, click Continue.

7. Accept the license agreement, select the new drive and click Install.

8. Complete the installation.

📘

Known issue with macOS Ventura

macOS Ventura VMs created from ISO return to the Recovery (ISO install) screen after restart, if you don't manually select to boot macOS from the boot menu.

Workaround: Choose the second option from the boot menu (macOS Installer during the final steps of the setup or Macintosh HD after you have completed the installation) after every restart. If you miss the boot menu and end up at the Recovery screen, restart the VM from the Apple menu in the top left corner.
Once you're done with your current OS configuration, commit the changes or save a new image from the VM. Use the image to create and deploy macOS Ventura VMs.

6. Create a new base image from the newly installed VM

If you want to create a bootable base image that you can use with other VM configurations, you can save the newly installed VM as a new base image.

1. Get the VM ID.

orka vm status -v <NAME> -y

curl --location 'http://<ORKA-API-IP>/resources/vm/status/myorkavm' \
--header 'Authorization: Bearer <TOKEN>'

2. Save the VM as a new base image. The name you specify must be unique.

orka image save -v <VM_ID> -b <IMAGE>.img -y

curl --location 'http://<ORKA-API-IP>/resources/image/save' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
	"orka_vm_name": "<VM_ID>",
	"new_name": "<IMAGE_NAME>.img"
}'

See also

• Orka API Reference: ISOs
• Orka CLI Reference: ISOs