dockur/macos

Before running the container, ensure your host meets these requirements:

• Linux Host: Docker or Podman with KVM support.
• Windows Host: Docker Desktop or Podman (Desktop) on Windows 11 with nested virtualization enabled.
• Processor: An AVX2-capable processor (e.g., Intel Haswell/4th-gen Core or newer, AMD Zen/Ryzen 1000 series or newer).
• RAM: At least 4 GB of available RAM.
• Disk Space: At least 32 GB of free disk space.

NOTE

Docker Desktop on Linux, macOS, and Windows 10 does not currently provide KVM access to containers and is therefore not supported.

To run macOS in a Docker container using Compose, create a docker-compose.yml file with the following configuration. This setup includes KVM acceleration, network tuning capabilities, and a persistent storage volume.

services:
  macos:
    image: dockurr/macos
    container_name: macos
    environment:
      VERSION: "15"
    devices:
      - /dev/kvm
      - /dev/net/tun
    cap_add:
      - NET_ADMIN
    ports:
      - 8006:8006
      - 5900:5900/tcp
      - 5900:5900/udp
    volumes:
      - ./macos:/storage
    restart: always
    stop_grace_period: 2m

To expand an existing disk, first increase the DISK_SIZE environment variable in your configuration. After the container starts, you must run the following commands from the macOS terminal to allocate the new space:

diskutil repairDisk disk2
diskutil apfs resizeContainer disk3 0

(Note: Disk identifiers like disk2 or disk3 may vary depending on your setup.)

To share a host folder with the macOS guest, use a bind mount and the 9p protocol:

1. Add a volume mapping in your configuration (e.g., - ./example:/shared).
2. Inside macOS, run the following command to mount the share:

sudo -S mount_9p shared

3. In Finder, go to Go → Computer to access the folder.

volumes:
  - ./example:/shared

Run the macOS container directly using the Docker CLI. This command sets the version to 14, maps the web viewer port, and mounts a local directory for storage.

docker run -it --rm --name macos -e "VERSION=14" -p 8006:8006 --device=/dev/kvm --device=/dev/net/tun --cap-add NET_ADMIN -v "${PWD:-.}/macos:/storage" --stop-timeout 120 docker.io/dockurr/macos

To bypass bridge networking and give the container its own IP on your local network, use a macvlan network.

1. Create the network on the host (adjusting for your subnet):

docker network create -d macvlan \
    --subnet=192.168.0.0/24 \
    --gateway=192.168.0.1 \
    --ip-range=192.168.0.100/28 \
    -o parent=eth0 vlan

2. Configure your Compose file to use the network and assign a static IP:

services:
  macos:
    networks:
      vlan:
        ipv4_address: 192.168.0.100

networks:
  vlan:
    external: true

Warning: Due to macvlan design, the Docker host will not be able to communicate with the container's IP address directly.

Manage how you view the macOS interface:

Display Settings:

• DISPLAY: Display backend: web, vnc, disabled, or none. Defaults to web.
• LOSSY: Enables lossy VNC compression to reduce bandwidth usage. Defaults to N.
• VGA: QEMU video adapter model. Defaults to vmware.
• WIDTH: Display width for macOS and OpenCore. Defaults to 1920.
• HEIGHT: Display height for macOS and OpenCore. Defaults to 1080.

Web UI Settings:

• WEB: Enables the web interface. Defaults to Y.
• WEB_PORT: Port for the web interface. Defaults to 8006.
• VNC_PORT: Port for the VNC server. Defaults to 5900.
• AUDIO: Streams guest audio to the web viewer. Defaults to N.
• SOUND: QEMU audio device used by the web viewer. Defaults to usb-audio.
• PROTECT: Enables password protection for the web interface. Defaults to N.

To pass a USB device to the macOS VM, you must provide the vendor and product IDs via the ARGUMENTS environment variable and map the USB bus in devices.

1. Find IDs using lsusb on the host.
2. Add to configuration:

environment:
  ARGUMENTS: "-device usb-host,vendorid=0x1234,productid=0x1234"
devices:
  - /dev/bus/usb

Adjust the hardware allocation using the following environment variables:

• RAM_SIZE: Set the amount of RAM (e.g., 8G). Default is 4 GB.
• CPU_CORES: Set the number of CPU cores (e.g., 4). Default is 1 core.
• DISK_SIZE: Set the disk capacity (e.g., 256G). Default is 64 GB.

Important for AMD Users: Avoid assigning multiple CPU cores or more than 8 GB of RAM during the initial installation to prevent freezes or instability. Increase these values only after the installation is complete and the system has run reliably for several hours.

environment:
  RAM_SIZE: "8G"
  CPU_CORES: "4"
  DISK_SIZE: "256G"

Control the computational resources allocated to the macOS guest:

• CPU_CORES: Number of virtual CPU cores. Accepts values like 4, half, or max. Defaults to 1.
• CPU_MODEL: QEMU CPU model. Automatically selected for Intel or AMD hosts if unset.
• CPU_FLAGS: Additional QEMU CPU flags.
• SMP: Custom CPU topology. Determined from CPU_CORES if unset.
• KVM: Enables KVM hardware acceleration. Defaults to Y.
• RAM_SIZE: Amount of RAM assigned to macOS (e.g., 8G, half, or max). Defaults to 4G.
• RAM_CHECK: If Y, checks whether enough host memory is available before starting macOS. Defaults to Y.

Control how the system shuts down and how you debug the container:

Shutdown:

• SHUTDOWN: Enables graceful ACPI shutdown. Defaults to Y.
• TIMEOUT: Maximum time, in seconds, to wait before forcing macOS to stop. Defaults to 115.

Debugging:

• DEBUG: Enables verbose debug output. Defaults to N.
• TRACE: Enables shell command tracing. Defaults to N.
• SERIAL: QEMU serial device configuration. Defaults to mon:stdio.
• MONITOR: QEMU monitor configuration.
• QMP: QEMU Machine Protocol configuration.