How To Run macOS in Docker Container using Docker-OSX

7 min readOct 12, 2022

It is habitual that docker containers can be accessed using CLI processes with no Graphical interfaces at all. Did you know it is possible to run graphical applications such as Firefox, chrome e.t.c on docker using OS X?

Docker-OSX is a project that simplifies macOS installation using Docker containers on OSX-KVM. It allows one to install macOS Big Sur, Monterey desktop, Catalina or boot to the OSX shell.

The provided docker images are:

macOS Catalina — sickcodes/docker-osx:latest(1.88GB)
macOS Big Sur — sickcodes/docker-osx:big-sur(2.1GB)
macOS Monterey — sickcodes/docker-osx:Monterey(2.08GB)
OS X shell with a visual display — sickcodes/docker-osx:auto

There are also older versions:

macOS Mojave — sickcodes/docker-osx:mojave(1.91GB)
macOS High Sierra — sickcodes/docker-osx:high-sierra(1.91GB)

This project offers amazing features such as:

Full auto mode: boot straight to OSX shell and even run commands as runtime arguments
SSH on localhost:50922
macOS Monterey VM on Linux!
NC version on localhost:8888: the VNC version is in a separate directory due to the security risks involved with using VNC
Xfvb headless mode
Folder sharing
Kubernetes Helm Chart.
X11 Forwarding
Use iPhone OSX KVM on Linux using usbfluxd!
Create an ARMY of the same exact container using docker commit
iMessage security research via serial number generator!

This guide will demonstrate how to run macOS in Docker Container using Docker-OSX.

Before You Begin

This guide will work best if the following are met:

Hardware virtualization enabled in BIOS
x86_64 KVM-capable host
20GB+++ disk space for bare minimum installation (50GB if using Xcode)
At least 50 GBs for :auto (half for the base image, half for your runtime image
Install Docker
Install QEMU on the host system

#1. Install QEMU on Linux

KVM hypervisor is required to be able to run macOS in Docker containers. Below is a list of guides to help you install QEMU on your host machine:

Once installed, add your user to the kvm group.

sudo usermod -aG kvm $USER

#2. Install Docker on Linux

This guide requires one to have the Docker engine installed. If you haven’t use the below guide:

How To Install Docker CE on Linux Systems

Add your system user to the docker group.

sudo usermod -aG docker $USER

newgrp docker

Start and enable docker:

sudo systemctl start docker && sudo systemctl enable docker

#3. Run macOS in Docker Containers

Now proceed and run the preferred macOS distribution in docker containers. There are several environment variables one can use.

macOS Big Sur

You can customize the WIDTH and HEIGHT to match your desired resolution.

docker run -it \

    --device /dev/kvm \

    -p 50922:10022 \

    -e DEVICE_MODEL="iMacPro1,1" \

    -e WIDTH=1600 \

    -e HEIGHT=900 \

    -v /tmp/.X11-unix:/tmp/.X11-unix \

    -e "DISPLAY=$DISPLAY:-:0.0" \

    -e GENERATE_UNIQUE=true \

    -e MASTER_PLIST_URL=https://raw.githubusercontent.com/sickcodes/osx-serial-generator/master/config-custom.plist \

    sickcodes/docker-osx:big-sur

macOS Catalina

docker run -it \

    --device /dev/kvm \

    -p 50923:10022 \

    -e GENERATE_UNIQUE=true \

    -e DEVICE_MODEL="iMacPro1,1" \

    -e WIDTH=1600 \

    -e HEIGHT=900 \

    -v /tmp/.X11-unix:/tmp/.X11-unix \

    -e "DISPLAY=$DISPLAY:-:0.0" \

    sickcodes/docker-osx:latest

macOS Monterey

docker run -it \

    --device /dev/kvm \

    -p 50924:10022 \

    -e GENERATE_UNIQUE=true \

    -e DEVICE_MODEL="iMacPro1,1" \

    -e WIDTH=1600 \

    -e HEIGHT=900 \

    -v /tmp/.X11-unix:/tmp/.X11-unix \

    -e "DISPLAY=$DISPLAY:-:0.0" \

    -e GENERATE_UNIQUE=true \

    -e MASTER_PLIST_URL='https://raw.githubusercontent.com/sickcodes/osx-serial-generator/master/config-custom.plist' \

    sickcodes/docker-osx:monterey

macOS High Sierra

docker run -it \

    --device /dev/kvm \

    -p 50922:10022 \

    -v /tmp/.X11-unix:/tmp/.X11-unix \

    -e "DISPLAY=$DISPLAY:-:0.0" \

    sickcodes/docker-osx:high-sierra

macOS Mojave

docker run -it \

    --device /dev/kvm \

    -p 50922:10022 \

    -v /tmp/.X11-unix:/tmp/.X11-unix \

    -e "DISPLAY=$DISPLAY:-:0.0" \

    sickcodes/docker-osx:mojave

More customization options can be made to the container such as:

RAM, Cores, SMP

The default RAM used is 3GB, but you can increase this depending on the available RAM.

$ free -mh

              total        used        free      shared  buff/cache   available

Mem:          20.5Gi       5.8Gi        5.8Gi     322Mi       1.6Gi       10.1Gi

Swap:         12.0Gi       922Mi       1.1Gi

Adjust the RAM, Cores, SMP using the flags:

-e RAM=6 \

    -e SMP=4 \

    -e CORES=4 \

Resolution

The desired resolution can be set using the Height and width for example 800×600 will be:

-e WIDTH=800 \

    -e HEIGHT=600 \

Mounting Physical disks

You can mount a physical Mac OSX disk. First export the variables:

OSX_IMAGE="$PWD/mac_hdd_ng_xcode_bigsur.img"

DISK_TWO="$PWD/mount_me.img"

Now capture the disk in docker using the -v flag.

-v "$OSX_IMAGE":/image \

    -v "$DISK_TWO":/disktwo \

#4. Configure your macOS Installation

The download will take a few minutes. Once complete, you will see this popup.

How-To-Run-macOS-in-Docker-Container-using-Docker-OSX

Select macOS Base System and proceed. The system will initialize a shown.

How-To-Run-macOS-in-Docker-Container-using-Docker-OSX-1

Format the largest QEMU Disk

Using the Disk Utility format the largest QEMU Disk.

For this case, the largest disk is 274.88 GB. Once selected, click on erase.

How-To-Run-macOS-in-Docker-Container-using-Docker-OSX-3

Provide a name for the disk and click Erase

How-To-Run-macOS-in-Docker-Container-using-Docker-OSX-4

Once complete, you will see this.

How-To-Run-macOS-in-Docker-Container-using-Docker-OSX-5

#5. Install macOS on the Virtual Machine.

Close the disk utility and now click on Reinstall macOS Big Sur or whatever distribution for your case.

How-To-Run-macOS-in-Docker-Container-using-Docker-OSX-6

Click continue to start the installation.

How-To-Run-macOS-in-Docker-Container-using-Docker-OSX-7

Agree to the License terms.

How-To-Run-macOS-in-Docker-Container-using-Docker-OSX-8

Select the erased disk. For my case, I named it BigSur.

How-To-Run-macOS-in-Docker-Container-using-Docker-OSX-9

Sit back and wait for the installation to complete.

How-To-Run-macOS-in-Docker-Container-using-Docker-OSX-10

Once complete, the macOS VM will reboot. Select the macOS Installer entry here.

How-To-Run-macOS-in-Docker-Container-using-Docker-OSX-11

On completion, the entry above will be updated to Big Sur. Now you can boot into your new installation by clicking on it.

How-To-Run-macOS-in-Docker-Container-using-Docker-OSX-13

Proceed and make the post-installation configurations such as:

Setting our country or region

How-To-Run-macOS-in-Docker-Container-using-Docker-OSX-14

Set the preferred language

How-To-Run-macOS-in-Docker-Container-using-Docker-OSX-15

Set apple ID, create a user account and password e.t.c

How-To-Run-macOS-in-Docker-Container-using-Docker-OSX-16

Mount/Share directories, files

The easiest way to achieve this is by using sshfs

First, create the directory to be shared/mounted.

sudo mkdir /mnt/osx

sudo chmod -R 777 /mnt/osx

Now use sshfs to mount/share the directory:

sshfs user@localhost:/ -p 50922 /mnt/osx

After a few seconds, you will have the directory mounted.

#6. Manage the macOS Virtual Machine

The macOS virtual machine can be managed using docker. To start it, get the container ID with the command:

$ docker ps -a

CONTAINER ID   IMAGE                          COMMAND                  CREATED        STATUS                      PORTS     NAMES

9ce4b501ce82   sickcodes/docker-osx:big-sur   "/bin/bash -c 'sudo …"   14 hours ago   Exited (0) 22 minutes ago             loving_poincare

Use the container ID to start the VM.

docker start Container_ID/Name

You can also configure the VM to run as a system service by creating a service file.

sudo vim /etc/systemd/system/BigSur_container.service

Add the below lines to the file:

[Unit]

Description=Semaphore container



[Service]

Restart=always

ExecStart=/usr/bin/docker start -a Container_ID/Name

ExecStop=/usr/bin/docker stop -t 2 Container_ID/Name



[Install]

WantedBy=local.target

Remember to replace the Container_ID/Name in the file as required. Reload the system daemon.

sudo systemctl daemon-reload

Now you can start the container just like any other system service:

sudo systemctl start BigSur_container

Check the status of the container.

$ systemctl status BigSur_container

● BigSur_container.service - Semaphore container

     Loaded: loaded (/etc/systemd/system/BigSur_container.service; disabled; vendor preset: >

     Active: active (running) since Wed 2022-06-01 13:23:21 EAT; 13s ago

   Main PID: 7368 (docker)

      Tasks: 8 (limit: 9070)

     Memory: 18.0M

     CGroup: /system.slice/BigSur_container.service

             └─7368 /usr/bin/docker start -a 9ce4b501ce82



Jun 01 13:23:39 home docker[7368]: + for f in /sys/block/sd*/device/timeout

Jun 01 13:23:39 home docker[7368]: + echo 300

To stop the container run:

sudo systemctl stop BigSur_container

To remove a Docker-OSX container, first, get the list of available containers.

docker container ls -a

Stop the container.

docker container stop ID_or_Name

docker container rm ID_or_Name

Remove images:

docker image ls

Then remove the identified image:

docker image rm Image_ID

Closing Thoughts

That marks the end of this guide on how to run macOS in Docker Container using Docker-OSX. I hope learned a lot from this guide.

https://www.computingpost.com/how-to-run-macos-in-docker-container-using-docker-osx/?feed_id=11864&_unique_id=6347366faac7e