AutoPilot
So, what is AutoPilot? Are we talking about an Airbus A320? Nope, just some random GitHub project on the internet. Regardless, here's the rundown.
AutoPilot is a script developed by me - Coopydood - to automate the creation of an executable QEMU script file. However, it doesn't just automate it, it also personalises it based on your preferences.
The way it works is by asking you - the user - a series of questions about your preferences for the virtual machine. This includes things like the virtual CPU cores, allocated RAM, target OS, etc. Then, AutoPilot uses this information to generate a fully-customised script file, derived from a pre-made base script - with all your preferences.
The generated script file is immediately valid and can be run instantly after AutoPilot completes - which in most cases is under 3 minutes - depending on what you choose to customise. This makes it super easy to get a basic macOS VM up and running with zero user tinkering, all while catering to personal preferences.
With the intro out of the way, I'll now go into more detail about each AutoPilot stage, including acceptable values and how to enter them.
This really is as simple as it sounds. You can choose what you want the file name of the config script to be. This can be an alphanumeric string with no special characters except _ and -.
| Default | Accepted | Examples |
|---|---|---|
| boot.sh | [string].sh | macOS.sh macOS-1015.sh ultimate_kvm.sh |
This setting only really has one definitive use right now - virtual network adapter model auto selection. Other than that, it is purely cosmetic at this time. It's still recommended to set this value properly in case future functionality and features depend on it.
If defining a custom value, only a 4-digit value for macOS 10.XX releases, or a 2-digit value for macOS 11 or later is accepted. Do NOT include any subversions (i.e. 10.13.6, 10.15.7, etc.).
In project versions v0.8.6 and later, this value is also now used to add a boot entry to the main menu for easy access. Again, this is purely cosmetic but something to consider.
| Default | Accepted | Examples |
|---|---|---|
| 1015 | 10XX (10.XX) |
1013 1014 |
| XX (>=11) |
11 12 |
Like any other virtual machine, the guest needs virtual cores to work with. As a general rule, use no more than 80% of your host's total cores. For example, if your host has 10 cores, you shouldn't use any more than 8 virtual cores. That's all I can recommend here - use your own judgment and scale to your hardware appropriately.
| Default | Accepted | Examples |
|---|---|---|
| 2 | [number] | 4 6 8 |
Similar to the previous step, your guest needs virtual threads to work with.
THIS VALUE IS A MULTIPLIER. This is calculated as virtual cores ✕ virtual threads.
For example, if you wanted a total of 4 virtual cores and 8 virtual threads, you would input 2 here. (4 ✕ [2] = 8)
If this confuses you - and I don't blame you, I've confused myself - then leave this value as it is.
| Default | Accepted | Examples |
|---|---|---|
| 2 | [number] | 1 2 |
This sets the model of the virtual CPU, and subsequently what the guest OS recognizes it as.
THIS SHOULD NOT BE CHANGED UNLESS YOU KNOW WHAT IT MEANS! Refer to the official QEMU documentation on CPU models for a comprehensive list of acceptable values.
If you know your host CPU model is supported natively by macOS (i.e. Intel Core i3, i5, i7, i9) or at least a similar variant of a supported model (such as the i9-10900K being similar to Apple's i9-10910), you can expose the real model to the guest using the host value. It might do something. Use at your own risk.
| Default | Accepted | Examples |
|---|---|---|
| Penryn | [cpu_model] | Broadwell IvyLake |
| host |
This lets you change the feature set of the virtual CPU. If you're a nerdy nerd nerd who nerds then you might find benefit in tinkering with this, but otherwise:
Don't change this unless you know what you're doing.
| Default | Accepted | Examples |
|---|---|---|
| +ssse3,+sse4.2,+popcnt,+avx,+aes,+xsave,+xsaveopt,check | +[arg] | +kvm |
| +[arg1],+[arg2] ... | +avx,+kvm,+ssse3 |
This one is very similar to the virtual CPU cores option in that it should be scaled relative to your host's hardware. macOS is surprisingly lenient when it comes to lesser RAM amounts, so you don't need to overdo it.
My only recommendation would be: [total host RAM] − [host idle RAM usage] − 1GB >= total virtual RAM
Example: If your host has 16GB total RAM, your host uses 4GB of RAM when idle, don't use any more than 11GB of RAM for the virtual machine. ([16GB] − [4GB] − 1GB = 11GB)
| Default | Accepted | Examples |
|---|---|---|
| 4G | [number]G | 2G 8G 16G |
You should think carefully about this one as it might be hard to change later. This is the capacity of your primary virtual hard drive that will be used for your macOS installation. Keep in mind macOS uses upwards of 40GB for the system, so you should base your total on how much you think you'll need.
If you're just testing the project, you can leave it as is. If you plan on using the virtual machine long-term, perhaps make it a bit bigger to give yourself room.
NOTE: This is a dynamically-growing disk. The virtual hard disk file will grow as you use it. The full capacity is NOT used on the host's storage upon creation. If you've ever used VMware's virtual disks, it's the same as that. Please also note that the actual virtual capacity of the hard disk may be slightly larger than the value you specify.
| Default | Accepted | Examples |
|---|---|---|
| 80G | [number]G | 60G 120G 256G |
This one is a bit more picky. macOS has a limited number of network drivers due to the limited hardware configurations that natively run macOS, therefore you need to pick a model with driver support.
Based on your target OS you chose earlier, the default option will auto-select the best model for your macOS version.
You can still override this if you'd like, but for most people, whatever is auto-selected will be fine.
| Default | Accepted | Examples |
|---|---|---|
| e1000-82545em | [adapter_model] | e1000m vmxnet3 |
| vmxnet3 |
The virtual network adapter needs a virtual MAC address to identify it.
The default is fine unless you intend on using features such as iMessage and FaceTime, as these services require specific MAC address values.
In this case, you should use your own custom one, or you can even have the script generate a random compatible one for you. I'd recommend the latter to make it more unique, at the risk of being perhaps a bit less reliable.
| Default | Accepted | Examples |
|---|---|---|
| 00:16:cb:00:21:09 | XX:XX:XX:XX:XX:XX | 00:16:cb:00:48:02 00:16:ca:00:27:09 00:16:cr:00:87:33 |
To install macOS, you'll need an image of the macOS Recovery.
The script can automatically download a recovery image of a macOS version of your choosing, or you can use one you already have. If you are using a custom image, it should be in the *.img format. You can drag a file onto the terminal window, or place a file called BaseSystem.img in the root of the project directory to have it be detected automatically. If it is in the *.dmg format - this is okay - the script will automatically detect this and convert it for you during the configuration process.
You can also choose to skip this step, but this is not recommended.
| Default | Accepted | Examples |
|---|---|---|
| BaseSystem.img | [file_name].img | BaseSystem.img macOSRecovery.img |
| [file_name].dmg | BaseSystem.dmg InstallESD.dmg |
You'll now get a chance to see your choices displayed in the form of a summary screen. An example of this screen can be found below:
From here, you can confirm and continue, go back and change your settings, start over, or exit entirely.
The process checklist is displayed upon confirming your preferences, in the form of a traffic light system.
| Red | Yellow | Green |
|---|---|---|
| Not yet started | In progress | Complete |
If a sub-operation is required, this will be indicated by a dropdown arrow underneath the current parent operation.
Written and maintained by Coopydood.
You can contribute to documentation, too!