# https://github.com/sickcodes/Docker-OSX Project Manual Generated at: 2026-07-06 18:45:48 UTC ## Table of Contents - [Project Overview and System Requirements](#page-overview) - [Container Images and Supported macOS Versions](#page-images) - [OpenCore Configuration, Plist Customization, and Serial Number Generation](#page-config) - [Kubernetes Deployment, Hardware Passthrough, and Troubleshooting](#page-deploy) ## Project Overview and System Requirements ### Related Pages Related topics: [Container Images and Supported macOS Versions](#page-images), [Kubernetes Deployment, Hardware Passthrough, and Troubleshooting](#page-deploy)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/sickcodes/Docker-OSX/blob/main/README.md) - [FAQ.md](https://github.com/sickcodes/Docker-OSX/blob/main/FAQ.md) - [CREDITS.md](https://github.com/sickcodes/Docker-OSX/blob/main/CREDITS.md) - [CHANGELOG.md](https://github.com/sickcodes/Docker-OSX/blob/main/CHANGELOG.md) - [Dockerfile](https://github.com/sickcodes/Docker-OSX/blob/main/Dockerfile) - [docker-compose.yml](https://github.com/sickcodes/Docker-OSX/blob/main/docker-compose.yml) - [customize](https://github.com/sickcodes/Docker-OSX/blob/main/customize) - [entrypoint.sh](https://github.com/sickcodes/Docker-OSX/blob/main/entrypoint.sh) - [Makefile](https://github.com/sickcodes/Docker-OSX/blob/main/Makefile) - [LICENSE](https://github.com/sickcodes/Docker-OSX/blob/main/LICENSE)
# Project Overview and System Requirements ## Purpose and Scope Docker-OSX is a project that ships pre-built, near-stock macOS container images running inside QEMU, wrapped in Docker. The stated goal is to provide users with a reproducible, scriptable way to launch macOS (Catalina through Sonoma) for research, reverse engineering, security testing, and continuous integration, without owning Apple hardware (`Source: [README.md:1-40]()`). The repository combines three moving parts: - A containerized QEMU harness that boots an unmodified macOS `.iso`/`.img` recovered via `dmg2img`-style workflows. - A handful of wrapper scripts (`entrypoint.sh`, `customize`, `Launch.sh`) that expose flags for CPU, RAM, disk size, display, USB passthrough, and headless mode. - A set of "naked" base images and `auto` build helpers that let users rebuild macOS installers from scratch inside the container (`Source: [CREDITS.md:1-60]()`). Community issue #799 ("Docker Image disappeared") and #858 ("Docker images `naked`, `auto` etc do not exist") show that the published image registry changed several times; users currently default to `docker pull sickcodes/docker-osx:latest` (`Source: [CHANGELOG.md:1-120]()`). ## High-Level Architecture The runtime pipeline is straightforward: the host provides `/dev/kvm` plus nested virtualization flags; Docker mounts the macOS image and a shared `disk.img` into a privileged container; `entrypoint.sh` invokes QEMU with the arguments declared via environment variables such as `RAM`, `CPU`, `DISPLAY`, `USBPASSTHROUGH`, and `HEADLESS` (`Source: [entrypoint.sh:1-80]()`). On first boot, a `Launch.sh` trigger generates a `disk.img`, registers a `Launch.sh` autostart, and reboots into the freshly initialized install (`Source: [customize:1-60]()`). ```mermaid flowchart LR A[Host kernel
KVM + ignore_msrs] --> B[Docker engine] B --> C[Container: sickcodes/docker-osx] C --> D[entrypoint.sh] D --> E[QEMU -machine q35
-cpu host,vendor=GenuineIntel] E --> F[macOS .img on shared volume] F --> G[Headless VNC / SPICE display] ``` This layering is why the project only works on Linux hosts with hardware virtualization; the container itself does not provide virtualization, it merely orchestrates QEMU's access to `/dev/kvm` (`Source: [README.md:40-120]()`). ## System Requirements ### Host Hardware Because the project leans on KVM, the host CPU must expose hardware virtualization extensions. The README and issue #685 both call out the same diagnostic incantation, summarized here: | Check | Required signal | |-------|-----------------| | `egrep -c '(svm|vmx)' /proc/cpuinfo` | ≥ 1 (VMX for Intel, SVM for AMD) | | `ls -lha /dev/kvm` | device present, user has rw access | | `qemu-system-x86_64 --version` | ≥ QEMU 5.x | | `free -mh` | at least 8 GB RAM (16 GB recommended for Sonoma) | | `df -h .` | ≥ 60 GB free for Catalina, more for newer releases | | `uname -a` | Linux 5.x+ (`Source: [README.md:60-180]()`) | The `Dockerfile` additionally installs `qemu-system-x86_64`, `qemu-utils`, `qemu-kvm`, and the kernel module scaffolding so that the container can boot QEMU even on distros where the host package set is incomplete (`Source: [Dockerfile:1-120]()`). ### Host Software The supported host is Linux. macOS hosts are explicitly out of scope because Apple's hypervisor.framework cannot expose `/dev/kvm` to nested x86_64 emulation, which is why issue #487 ("Featurerequest: arm64v8") remains an open limitation; the project emulates x86_64 guests and would need a complete QEMU/AArch64 redesign to target Apple Silicon (`Source: [FAQ.md:1-80]()`). Required host packages include Docker (≥ 20.10), `make`, `socat`, and either `libvirtd` or direct `/dev/kvm` access. The `Makefile` exposes convenience targets such as `make`, `make cpu=10 ram=16`, and `make naked` that translate into `docker run` invocations (`Source: [Makefile:1-60]()`). ### macOS Image Sourcing Docker-OSX does not bundle macOS. Users must supply either: - A pre-built image such as `sickcodes/docker-osx:naked`, which the project rebuilds for tags like `auto`, `big-sur`, `monterey`, `ventura`, and `sonoma` (`Source: [docker-compose.yml:1-40]()`). - A self-converted `.img` produced by `dmg2img` from a downloaded IPSW/Installer pkg, plus an OpenCore bootloader ISO (`Source: [README.md:120-200]()`). The CHANGELOG documents tag churn; only `latest` is consistently published, and the project's own issue tracker notes that some legacy tags are intentionally retired (`Source: [CHANGELOG.md:1-120]()`). ## Known Constraints Reflected by the Community Several recurring community threads map directly onto the architectural boundaries above: - **VRAM ceiling** (issue #688): the default QEMU machine definition exposes only 7 MB of VRAM. Increasing it requires editing `-device vmware-svga` / `-vga vmware` parameters in `entrypoint.sh`, not a configuration file (`Source: [FAQ.md:80-140]()`). - **Audio / GTK failures** (issue #685): these originate when the host lacks ALSA, PulseAudio, or GTK initialization for the QEMU GUI; the FAQ recommends installing the corresponding `-dev` packages (`Source: [FAQ.md:60-120]()`). - **Kernel module / ACL problems** (issue #685): the container expects to read and write `/dev/kvm`; if the host ACLs exclude the docker user, the entrypoint aborts (`Source: [entrypoint.sh:40-100]()`). - **Image availability** (issues #799, #858): users are steered toward `docker pull sickcodes/docker-osx:latest` and the `make` / `make build` recipes rather than obsolete tags (`Source: [CHANGELOG.md:60-140]()`). Together these constraints frame Docker-OSX as a Linux-only, KVM-dependent research environment: powerful for scripted CI of macOS workloads, but bounded by hardware, virtualization, and Apple's licensing stance on running macOS outside Apple hardware (`Source: [LICENSE:1-30]()`). --- ## Container Images and Supported macOS Versions ### Related Pages Related topics: [Project Overview and System Requirements](#page-overview), [OpenCore Configuration, Plist Customization, and Serial Number Generation](#page-config)
Related Source Files The following source files were used to generate this page: - [Dockerfile](https://github.com/sickcodes/Docker-OSX/blob/main/Dockerfile) - [Dockerfile.auto](https://github.com/sickcodes/Docker-OSX/blob/main/Dockerfile.auto) - [Dockerfile.naked](https://github.com/sickcodes/Docker-OSX/blob/main/Dockerfile.naked) - [Dockerfile.naked-auto](https://github.com/sickcodes/Docker-OSX/blob/main/Dockerfile.naked-auto) - [vnc-version/Dockerfile](https://github.com/sickcodes/Docker-OSX/blob/main/vnc-version/Dockerfile) - [vnc-version/Dockerfile.nakedvnc](https://github.com/sickcodes/Docker-OSX/blob/main/vnc-version/Dockerfile.nakedvnc)
# Container Images and Supported macOS Versions Docker-OSX distributes macOS as a set of containerized QEMU images. Each Dockerfile in the repository builds a tagged image that targets a specific macOS release, automation level, and display mechanism. Understanding the matrix of `Dockerfile`, base image, `SHORTNAME`, and runtime variables is essential before pulling or rebuilding an image. Community issue [#799](https://github.com/sickcodes/Docker-OSX/issues/799) reflects recurring user confusion when tags such as `sickcodes/docker-osx:sonoma` disappear, and issue [#858](https://github.com/sickcodes/Docker-OSX/issues/858) shows users attempting to pull `auto`, `naked`, and other tags that do not exist on Docker Hub. ## Image Variants and Naming The repository exposes two top-level directories of images: the host-display set (root `Dockerfile*`) and the VNC-display set (`vnc-version/Dockerfile*`). Within each directory there are two flavors: a *full* image that downloads the macOS installer into a runtime hook, and a *naked* image that requires the user to attach a pre-existing base image via `BASE_IMAGE`. The four root-level Dockerfiles represent the matrix shown below. | Dockerfile | Display | Build Mode | Base Image Source | |---|---|---|---| | `Dockerfile` | Host X11 | Manual launch | Downloads installer at runtime | | `Dockerfile.auto` | Host X11 | Auto, no VNC | Downloads installer and boots automatically | | `Dockerfile.naked` | Host X11 | Manual launch | Mounts user-supplied `BASE_IMAGE` | | `Dockerfile.naked-auto` | Host X11 | Auto, no VNC | Mounts user-supplied `BASE_IMAGE` | | `vnc-version/Dockerfile` | noVNC web | Manual launch | Downloads installer at runtime | | `vnc-version/Dockerfile.nakedvnc` | noVNC web | Manual launch | Mounts user-supplied `BASE_IMAGE` | Each Dockerfile uses `ARG SHORTNAME` to select the macOS release. The default in `Dockerfile` is `big-sur` `Source: [Dockerfile:8-9]()`. The `ARG SHORTNAME` is consumed by environment variables declared later in the same file (for example `ENV SHORTNAME=${SHORTNAME}`) and propagated to the `ENTRYPOINT` helpers `Source: [Dockerfile:71-75]()`. The same `SHORTNAME` indirection is used in the VNC variants: `vnc-version/Dockerfile` declares `ARG SHORTNAME` with `ENV SHORTNAME ${SHORTNAME:-big-sur}` `Source: [vnc-version/Dockerfile:7-8]()`. ## Supported macOS Releases The `SHORTNAME` values that the Dockerfiles are expected to handle are aligned with Apple's installer naming convention. While the repository does not enumerate every legal value in one place, each Dockerfile lists the supported identifiers via `ARG` declarations and helper comments adjacent to `ENV` blocks. Common values observed across the root Dockerfiles include `big-sur`, `monterey`, `ventura`, and `sonoma` `Source: [Dockerfile:8-9]()`. The auto launcher maps the same set: `ENV SHORTNAME=${SHORTNAME:-big-sur}` `Source: [Dockerfile.auto:5-6]()`. The naked and naked-auto variants follow the identical pattern `Source: [Dockerfile.naked:5-6]()` and `Source: [Dockerfile.naked-auto:5-6]()`. The VNC Dockerfile uses the same default `big-sur` and inherits the same `SHORTNAME` lookup mechanism `Source: [vnc-version/Dockerfile:7-8]()`. The pull tag users must request is constructed as `sickcodes/docker-osx:${SHORTNAME}`, for example `sickcodes/docker-osx:sonoma` `Source: [Dockerfile:71-75]()`. This convention explains issues like #799 and #858: only the `latest` and the SHORTNAME-based tags are published from the default Dockerfile flow. Tags such as `auto`, `naked`, or `naked-auto` are built from their dedicated Dockerfiles and are not pushed under those names from the root namespace unless explicitly published by the maintainers. ## Build Arguments and Runtime Hooks Every Dockerfile in scope inherits from `sickcodes/osx:VERSION`, where `VERSION` is itself a build argument. In `Dockerfile.auto` this is `ARG VERSION=latest` then `FROM sickcodes/osx:${VERSION}` `Source: [Dockerfile.auto:3-4]()`. The same pattern recurs in the naked variants `Source: [Dockerfile.naked:3-4]()` and `Source: [Dockerfile.naked-auto:3-4]()`, while the VNC Dockerfile pins `ARG VERSION=latest` and inherits from `sickcodes/osx:naked` via its own flow `Source: [vnc-version/Dockerfile:5-9]()`. The naked variants additionally expect a `BASE_IMAGE` argument at runtime: `ARG BASE_IMAGE` flows into `ENV BASE_IMAGE=${BASE_IMAGE}` so the entry script can attach an existing qcow2 disk `Source: [Dockerfile.naked:5-7]()`. Runtime behavior is encoded by `CMD` and `ENTRYPOINT` declarations. The auto Dockerfile overrides `CMD` to drive an unattended boot: `CMD ["sudo", "-E", "/bin/bash", "/auto/boot.auto"]` `Source: [Dockerfile.auto:11-12]()`. The naked-auto Dockerfile uses a different entry: `CMD ["sudo", "-E", "/bin/bash", "/auto/boot-macOS.sh"]` `Source: [Dockerfile.naked-auto:11-12]()`. Manual-launch images delegate to the entry scripts inside the base image; for example, `Dockerfile` ends with `CMD ["/bin/bash", "-c", "trap 'kill -SIGTERM $$' EXIT; sudo -E -u sickcodes /bin/bash -c '/bin/bash /entrypoint.sh; tail -f /dev/null'"]` `Source: [Dockerfile:78-82]()`. The VNC variants swap in `/entrypointvnc.sh` instead `Source: [vnc-version/Dockerfile:23-27]()`. ## Selecting and Building an Image To build the canonical Sonoma host-display image, run `docker build -t docker-osx --build-arg SHORTNAME=sonoma .` from the repository root `Source: [Dockerfile:8-9]()`. To produce an unattended variant, use `Dockerfile.auto` with the same `--build-arg SHORTNAME=` and rely on the auto `ENTRYPOINT` `Source: [Dockerfile.auto:5-12]()`. To attach a pre-built disk, build `Dockerfile.naked` or `Dockerfile.naked-auto` and pass `--build-arg BASE_IMAGE=/path/to/disk.qcow2` (and `--build-arg SHORTNAME=`), which the entry scripts persist through `ENV BASE_IMAGE` `Source: [Dockerfile.naked:5-7]()`. For browser-based access, build from the `vnc-version/` directory using `vnc-version/Dockerfile` or `vnc-version/Dockerfile.nakedvnc`, which set the entry to `/entrypointvnc.sh` and default `SHORTNAME` to `big-sur` `Source: [vnc-version/Dockerfile:7-8]()`. Users running on Apple silicon or Raspberry Pi (issue [#487](https://github.com/sickcodes/Docker-OSX/issues/487)) should note that all Dockerfiles here target x86_64 QEMU images; no `arm64v8` Dockerfile is shipped in the root or `vnc-version` directories. --- ## OpenCore Configuration, Plist Customization, and Serial Number Generation ### Related Pages Related topics: [Container Images and Supported macOS Versions](#page-images), [Kubernetes Deployment, Hardware Passthrough, and Troubleshooting](#page-deploy)
Related Source Files The following source files were used to generate this page: - [custom/README.md](https://github.com/sickcodes/Docker-OSX/blob/main/custom/README.md) - [custom/config-custom.plist](https://github.com/sickcodes/Docker-OSX/blob/main/custom/config-custom.plist) - [custom/config-legacy.plist](https://github.com/sickcodes/Docker-OSX/blob/main/custom/config-legacy.plist) - [custom/config-nopicker-custom.plist](https://github.com/sickcodes/Docker-OSX/blob/main/custom/config-nopicker-custom.plist) - [custom/config-nopicker-legacy.plist](https://github.com/sickcodes/Docker-OSX/blob/main/custom/config-nopicker-legacy.plist) - [custom/generate-specific-bootdisk.sh](https://github.com/sickcodes/Docker-OSX/blob/main/custom/generate-specific-bootdisk.sh)
# OpenCore Configuration, Plist Customization, and Serial Number Generation ## Overview and Scope The `custom/` directory of Docker-OSX provides OpenCore bootloader configuration assets used to boot macOS inside QEMU-based containers. These assets solve a central Hackintosh problem: macOS expects specific SMBIOS data (serial numbers, board identifiers, ROM values) and ACPI/UEFI tweaks that ordinary QEMU defaults do not provide. By shipping pre-made OpenCore `config.plist` variants, Docker-OSX gives users a working macOS boot environment that can be further customized without rebuilding the container from scratch. The configurations are split along two axes: - **Boot picker behavior**: standard vs `nopicker` (silent boot straight into the picker default entry) - **Target macOS install flow**: `custom` (newer install flow) vs `legacy` (older install flow) A companion shell script, `generate-specific-bootdisk.sh`, integrates these plists when assembling a bootable disk image. `Source: [custom/README.md:1-50]()` ## Plist File Variants Docker-OSX ships four OpenCore configuration files, each tuned for a different combination of features: | File | Picker | Install Flow | Typical Use | |------|--------|--------------|-------------| | `config-custom.plist` | enabled | custom | Standard modern macOS install with picker UI | | `config-nopicker-custom.plist` | disabled | custom | Automated boot straight into custom install | | `config-legacy.plist` | enabled | legacy | Older install flow with picker UI | | `config-nopicker-legacy.plist` | disabled | legacy | Automated silent boot for legacy flow | `Source: [custom/config-custom.plist:1-50]()`, `[custom/config-legacy.plist:1-50]()`, `[custom/config-nopicker-custom.plist:1-50]()`, `[custom/config-nopicker-legacy.plist:1-50]()` Each plist follows OpenCore's standard top-level sections (`ACPI`, `Boot`, `Kernel`, `Misc`, `NVRAM`, `PlatformInfo`, `UEFI`). The `PlatformInfo` section is the most important for macOS identity: it carries the `SystemSerialNumber`, `MLB` (main logic board serial), `SystemUUID`, and `ROM` values. macOS uses these to register with Apple services such as iCloud and the App Store, so the values must be plausible for the chosen `SystemProductName` (e.g., `MacPro7,1`, `iMacPro1,1`). ## Customization Workflow Users typically customize the OpenCore plist in two ways: 1. **Edit a plist directly** for one-off changes, such as adjusting `ConsoleAttributes`, toggling entries in `Kernel > Add`/`Kernel > Patch`, or modifying `NVRAM` boot arguments like `-v`, `nv_disable=1`, or QEMU-specific hints. 2. **Use `custom/generate-specific-bootdisk.sh`** to build a tailored bootdisk image. This script reads an OpenCore plist (typically one of the four variants above) and assembles a disk image containing the bootloader, OpenCore drivers, and the macOS installer payload. The result is a deterministic bootable image that can be mounted as a container's primary disk. `Source: [custom/generate-specific-bootdisk.sh:1-80]()` Because the script consumes the same plist variants shipped in the directory, any change made to those plists propagates into the generated bootdisk without modifying the Docker image itself. This is the recommended path for users who want a stable, version-controlled OpenCore config alongside a specific macOS version. `Source: [custom/README.md:1-50]()` ## Serial Number Generation and SMBIOS Identity Although Docker-OSX ships fixed plists, the `custom/` workflow is explicitly designed so that users can substitute their own SMBIOS values. This matters because: - Apple blocks serial numbers already in production use, so each running macOS VM needs a unique synthetic serial. - iMessage, FaceTime, iCloud, and App Store registration depend on plausible SMBIOS data that matches the selected `SystemProductName`. - An invalid or duplicated serial causes Apple ID sign-in failures, which is a recurring community concern. The README in `custom/` documents how to edit `PlatformInfo` keys (`SystemSerialNumber`, `MLB`, `SystemUUID`, `ROM`) and re-run the bootdisk generator. Users who want fully randomized serials typically generate them offline using OpenCore's `macserial` tool or a similar SMBIOS generator, then patch the plist before invoking `generate-specific-bootdisk.sh`. `Source: [custom/README.md:1-50]()`, `[custom/generate-specific-bootdisk.sh:1-80]()` A typical flow is: edit `PlatformInfo` keys in `config-custom.plist` → run `generate-specific-bootdisk.sh` with the patched plist and a chosen macOS version → boot the resulting image inside Docker-OSX. Because the plist is reused across boots, the serial persists for the lifetime of that bootdisk image. ## Related Community Concerns - **Image availability** (issues #799, #858): Because bootdisk generation depends on pulling base images and OpenCore artifacts, registry outages or missing tags directly affect users running `generate-specific-bootdisk.sh`. The workflow described on this page assumes the base image is reachable. - **Platform requests** (issue #487: arm64v8): Customization of the plist alone cannot bridge architecture gaps; arm64 host support would require changes outside the current OpenCore configurations. - **Hardware tunables** (issue #688: increased VRAM): Adjustments like VRAM size are made via QEMU command-line arguments and matching OpenCore `DeviceProperties` entries, not via the plist's `PlatformInfo` section. - **Host configuration** (issue #685): Kernel module, KVM, and ALSA failures originate outside Docker-OSX but affect whether a customized OpenCore bootdisk can successfully launch macOS at all. --- ## Kubernetes Deployment, Hardware Passthrough, and Troubleshooting ### Related Pages Related topics: [Project Overview and System Requirements](#page-overview), [OpenCore Configuration, Plist Customization, and Serial Number Generation](#page-config)
Related Source Files The following source files were used to generate this page: - [docker-compose.yml](https://github.com/sickcodes/Docker-OSX/blob/main/docker-compose.yml) - [helm/README.md](https://github.com/sickcodes/Docker-OSX/blob/main/helm/README.md) - [helm/Chart.yaml](https://github.com/sickcodes/Docker-OSX/blob/main/helm/Chart.yaml) - [helm/values.yaml](https://github.com/sickcodes/Docker-OSX/blob/main/helm/values.yaml) - [helm/Dockerfile](https://github.com/sickcodes/Docker-OSX/blob/main/helm/Dockerfile) - [helm/INSTALL-QEMU-AND-GPU-IOMMU.md](https://github.com/sickcodes/Docker-OSX/blob/main/helm/INSTALL-QEMU-AND-GPU-IOMMU.md)
# Kubernetes Deployment, Hardware Passthrough, and Troubleshooting Docker-OSX ships with two primary deployment paths: a `docker-compose.yml` for single-host runs and a Helm chart under `helm/` for orchestrating the macOS/QEMU workload on Kubernetes. Because the container ultimately boots real macOS through QEMU, almost every failure mode surfaces at the intersection of container plumbing, Kubernetes scheduling, and host-level hardware passthrough (KVM, GPU, and IOMMU). This page consolidates how the project expects you to deploy it, what hardware you must expose, and the recurring errors the community has reported. ## Deployment Surfaces The project advertises itself as a Docker-first image, but it also packages a Helm chart so the same container can be scheduled on a Kubernetes cluster. The chart's metadata, version, and maintainer information live in `helm/Chart.yaml`, while every tunable parameter (image repository, tag, resources, device paths, environment overrides) is exposed through `helm/values.yaml` `Source: [helm/values.yaml:1-200]()`. The `helm/Dockerfile` rebuilds the runtime image that the chart deploys, and `helm/README.md` documents the supported values, prerequisites, and install commands `Source: [helm/README.md:1-120]()`. For non-Kubernetes hosts, `docker-compose.yml` provides the equivalent run-line: a single `privileged`-mode container with the KVM device mapped, an optional VNC/noVNC port range, and the boot image as a volume `Source: [docker-compose.yml:1-80]()`. Both paths converge on the same QEMU invocation inside the container, so the troubleshooting matrix below applies to both. ## Kubernetes (Helm) Deployment Installing the chart follows the standard Helm workflow. The maintainers assume you have a working cluster node, the `kubectl` and `helm` CLIs, and host packages installed for KVM, VFIO, and (optionally) GPU passthrough — these are spelled out in `helm/INSTALL-QEMU-AND-GPU-IOMMU.md` `Source: [helm/INSTALL-QEMU-AND-GPU-IOMMU.md:1-90]()`. Typical install steps are: ```bash helm repo add sickcodes https://sickcodes.github.io/Docker-OSX helm install docker-osx sickcodes/docker-osx -f values.yaml ``` The `values.yaml` file is where most users will tune the deployment. Common keys include the image tag (defaulting to `latest`), the macOS `SHORTNAME` build arg, the number of CPU cores, RAM allocation, disk size, and the host paths for `/dev/kvm` and any GPU/IOMMU devices. Resource requests and limits on the pod control how aggressively the scheduler can bin-pack the workload `Source: [helm/values.yaml:1-200]()`. Because the container runs in `privileged: true` with `hostPID`/`hostIPC`, the chart's `securityContext` block is the only gate between the QEMU process and the host kernel; do not relax it. ## Hardware Passthrough: KVM, GPU, and IOMMU Docker-OSX is fundamentally an x86_64 macOS-on-QEMU harness, so it requires hardware virtualization on the host. The single most important device is `/dev/kvm`, which must be read/writable by the container `Source: [docker-compose.yml:20-40]()`. The Helm chart exposes the same path through `values.yaml` (commonly a `devices` or `extraVolumeMounts` block) so the pod's security context can mount it `Source: [helm/values.yaml:1-200]()`. For GPU passthrough, `helm/INSTALL-QEMU-AND-GPU-IOMMU.md` documents the full chain: enable IOMMU in firmware, load the `vfio-pci` and `vfio_iommu_type1` modules, bind the GPU to `vfio-pci` via its PCI ID, and confirm the device node appears under `/dev/vfio/`. The container then receives that device via the chart's device list, and QEMU inside the image attaches it with `-device vfio-pci,host=...`. The same file also covers ALSA audio passthrough and libvirt coexistence — both are common stumbling blocks. The architecture can be sketched as: ```mermaid flowchart LR A[Kubernetes Node] --> B[Helm Chart Pod] B --> C[Privileged Container] C --> D[QEMU] D --> E[macOS VM] A -- /dev/kvm --> C A -- /dev/vfio/* --> C A -- libvirt/ALSA --> C C -- VNC/noVNC --> F[Client Browser] ``` ## Troubleshooting Common Failures Several issues surface repeatedly in the issue tracker and are worth pre-empting. - **Image pull failures ("repository does not exist", tags like `:auto` or `:naked` missing).** The Docker Hub namespace only publishes a small set of tags, and `:latest` is the canonical one. The build path shown in issue #799 (`docker build -t docker-osx --build-arg SHORTNAME=sonoma .`) is the supported workaround `Source: [docker-compose.yml:1-80]()`. Confirm the exact tag in `helm/values.yaml` matches a published one before installing the chart. - **ARM hosts (Apple Silicon, Raspberry Pi).** The image is x86_64-only because it depends on QEMU's x86 system emulator and KVM acceleration; ARM64 support is tracked in #487 and is not yet available in `helm/Dockerfile` `Source: [helm/Chart.yaml:1-40]()`. - **KVM not detected inside the container.** Run the diagnostic block from #685 (`uname -a`, `ls -lha /dev/kvm`, `egrep -c '(svm|vmx)' /proc/cpuinfo`, `qemu-system-x86_64 --version`) and verify the pod is scheduled on a node whose `values.yaml` mounts `/dev/kvm` with the correct group/UID `Source: [helm/INSTALL-QEMU-AND-GPU-IOMMU.md:1-90]()`. - **Low VRAM (7 MB) inside macOS.** This is the default QEMU VGA configuration; increase it with `-device vmware-svga,vgamem_mb=...` or a custom QEMU command, as discussed in #688. - **Audio, ACL, or GTK errors.** These usually trace back to missing host packages (`libpulse0`, `libgtk-3-0`) or to the container not being privileged; both are prerequisites in `helm/INSTALL-QEMU-AND-GPU-IOMMU.md` `Source: [helm/INSTALL-QEMU-AND-GPU-IOMMU.md:1-90]()`. When in doubt, reproduce the failure with the `docker-compose.yml` service first; it isolates host-level issues (KVM, IOMMU, libvirt) from cluster-level ones (RBAC, device plugin, pod security policies), and the same fix then carries over to the Helm chart through `values.yaml`. --- --- ## Pitfall Log Project: sickcodes/Docker-OSX Summary: Found 21 structured pitfall item(s), including 7 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification. ## 1. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/526 ## 2. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/904 ## 3. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/914 ## 4. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/413 ## 5. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/923 ## 6. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/844 ## 7. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/666 ## 8. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: runtime_trace - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Repro command: `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` - Evidence: identity.distribution | https://github.com/sickcodes/Docker-OSX ## 9. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/799 ## 10. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/547 ## 11. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/531 ## 12. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/918 ## 13. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/543 ## 14. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/924 ## 15. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/402 ## 16. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/sickcodes/Docker-OSX ## 17. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/sickcodes/Docker-OSX ## 18. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/sickcodes/Docker-OSX ## 19. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/sickcodes/Docker-OSX ## 20. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/sickcodes/Docker-OSX ## 21. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/sickcodes/Docker-OSX