Self-hosting macOS virtualisation

Self-hosting macOS virtual machines has become an area of interest for developers, QA teams, and IT professionals seeking a contained testing environment. The dockurr/macos project provides a streamlined method to run macOS within Docker using QEMU and KVM acceleration. This article explains the setup process, key requirements, and important compliance considerations.

Compliance

Apple’s licensing terms only permit macOS to be virtualised on Apple-branded hardware. Running a macOS guest on non-Apple devices constitutes a licence breach. Organisations intending to deploy this workflow must ensure hosts are Apple hardware to remain compliant with Apple’s End User Licence Agreement (EULA).

Requirements

The container relies on hardware virtualisation and networking support. Before deploying, verify:

• CPU virtualisation: Intel VT-x or AMD-V enabled in BIOS/firmware.
• KVM device: /dev/kvm must exist and be accessible to Docker. On Linux, install qemu-kvm, libvirt packages, and test with kvm-ok.
• TUN device: /dev/net/tun must be present. Load with modprobe tun if missing.
• Nested virtualisation: If running inside another VM, ensure nested KVM is enabled.

These prerequisites enable QEMU to provide near-native CPU performance.

Container

A standard docker-compose.yml file provisions the macOS guest. An example:

services:
  macos:
    image: dockurr/macos
    container_name: macos
    environment:
      VERSION: "15"        # macOS Sequoia
      RAM_SIZE: "20G"
      CPU_CORES: "8"
      DISK_SIZE: "128G"
    devices:
      - /dev/kvm
      - /dev/net/tun
    cap_add:
      - NET_ADMIN
    ports:
      - "8006:8006"        # Web console
      - "5900:5900/tcp"    # VNC
      - "5900:5900/udp"
    volumes:
      - ./macos:/storage
    restart: always
    stop_grace_period: 2m

Persistent storage, including the VM disk, is maintained in the ./macos directory. Resource allocation can be customised for RAM, CPU, and disk size.

Installation

Once deployed, the installation proceeds through Apple’s recovery utilities:

Start

Run docker compose up -d to launch the service.

docker compose up -d

Connect

Access via browser at http://localhost:8006 or through a VNC client on port 5900.

Format

In Disk Utility, erase the largest "VirtIO Block Media" disk and format as APFS.

Install

Choose "Reinstall macOS" and complete the guided setup. The installer will download files and reboot several times.

The installation can take considerable time depending on network throughput.

Performance

• Acceleration: KVM enables hardware-accelerated virtualisation, delivering improved responsiveness.
• Interface: Native VNC clients provide smoother display performance compared with the web console.
• Persistence: VM state is stored on the mapped volume, ensuring continuity across restarts.
• Networking: Assigning NET_ADMIN and /dev/net/tun supports bridged networking for internet connectivity.

These optimisations enhance usability but performance will still be below bare-metal macOS.

Troubleshoot

Common issues include:

• Download: Adjust DNS entries in the Compose file (e.g., 1.1.1.1, 8.8.8.8).
• Permission: Ensure the Docker user is in the kvm group.
• Devices: Load required kernel modules (kvm, tun).

Following the GitHub project’s issue tracker provides current solutions to version-specific problems.

The dockurr/macos image delivers a practical framework for running macOS virtual machines within Docker. When executed on Apple hardware, it provides a compliant, cost-effective option for testing, training, and software validation. With proper configuration, teams can achieve reliable macOS virtualisation backed by KVM performance and persistent containerised management.