Introduction

This tutorial explains how to run a Dockerized MacOS on Unraid using the sickcodes/Docker-OSX project. This project allows for MacOS security research within containers on Linux and Windows.

This tutorial focuses on utilizing Unraid’s Docker-Compose functionality for container management and building a special VNC-compatible image necessary for Unraid. If you’re not using Unraid, the default image might be a better fit.

The standard sickcodes/Docker-OSX image on Docker Hub relies on KVM for screen rendering. While this tutorial doesn’t offer native NoVNC support like other Unraid containers (yet), it allows connection to the container via a VNC client. A solution for native NoVNC support is currently in progress.

This guide offers a concise solution for getting started with a functional and maintained container.

Building the VNC-compatible Image on Unraid

Connect to your Unraid server through SSH or the web portal’s Terminal. Execute the following commands to download the required Dockerfile and build the image:

1
2
3
4
5
6
mkdir /var/tmp/macos
cd /var/tmp/macos

wget https://raw.githubusercontent.com/sickcodes/Docker-OSX/master/vnc-version/Dockerfile

docker build -t docker-osx-vnc .

Initial image building attempts may encounter invalid key errors for numerous packages and prerequisites. If encountered, add the following lines to the Dockerfile after the “ARG MIRROR_COUNT=10” line:

1
2
3
4
5
# Disable signature checks for invalid key errors
RUN sudo sed -i 's/SigLevel    = Required DatabaseOptional/SigLevel = Never/g' /etc/pacman.conf
RUN if [[ "${LINUX}" == true ]]; then \
        sudo pacman -Syu linux libguestfs --noconfirm \
    ; fi

Open the Dockerfile:

1
nano /var/tmp/macos/Dockerfile

Paste the lines, save the file (CTRL + X), then rebuild the image:

1
docker build -t docker-osx-vnc .

The image should now build without errors.

Creating a Docker-Compose stack on Unraid

Docker-Compose simplifies container management and provides granular control. This guide leverages this tool for its ease of configuration transfer and sharing capabilities.

Ensure you have the “Docker Compose Manager” plugin (by dcflachs) installed from Unraid’s Community Applications. At the bottom of the Docker tab, select ADD NEW STACK and name it (e.g., “MacOS”). Click the gear icon next to the stack name, choose EDIT STACK, then select COMPOSE FILE. Paste the following configuration into the provided text box:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
version: '3'
services:
    macos:
        container_name: 'macos'
        image: 'docker-osx-vnc:monterey'
        privileged: true
        devices:
            - /dev/kvm
            - /dev/snd
            - /dev/null
        ports:
            - '8888:5999'
            - '50922:10022'
        environment:
            - 'USERNAME=user'
            - 'PASSWORD=pass'
            - 'DISPLAY=${DISPLAY:-:0.0}'

Save the changes and click COMPOSE UP to start the MacOS container. The new container will appear alongside your other containers in the Unraid GUI, providing access to logs and console.

Running the container without Docker-Compose

To run the container without Docker-Compose, execute the following command via SSH or the GUI Terminal:

1
docker run --device /dev/kvm --device /dev/snd -p 8888:5999 -p 50922:10022 -d --privileged docker-osx-vnc:latest

Connecting to the MacOS Container with VNC Protocol

Before connecting, obtain the generated VNC password. On Unraid, locate the macos container, click it, and select "Console".

In the new Terminal window, type:

1
cat vncpasswd_file

The output is your container’s VNC password.

Windows

Download and install a VNC client that supports TigerVNC (e.g., TightVNC Client). Launch the client and enter your container’s IP address followed by "::8888". Provide the VNC password when prompted.

MacOS

Utilize the built-in VNC client by pressing CMD+K and entering vnc://IP_OF_MACOS_DOCKER:8888. Enter the VNC password when prompted.