Run macOS Inside Docker: Complete Docker‑OSX Tutorial

Docker is an open‑source container engine that packages applications and their dependencies into portable containers, which can run on any Linux or Windows host using sandbox isolation.

What Is the Docker‑OSX Project?

The official description reads:

Run Mac in a Docker container! Run near native OSX‑KVM in Docker! X11 Forwarding!

Features

CI/CD weaponization through VNC and xdotool for automated pipelines.

OSX‑KVM – runs macOS on KVM.

X11 Forwarding – forwards display via the X11 protocol.

SSH on localhost:50922 – allows SSH connections to the OS.

QEMU support.

VNC on localhost:8888 – provides graphical remote access.

Create an ARMY using docker commit – turn a running container into an image.

XFVB HEADLESS (use VNC) – headless operation via VNC.

Using the pre‑built image makes launching macOS extremely simple.

Operation

Run Docker‑OSX

Pull the image: docker pull sickcodes/docker-osx:latest Start the container:

docker run \
    --device /dev/kvm \
    --device /dev/snd \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -e "DISPLAY=${DISPLAY:-:0.0}" \
    sickcodes/docker-osx:latest

After macOS starts, enable SSH access:

docker run \
    --device /dev/kvm \
    --device /dev/snd \
    -e RAM=4 \
    -p 50922:10022 \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -e "DISPLAY=${DISPLAY:-:0.0}" \
    sickcodes/docker-osx:latest

Connect via SSH (macOS must have SSH enabled):

ssh fullname@localhost -p 50922

Use VNC for Graphical Access

Build the VNC‑enabled Docker‑OSX image from the Dockerfile at:

https://github.com/sickcodes/Docker-OSX/blob/master/vnc-version/Dockerfile

Build command: docker build -t docker-osx-vnc . Run the VNC container:

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

Connect with a VNC client:

Local VNC: localhost:8888 Remote VNC: remotehost:8888 To view the VNC password, find the container ID and inspect the password file:

docker ps
# copy container ID and then
docker exec abc123fgh456 tail vncpasswd_file