Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Here, you will find guides on virtualizing macOS, whether that be in a virtual machine, or in a docker container.
View the child-pages for guides on how to setup your own macOS Virtual Machine. We have guides in this GitBook, as well as external guides for specific environments & deployments.
How to enable iMessage after successfully creating an unofficial Mac device
iServices are 99% likely to not run on your unofficial Mac until you successfully spoof the required items to disguise your VM as a real Mac.
If you made your macOS install using OpenCore, follow their guide to enable iServices.
If you made your macOS inside VMWare, here is how you can enable iServices:
This guide is tailored to work on Catalina only. We recommend using Catalina initially and upgrading to Big Sur later because Apple changed how iMessage activation worked in Big Sur.
AMD USERS PLEASE READ
If you followed an AMD guide that required you to change your VMX file so that the VM will boot, you will need to use the model number that the guide used, along with other modifications to the VMX.
****Our guides suggest using MacBookPro14,3
- use this in GenSMBIOS.
The board-id
for MacBookPro14,3
is Mac-551B86E5744E2388
.
You should also use smbios.reflectHost = "FALSE"
instead of TRUE
.
If you would like to use a lower macOS version than Catalina, you will need to use a different model number than MacPro7,1
in step 1 of the guide. This is because that model initially launched with Catalina, so it does not support lower macOS versions. A good model to try that supports High Sierra and higher is iMacPro1,1
.
Follow the OpenCore guide linked above, but only complete the following sections (make sure to save all information from these sections for later use):
Using GenSMBIOS
You will want to use the model number MacPro7,1
. Verify your serial numbers using the Apple Check Coverage Page. You have got a good serial number when the page highlights the entry box in red and says Please enter a valid serial number.. As long as it was correctly copied from GenSMBIOS you should be good to go.
Choose a Mac Address
Derive the corresponding ROM Value
Open up a Notepad window, and type the following information (you will need this later): (AMD USERS PLEASE MAKE SURE TO READ THE ORANGE NOTE ABOVE)\
Fully close your VM and VMware. Nothing VMware related (besides this guide of course) should be running.
Open File Explorer, click Documents, open the folder named Virtual Machines, open the folder with the name of your VM, and find your .vmx file (VMware virtual machine configuration). Open it with Notepad.
Scroll to the line board-id.reflectHost = "FALSE"
and replace FALSE
with TRUE
.
Find the line firmware = "efi"
and paste everything from the other Notepad window right below this.
Find the line ethernet0.addressType = "generated"
and replace generated
with static
.
Find the line ethernet0.generatedAddress = "xx:xx:xx:xx:xx:xx"
and replace the entire line with ethernet0.Address = "<YOUR CHOSEN MAC ADDRESS>"
Find the line ethernet0.generatedAddressOffset = "0"
and replace the entire line with ethernet0.checkMACAddress = "false"
.\
Save the .vmx file inside Notepad, boot it up, and try signing into your Apple ID from within the iMessage app. If all went well, you will be able to sign in and send messages.
You cannot sign into iMessage at this time ... contact Apple Support and provide the code below. This issue can be one of two things:
Go to System Preferences and go in iCloud, make sure you are logged in - if yes, proceed to the below:
You will need to do what the popup says and call Apple Support.
You need to just say something like I just got this Mac from <online reselling store in your country> and I can't sign in and it gives me a customer code
Sometimes it takes a couple calls because the support person doesn't know what the customer code is
It helps to have photos of the customer code
Once you've got someone who knows what they're doing, it's a 5 minute process - they enter something server side, then you restart your Mac, and it works
Run the following in terminal:
Reboot once done.
This document will guide you on how to setup a macOS virtual machine on your Windows operating system. This guide has a lot of steps, but I promise it's not hard. It's mainly to provide all the context and information to make the setup easy to follow. I've also broken the steps down into multiple sections in order to make it easier to understand.
Make sure that your PC has Virtualization enabled in the BIOS. If you do not know if you have virtualization enabled, open Task Manager's Performance
tab:
If virtualization is disabled, you need to boot into your PC's BIOS and enable it. Now, enabling it will be different per-vendor, however, here are 2 YouTube videos that may help:
The first step in setting up a virtual machine is getting an image that is compatible with our virtualization software, in this case, VMWare. To do this, we will use OpenCore. The following instructions are a shortened form of the full OpenCore Install Guide:
https://dortania.github.io/OpenCore-Install-Guide/installer-guide/windows-install.html
Note: This method is preferred over downloading an existing ISO from the internet because you never know when the integrity of an ISO from the internet might be compromised.
You should have Python installed: https://www.python.org/downloads/
Download the latest release of OpenCore.
Download Link: https://github.com/acidanthera/OpenCorePkg/releases
Choose the zip
file labeled with RELEASE
.
Extract the OpenCore ZIP file, and open the extracted folder.
Navigate into Utilities\macrecovery
.
Holding Shift
on your keyboard, right-click your explorer window and select Open PowerShell window here
.
Run the python command corresponding to the macOS version you want to download, found in the OpenCore Install Guide.
Running the command will download the BaseSystem.dmg
image from Apple's servers
macOS Ventura
If you'd like to download macOS Ventura, use the command below:
This is not recommended for inexperienced users!
Next, cut/copy the BaseSystem.dmg
file (generated in the macrecovery
folder), to your user profile's Documents
folder
Now that you have the BaseSystem.dmg
file, we will now need to convert it into a format that VMWare can understand and load. In order to do that, we need to use yet another open-source tool called QEMU
. Follow the steps below to learn how to use it.
This is a short guide to show you how to install QEMU
, an open-source tool for working with disk images.
Download QEMU
for Windows.
Download Link: https://qemu.weilnetz.de/w64/
You will see a bunch of folders with years on them. Ignore those. Download the qemu-w64-setup-XXXXXXXX.exe
installer.
Run the installer once the download completes.
If you get a Windows SmartScreen alert, allow the installer to Run Anyways
.
If you get an error during installation saying a file cannot be written, just click the Retry
button in the prompt.
The installer will install files to C:\Program Files\qemu
(Optional). You may want to add the C:\Program Files\qemu
path to your Windows System Environment Variables
This is optional because I will be using the full path to qemu-img
in the rest of the guide.
If you are non-technical or a beginner, I would skip this step.
Now that we've installed QEMU
, we need to use it to convert the BaseSystem.dmg
to a VMWare .vmdk
disk image.
Open Explorer
and navigate into your Documents
folder (where your BaseSystem.dmg
is located).
Holding Shift
on your keyboard, right-click your explorer window and select Open PowerShell window here
.
Run the following command to use QEMU
to convert the image to a .vmdk
.
& "C:\Program Files\qemu\qemu-img.exe" convert -O vmdk -o compat6 BaseSystem.dmg recovery.vmdk
You will now have a recovery.vmdk
file in your Documents
folder that you can use with VMWare.
In order for you to even be able to load a macOS system into VMWare, you will need to use a third-party program called Auto-Unlocker
to patch your VMWare installation.
You should have either VMWare Workstation Player (free), or VMWare Workstation Pro (paid) installed
VMWare Workstation Player (free): https://www.vmware.com/products/workstation-player.html (VMWare Workstation Player 16 download)
VMWare Workstation Pro (paid): https://www.vmware.com/products/workstation-pro.html
Download Auto-Unlocker
.
Extract the downloaded zip
file.
Run the Unlocker.exe
file.
This will bring up a GUI to patch your VMWare installation
The app will attempt to auto-fill the install locations. However, if they are empty, please locate and select your VMWare installation folder.
Click the Patch
button
Once the patching is complete, you may close the Unlocker app.
Download Unlocker
.
Extract the downloaded zip
file.
Run the win-install.cmd
file as an Administrator
This section will detail how to create the base virtual machine using the recovery disk we created earlier.
Pre-requisites
You should have either VMWare Workstation Player (free), or VMWare Workstation Pro (paid) installed
VMWare Workstation Player (free): https://www.vmware.com/products/workstation-player.html (VMWare Workstation Player 16 download)
VMWare Workstation Pro (paid): https://www.vmware.com/products/workstation-pro.html
You should have patched your VMWare installation using the Unlocker app
Instructions
Open VMWare and click File -> New Virtual Machine
Select Custom Installation
and start navigating through the New Virtual Machine setup screens.
On the Guest Operating System Installation
page, select, I will install the operating system later.
On the Select a Guest Operating System
page, select Apple Mac OS X
, as well as the corresponding macOS version.
On the Processor Configuration
page, select 1
for the Number of processors
.
For the Number of cores per processor
, select a number that is within your computer's resource constraints.
On the Memory for the Virtual Machine
page, we recommend the following:
Minimum: 4096 MB
Recommended: 8096 MB
On the Network Type
page, select Use network address translation (NAT)
.
On the Select a Disk
page, select Use an existing virtual disk
.
On the Select an Existing Disk
page, browse & select the recovery.vmdk
disk we created earlier.
Finish the setup.
Edit your Virtual Machine's settings.
Add a new piece of hardware.
On the Hardware Type
page, select Hard Disk
.
On the Disk Type
page, select SATA
.
On the Select a Disk
page, select Create a new virtual disk
On the Specify Disk Capacity
page, enter an amount that makes sense
Minimum: 50 GB
Recommended: 80 GB
Complete the Hard Disk setup.
This section will detail how to patch your virtual machine in order to properly run macOS and get iServices setup.
Navigate to your virtual machine's files
The virtual machine's files are located here: C:\Users\<username>\Documents\Virtual Machines\
Create a backup of your virtual machine's .vmx
file
You can just copy and paste it into the same directory, appending .bak
to the filename.
Open your virtual machine's original Configuration File
(.vmx
) in a text editor (i.e. Notepad)
Paste the following line into the .vmx
file and save it.
If you have an AMD CPU, also add the following to your .vmx
file.
macOS Ventura
If your VM is macOS Ventura, you may need to add (or edit) the following to enable internet connectivity:
Once you've edited the .vmx
file, you should be able to boot the virtual machine normally.
Common Issues
If you are having issues performing the initial boot for the virtual machine, take a look at the most common issues below.
Stuck on Apple Boot Logo: If you attempt to boot your virtual machine and it's stuck on the Apple Boot Logo, do the following to fix the issue. Power off the Virtual Machine, then open the virtual machine's settings. Once the settings window opened beside the Hardware
tab click on Options
. Change the Apple Mac OS X
selection to Microsoft Windows
then click OK. Power on the virtual machine again. Once all installed then go back to settings and set it back to Apple Mac OS X
The CPU has been disabled by the guest operating system: Enable virtualization in your computer's BIOS
There are guides on YouTube describing how to do this.
Feature 'cpuid.ds' was absent, but must be present: This is due to a corrupted vmx file. Try using a backup of your .vmx
file and edit the .vmx
file carefully this time.
Make sure that your editor is not converting the quotes ("
) to "greek" quotes
This virtual machine requires AVX2 but AVX is not present. This virtual machine cannot be powered on: This is due to a corrupted vmx file. Try using a backup of your .vmx
file and edit the .vmx
file carefully this time.
Make sure that your editor is not converting the quotes ("
) to "greek" quotes
Module 'featurecompat' power on failed: In your .vmx
file, make sure that your editor is not converting the quotes ("
) to "greek" quotes
Once you're able to boot into the recovery setup, follow these steps to properly install macOS.
Note: You may want to power off your virtual machine and take a snapshot before continuing. If anything goes wrong during setup, you can always revert back to your snapshot.
Select Disk Utility
and hit Continue
.
On the Disk Utility
page, select the Hard Disk you created.
This is not the one labeled, macOS Base System
With the Hard Disk selected, click Erase
in the top right of Disk Utility.
This will format the hard disk into a format that macOS can use.
Close Disk Utility.
On the recovery page, select Reinstall macOS <version>
and hit Continue
.
Continue through the setup, accepting the license agreement(s).
When prompted to select the disk to install macOS, select the disk you just formatted.
Wait for the operating system to be installed.
Once the operating system is installed, navigate through the macOS setup.
You do not need to sign into an Apple ID when prompted.
Create your macOS computer account, finish the setup, and login.
Note: Once everything is setup, you may edit the Virtual Machine's settings and remove the recovery.vmdk
Hard Disk. Do not delete the Hard Disk you created manually (to store the install). Note 2: You may want to power off your virtual machine and take another snapshot before continuing.
By default, your macOS deployment will not support iServices such as iMessage. In order to support iServices, additional configurations must be done. We will accomplish this by utilizing a tool called Clover Configurator
.
Boot up your macOS virtual machine and login.
Open Safari and download Clover Configurator
.
Open Clover Configurator
.
You may need to allow it to run via System Preferences -> Security & Privacy
.
Once opened, navigate to the SMBIOS
tab in the sidebar.
Find the up/down arrow button under the large "question mark" image, and to the right of the Update Firmware Only
checkbox.
Click on the up/down arrow button and select any product made in 2019 or newer.
We recommend MacPro7,1
or iMac16,1
Copy the following configuration to an editor (i.e. Notepad), on your host computer (Windows).
In Clover Configurator, click the Generate New
button next to the Serial Number
field to generate a new serial number.
Copy & paste the following Clover Configurator SMBIOS fields into the configuration from above:
AAA
: Replace with your Board ID
(i.e. Mac-XXXXXXXXXXXXXX
)
BBB
: Replace with your Product Name
(i.e. MacPro7,1
)
CCC
: Replace with your generated Serial Number
In Clover Configurator, click on the Rt Variables
tab in the sidebar.
Click on the Generate
button next to the ROM
text.
Copy & paste the following Clover Configurator Rt Variable fields into the configuration from above:
DDD
: Replace with your generated ROM
EEE
: Replace with your generated MLB
Close Clover Configurator & shut down your macOS virtual machine
Open your virtual machine's .vmx
file. The same one you edited earlier in the setup guide.
The virtual machine's files are located here: C:\Users\<username>\Documents\Virtual Machines\
Paste your completed configuration above into the .vmx
file.
Find the board-id.reflectHost
configuration and verify that it is set to "TRUE"
.
Find the ethernet0.addressType
configuration and change it from "generated"
to "static"
In your browser, go to the following link to grab an "OUI" for the configuration:
The OUI contains 3 segments, each containing 2 characters.
It does not matter which OUI you choose. Choose any.
Find the ethernet0.generatedAddress
configuration and change the first 3 segments to match the 3 segments of your chosen OUI.
Example: If my current generatedAddress
is 00:0c:29:bb:91:7f
, and I've selected the OUI, 00-1F-F3
, my new generatedAddress
will be 00:1f:f3:bb:91:7f
It's recommended to use lower-case characters for the alphabetical letters.
Rename the ethernet0.generatedAddress
configuration to just ethernet0.Address
Replace the ethernet0.generatedAddressOffset = "0"
configuration with ethernet0.checkMACAddress = "FALSE"
Save and close the .vmx
file.
Your macOS virtual machine should be good to go! You now should be able to sign into iMessage and use the other iServices. Boot up your virtual machine and sign into iMessage to verify everything is working correctly.
Note: If something failed during setup and your macOS virtual machine will not boot, restore from an earlier snapshot and redo part of the setup!
Here are a few final checks to make sure that your macOS virtual machine is setup correctly.
When the macOS virtual machine is booted & running, click on the Apple Logo
and select About this Mac
. Verify that the serial number listed matches the serial number you configured in the steps above.
Open System Preferences
and open your Date & Time
settings. Verify that your timezone is set correctly and your time is properly synced.
If you are unsure, you can open Safari and go to https://time.is to see if your time synchronization is misaligned.
If your time synchronization is misaligned, you can synchronize it by opening Terminal
and running this command: sudo ntpdate -vu time.apple.com
This guide will show you how to setup the BlueBubbles Docker container to run as a service on your Linux host. This is to make sure that the host starts up when your Linux host restarts.
If you do not have a physical Mac at your disposal and if you already have a Linux home server, it is relatively easy to turn BlueBubbles into a systemd service which you can configure to run at startup. This way, when your home server starts or reboots, it BlueBubbles automatically starts up.
BlueBubbles does have to be initially configured manually, including a full install of a macOS VM. However, using Docker-OSX makes this configuration much easier. If you are not already running BlueBubbles in a Docker-OSX container, first follow our guide on Configuring BlueBubbles in a container with Docker-OSX.
Once you are done configuring Docker-OSX and your BlueBubbles install:
. This will make the boot faster and allow the BlueBubbles server to start automatically.
In your BlueBubbles server settings, enable "Startup with MacOS".
If using the Private API, ensure that MacForce launches at start:
MacForge Preferences > "General" tab > Check "Launch MacForce at Login"
Create a new systemd service:
2. Enter the following:
It's recommended that you replace the value of ExecStart
with the script you made in Step 11 of the Configuring BlueBubbles in a container with Docker-OSX guide. If you do choose to paste the above code block into your new systemd service file, you will at least need to replace $PWD
(in the -v
options) with the full path to your Docker OSX virtual disks.
Alternatively, it is possible to point to the script file you saved. In that case, replace the ExecStart
line with this instead:
NOTE: If using podman, replace docker.service
with podman.service
and the docker run
command with podman run
.
3. Reload the systemd daemons:
4. Enable the service to start it at boot, and activate it now:
Expand the sidebar for this page to see various guides to help you set up a macOS VM.
If iMessage will not let you sign in, make sure to follow .
If you plan to make your VM in Windows, we highly recommend using .
This is by no means an easy process, and it is not guaranteed to work. We recommend using real Mac hardware to avoid compromising your Apple ID, you can find cheap Mac Minis (2009) on eBay for around $50-$75.
Feel free to join our Discord, linked in the header above, if you need any help!
This tutorial will show you how you can setup BlueBubbles in a Docker container, within a Linux host.
This guide is a contribution by @JustBen on our Discord
This guide is not for beginners. However, these steps should make it relatively easy to get up and running with a macOS Docker container running BlueBubbles on a Linux host. Before starting, you should familiarize yourself with the Linux CLI and be at least familiar with containerization and Docker (or Podman).
This guide is provided with no guarantees or warranty. If you encounter any problems, the community may be able to provide help in the Discord (linked in the header of this page), but we cannot guarantee that this will work for every configuration.
This guide has only been tested with MacOS Ventura, though it should work with only minor modifications for older versions.
This guide will walk you through setting up BlueBubbles on a macOS VM running in a . With the given configuration, your container will be accessible by VNC on port 5999.
You must have all of these already setup/installed in order to continue with the guide.
A Linux host
Comfort with bash
Packages:
docker
(or podman
)
docker-compose
(or podman-compose
)
tigervnc
(or another vncviewer)
qemu
All dependencies outlined by Docker-OSX in its
As noted in the link above, your system must support virtualization. The Docker-OSX documentation has steps on how to configure and verify that virtualization is supported and enabled on your system.
Create a directory for all the container resources
Create a virtual disk:
3. Run:
This will take a while because it's downloading the image for Docker-OSX and generating a unique serial number and bootdisk for your mac VM.
You may see a handful of errors particularly related to ALSA. These can be safely ignored.
NOTE: If using Podman, you can add --rmi
to also remove the image after setup. However, this flag can be annoying if you need to start/stop this step repeatedly to troubleshoot because it will re-download the image every time NOTE: If using Podman as a non-root user, the additional flag --network slirp4netns:port_handler=slirp4netns
must be added.
4. With your vnc viewer, open a connection to your IP on port 5999. If you're using tigervnc and running this on the same phost, you can use vncviewer localhost:5999
. The password will be vncpass
unless you changed it in the command.
5. If presented with a boot loader (a black screen with some icons in the center), select the option MacOS Base System
to boot into the recover/install menu.
6. Before installing, you have to format the drive with APFS for a macOS install. Go into Disk Utility and find your drive. Click "Erase". Fill in the name for the drive that you want, then leave the rest as defaults and click "Erase". Close out of Disk Utility.
7. Click on "reinstall macOS" and install macOS as normal.
8. Once you're on your desktop, test sending an iMessage to yourself. If it does not succeed, it's likely best to restart from the beginning, though our Discord community may be able to help.
9. Before shutting down your VM, run this in a new terminal with the same user:
This copies the generated bootdisk and serial number information out of the container and saves it as bootdisk.qcow2
so it can be used for all your future boots.
10. Shutdown your VM then take down the container.
The container and image will automatically be removed from your system (to keep things clean) because of the --rm
and --rmi
options we passed above.
11. Save this into a file (e.g. start-bluebubbles.sh
) and make sure you have execute permissions to run it (chmod +x start-bluebubbles.sh
).
This new docker run command should cut down on boot time and general overhead.
As before, errors related to ALSA can be safely ignored.
It is HIGHLY RECOMMENDED that you replace $PWD
in the above command (after both -v
flags) with an absolute path. For example, replace $PWD/maindisk.qcow2:/image
with /home/yourname/bluebubbles/maindisk.qcow2:/image
. This allows you to more easily run this script from any working directory (as you may want to do with a systemd service file).
To change the VNC password, change data=vncpass
to data=<yourpassword>
in the EXTRA
environment variable.
NOTE: As before, if using Podman as a non-root user, the additional flag --network slirp4netns:port_handler=slirp4netns
must be added.
12. Start up the container again (by running the script file you made in step 11). It might take a little while the first time as it pulls down a new container image, but it'll be quicker to boot after this first time. Once it's up, you can connect again with VNC on port 5999 with password vncpass
(unless you changed it).
14. When you want to start the container again, run the script you made in step 11. As before, you can connect to your VM with VNC on port 5999 with vncpass
or the password you set. To stop the container, run:
When disabling SIP, follow the instructions for "Physical Mac, INTEL" on the Private API installation documentation.
NOTE: On Ventura, you may have to use "MacOS extended (Journaled)" instead of APFS. See for more information.
13.
To install the BlueBubbles Private API features, just follow the normal guide .
To clarify, do NOT follow the documentation for . Everything you need is in the standard Private API installation guide.