Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
D

Docker-OSX

> DevOps
Free

Run macOS VM in a Docker! Run near native OSX-KVM in Docker! X11 Forwarding! CI/CD for OS X Security

53.0K stars0 likes0 views
WebsiteGitHub

About

Run macOS VM in a Docker! Run near native OSX-KVM in Docker! X11 Forwarding! CI/CD for OS X Security

Docker-OSX · Follow @sickcodes on Twitter

Run Mac OS X in Docker with near-native performance! X11 Forwarding! iMessage security research! iPhone USB working! macOS in a Docker container!

Conduct Security Research on macOS using both Linux & Windows!

Docker-OSX now has a Discord server & Telegram!

The Discord is active on #docker-osx and anyone is welcome to come and ask questions, ideas, etc.

Click to join the Discord server https://discord.gg/sickchat

Click to join the Telegram server https://t.me/sickcodeschat

Or reach out via Linkedin if it's private: https://www.linkedin.com/in/sickcodes

Or via https://sick.codes/contact/

Author

This project is maintained by Sick.Codes. (Twitter)

Additional credits can be found here: https://github.com/sickcodes/Docker-OSX/blob/master/CREDITS.md

Additionally, comprehensive list of all contributors can be found here: https://github.com/sickcodes/Docker-OSX/graphs/contributors

Big thanks to @kholia for maintaining the upstream project, which Docker-OSX is built on top of: OSX-KVM.

Also special thanks to @thenickdude who maintains the valuable fork KVM-OpenCore, which was started by @Leoyzen!

Extra special thanks to the OpenCore team over at: https://github.com/acidanthera/OpenCorePkg. Their well-maintained bootloader provides much of the great functionality that Docker-OSX users enjoy :)

If you like this project, consider contributing here or upstream!

Quick Start Docker-OSX

Video setup tutorial is also available here: https://www.youtube.com/watch?v=wLezYl77Ll8

Windows users: click here to see the notes below!

First time here? try initial setup, otherwise try the instructions below to use either Catalina or Big Sur.

Any questions, ideas, or just want to hang out?

https://discord.gg/sickchat

Release names and their version:

Catalina (10.15)

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

# docker build -t docker-osx .

Big Sur (11)

bash
docker run -it \
    --device /dev/kvm \
    -p 50922:10022 \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -e "DISPLAY=${DISPLAY:-:0.0}" \
    -e SHORTNAME=big-sur \
    sickcodes/docker-osx:latest

# docker build -t docker-osx .

Monterey (12)

bash

docker run -it \
    --device /dev/kvm \
    -p 50922:10022 \
    -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' \
    -e SHORTNAME=monterey \
    sickcodes/docker-osx:latest

# docker build -t docker-osx .

Ventura (13)

bash

docker run -it \
    --device /dev/kvm \
    -p 50922:10022 \
    -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' \
    -e SHORTNAME=ventura \
    sickcodes/docker-osx:latest

# docker build -t docker-osx .

Sonoma (14)

bash

docker run -it \
    --device /dev/kvm \
    -p 50922:10022 \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -e "DISPLAY=${DISPLAY:-:0.0}" \
    -e GENERATE_UNIQUE=true \
    -e CPU='Haswell-noTSX' \
    -e CPUID_FLAGS='kvm=on,vendor=GenuineIntel,+invtsc,vmware-cpuid-freq=on' \
    -e MASTER_PLIST_URL='https://raw.githubusercontent.com/sickcodes/osx-serial-generator/master/config-custom-sonoma.plist' \
    -e SHORTNAME=sonoma \
    sickcodes/docker-osx:latest

# docker build -t docker-osx .

Sequoia (15)

bash

docker run -it \
    --device /dev/kvm \
    -p 50922:10022 \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -e "DISPLAY=${DISPLAY:-:0.0}" \
    -e GENERATE_UNIQUE=true \
    -e CPU='Haswell-noTSX' \
    -e CPUID_FLAGS='kvm=on,vendor=GenuineIntel,+invtsc,vmware-cpuid-freq=on' \
    -e MASTER_PLIST_URL='https://raw.githubusercontent.com/sickcodes/osx-serial-generator/master/config-custom-sonoma.plist' \
    -e SHORTNAME=sequoia \
    sickcodes/docker-osx:latest

# docker build -t docker-osx .

Tahoe (16)

bash

docker run -it \
    --device /dev/kvm \
    -p 50922:10022 \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -e "DISPLAY=${DISPLAY:-:0.0}" \
    -e GENERATE_UNIQUE=true \
    -e CPU='Haswell-noTSX' \
    -e CPUID_FLAGS='kvm=on,vendor=GenuineIntel,+invtsc,vmware-cpuid-freq=on' \
    -e MASTER_PLIST_URL='https://raw.githubusercontent.com/sickcodes/osx-serial-generator/master/config-custom-sonoma.plist' \
    -e SHORTNAME=tahoe \
    sickcodes/docker-osx:latest

docker build -t docker-osx .

Older Systems

High Sierra

bash

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

# docker build -t docker-osx .

Mojave

bash

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

# docker build -t docker-osx .

Download the image manually and use it in Docker

This is a particularly good way for downloading the container, in case Docker's CDN (or your connection) happens to be slow.

bash
wget https://images2.sick.codes/mac_hdd_ng_auto.img

docker run -it \
    --device /dev/kvm \
    -p 50922:10022 \
    -v "${PWD}/mac_hdd_ng_auto.img:/image" \
    -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/Docker-OSX/master/custom/config-nopicker-custom.plist \
    -e SHORTNAME=catalina \
    sickcodes/docker-osx:naked

Share directories, sharing files, shared folder, mount folder

The easiest and most secure way is sshfs

bash
# on Linux/Windows
mkdir ~/mnt/osx
sshfs user@localhost: -p 50922 ~/mnt/osx
# wait a few seconds, and ~/mnt/osx will have full rootfs mounted over ssh, and in userspace
# automated: sshpass -p <password> sshfs user@localhost:/ -p 50922 ~/mnt/osx

(VFIO) iPhone USB passthrough (VFIO)

If you have a laptop see the next usbfluxd section.

If you have a desktop PC, you can use @Silfalion's instructions: https://github.com/Silfalion/Iphone_docker_osx_passthrough

(USBFLUXD) iPhone USB -> Network style passthrough OSX-KVM Docker-OSX

Video setup tutorial for usbfluxd is also available here: https://www.youtube.com/watch?v=kTk5fGjK_PM

This method WORKS on laptop, PC, anything!

Thank you @nikias for usbfluxd via https://github.com/corellium!

This is done inside Linux.

Open 3 terminals on Linux

Connecting your device over USB on Linux allows you to expose usbmuxd on port 5000 using https://github.com/corellium/usbfluxd to another system on the same network.

Ensure usbmuxd, socat and usbfluxd are installed.

sudo pacman -S libusbmuxd usbmuxd avahi socat

Available on the AUR: https://aur.archlinux.org/packages/usbfluxd/

yay usbfluxd

Plug in your iPhone or iPad.

Terminal 1

bash
sudo systemctl start usbmuxd
sudo avahi-daemon

Terminal 2:

bash
# on host
sudo systemctl restart usbmuxd
sudo socat tcp-listen:5000,fork unix-connect:/var/run/usbmuxd

Terminal 3:

bash
sudo usbfluxd -f -n

Connect to a host running usbfluxd

This is done inside macOS.

Install homebrew.

172.17.0.1 is usually the Docker bridge IP, which is your PC, but you can use any IP from ip addr...

macOS Terminal:

bash
# on the guest
brew install make automake autoconf libtool pkg-config gcc libimobiledevice usbmuxd

git clone https://github.com/corellium/usbfluxd.git
cd usbfluxd

./autogen.sh
make
sudo make install

Accept the USB over TCP connection, and appear as local:

(you may need to change 172.17.0.1 to the IP address of the host. e.g. check ip addr)

bash
# on the guest
sudo launchctl start usbmuxd
export PATH=/usr/local/sbin:${PATH}
sudo usbfluxd -f -r 172.17.0.1:5000

Close apps such as Xcode and reopen them and your device should appear!

If you need to start again on Linux, wipe the current usbfluxd, usbmuxd, and socat:

bash
sudo killall usbfluxd
sudo systemctl restart usbmuxd
sudo killall socat

Make container FASTER using https://github.com/sickcodes/osx-optimizer

SEE commands in https://github.com/sickcodes/osx-optimizer!

  • Skip the GUI login screen (at your own risk!)
  • Disable spotlight indexing on macOS to heavily speed up Virtual Instances.
  • Disable heavy login screen wallpaper
  • Disable updates (at your own risk!)

Increase disk space by moving /var/lib/docker to external drive, block storage, NFS, or any other location conceivable.

Move /var/lib/docker, following the tutorial below

  • Cheap large physical disk storage instead using your server's disk, or SSD.
  • Block Storage, NFS, etc.

Tutorial here: https://sick.codes/how-to-run-docker-from-block-storage/

Only follow the above tutorial if you are happy with wiping all your current Docker images/layers.

Safe mode: Disable docker temporarily so you can move the Docker folder temporarily.

  • Do NOT do this until you have moved your image out already https://github.com/dulatello08/Docker-OSX/#quick-start-your-own-image-naked-container-image
bash
killall dockerd
systemctl disable --now docker
systemctl disable --now docker.socket
systemctl stop docker
systemctl stop docker.socket

Now, that Docker daemon is off, move /var/lib/docker somewhere

Then, symbolicly link /var/lib/docker somewhere:

bash
mv /var/lib/docker /run/media/user/some_drive/docker
ln -s /run/media/user/some_drive/docker /var/lib/docker

# now check if /var/lib/docker

Issues· 419 open

View all issuesOpen on GitHub
  • #927

    How to solve it? '/home/arch/OSX-KVM/BaseSystem.img': No such file or directory

    Updated Sep 16, 2026
  • #926

    Can we use this docker image to build enterprise apps?

    Updated Sep 9, 2026
  • #133

    Igpu passthrough

    enhancementhelp wantedUpdated Aug 24, 2026
  • #750

    iPhone not recognized in Xcode

    Updated Jul 31, 2026
  • #895

    gtk initialization failed

    Updated Jul 21, 2026
  • #791

    gtk initialization failed (Possibly ALSA Related)

    Updated Jul 14, 2026
  • #924

    unable to start tahoe

    Updated Jun 4, 2026
  • #904

    Blank wallpaper and cannot login into apple ID.

    Updated Jun 4, 2026
  • #923

    Macos sonoma with amd RX580

    Updated May 31, 2026
  • #666

    QEMU Docker OSX, Mouse always not working after running 2 minutes

    Updated Apr 17, 2026

> Tags

Shellcontainerdockerdocker-osx

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedOct 17, 2026
CategoryDevOps
PricingFree

> Related tools

D
Docker
容器化平台，标准化应用交付
G
GitHub Actions
GitHub 原生 CI/CD 工作流
N
Nginx
高性能 Web 服务器与反向代理