### Xcode Installation and Configuration Commands

Source: https://github.com/sickcodes/docker-osx/wiki/Downloading-and-installing-xcode-headless---scriptless

A series of shell commands to expand the downloaded Xcode .xip file, move it to the Applications directory, reset Xcode command-line tools, accept the license, and run initial setup.

```shell
xip --expand Xcode.xip
sudo cp Xcode.app /Applications
sudo rm /Library/DeveloperCommandLineTools && xcode-select -r
sudo xcodebuild -license accept
sudo xcodebuild -runFirstLaunch
DevToolsSecurity -enable
```

--------------------------------

### Docker Container Runtime - Quick Start Mode

Source: https://context7.com/sickcodes/docker-osx/llms.txt

This mode initiates a fresh macOS installation within a Docker container, downloading official installers and configuring a virtual disk.

```APIDOC
## Docker Container Runtime - Quick Start Mode

### Description
Starts a fresh macOS installation (e.g., Sequoia) within a Docker container. This mode downloads the BaseSystem, creates a virtual disk, and boots into the macOS installer GUI. SSH is available on port 50922.

### Method
`docker run`

### Endpoint
`sickcodes/docker-osx:latest`

### Parameters
#### Environment Variables
- **DISPLAY** (string) - Optional - The display to use for the GUI (e.g., `${DISPLAY:-:0.0}`).
- **SHORTNAME** (string) - Required - The short name of the macOS version to install (e.g., `sequoia`).
- **RAM** (integer) - Optional - The amount of RAM to allocate to the VM (e.g., `8`).
- **SMP** (integer) - Optional - The number of SMP processors to allocate (e.g., `4`).
- **CORES** (integer) - Optional - The number of CPU cores to allocate (e.g., `4`).
- **WIDTH** (integer) - Optional - The screen width for the VM (e.g., `1920`).
- **HEIGHT** (integer) - Optional - The screen height for the VM (e.g., `1080`).

### Request Example
```bash
docker run -it \
    --device /dev/kvm \
    -p 50922:10022 \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -e "DISPLAY=${DISPLAY:-:0.0}" \
    -e "SHORTNAME=sequoia" \
    -e "RAM=8" \
    -e "SMP=4" \
    -e "CORES=4" \
    -e "WIDTH=1920" \
    -e "HEIGHT=1080" \
    sickcodes/docker-osx:latest
```

### Response
#### Success Response (Container Started)
- The container will download necessary files and boot into the macOS installer.
- SSH server will be available on `localhost:50922`.

#### Response Example
```
# Output indicating download progress and VM boot sequence
# SSH into the VM using: ssh root@localhost -p 50922 (initial password is often empty or 'alpine')
```
```

--------------------------------

### Docker Run: Quick Start Fresh macOS Sequoia Installation

Source: https://context7.com/sickcodes/docker-osx/llms.txt

Starts a fresh macOS Sequoia installation within a Docker container. This mode downloads the base system, creates a virtual disk, and boots into the macOS installer GUI. It requires KVM access and exposes the GUI via X11 forwarding. SSH is available on port 50922.

```bash
docker run -it \
    --device /dev/kvm \
    -p 50922:10022 \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -e "DISPLAY=${DISPLAY:-:0.0}" \
    -e SHORTNAME=sequoia \
    -e RAM=8 \
    -e SMP=4 \
    -e CORES=4 \
    -e WIDTH=1920 \
    -e HEIGHT=1080 \
    sickcodes/docker-osx:latest
```

--------------------------------

### Download Xcode .xip using wget and Cookies

Source: https://github.com/sickcodes/docker-osx/wiki/Downloading-and-installing-xcode-headless---scriptless

This snippet shows how to download the Xcode .xip file using wget by providing authentication cookies. It assumes you have Homebrew installed and have extracted the ADCDownloadAuth cookie value from your browser.

```shell
echo ".apple.com\tTRUE\t/\tFALSE\t1679146596\tADCDownloadAuth [cookie value]" > cookies.txt
brew install wget
wget --load-cookies cookies.txt [xip download link]
```

--------------------------------

### Docker Compose Deployment Example

Source: https://context7.com/sickcodes/docker-osx/llms.txt

Provides a Docker Compose file structure for orchestrating multi-container Docker deployments. This configuration simplifies the setup and management of services by defining networks, volumes, and service dependencies in a declarative YAML format. It is particularly useful for setting up consistent and repeatable macOS environments within Docker.

```yaml
version: "3.8"
services:
  docker-osx:
    image: "sickcodes/docker-osx:latest"
    privileged: true
    container_name: "docker-osx"
    volumes:
      - /tmp/.X11-unix:/tmp/.X11-unix
      - "${PWD}/config:/config"
      - "${PWD}/bootdisk:/bootdisk"
    ports:
      - "50922:10022"
    environment:
      - DISPLAY=${DISPLAY:-:0.0}
      - DEVICE_MODEL=${DEVICE_MODEL:-}
      - SERIAL=${SERIAL:-}
      - BOARD_SERIAL=${BOARD_SERIAL:-}
      - UUID=${UUID:-}
      - MAC_ADDRESS=${MAC_ADDRESS:-}
      - BOOTDISK=/bootdisk/custom-boot.qcow2
      - NOPICKER=true
      - GENERATE_UNIQUE=true
    devices:
      - /dev/kvm
networks:
  default:
    name: docker-osx-network
```

--------------------------------

### Install Ninja Build Tool (Python)

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/INSTALL-QEMU-AND-GPU-IOMMU.md

Installs the Ninja build system using pip3, a required dependency for building QEMU from source. Ensure pip3 is installed and updated on your system.

```bash
pip3 install ninja
```

--------------------------------

### Configure SourceKit-LSP Path for Remote Development

Source: https://github.com/sickcodes/docker-osx/wiki/Downloading-and-installing-xcode-headless---scriptless

This command helps in configuring the SourceKit-LSP path, which is necessary for remote development with Swift using VSCode. It uses xcrun to find the correct path for the SourceKit-LSP executable.

```shell
xcrun --find sourcekit-lsp
```

--------------------------------

### Configure libvirt Repository (CentOS 7)

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/INSTALL-QEMU-AND-GPU-IOMMU.md

Adds the official CentOS 7 virt repository for installing the latest libvirt packages. This command enables access to pre-compiled libvirt libraries, simplifying the installation process.

```bash
yum-config-manager --nogpgcheck --add-repo http://mirror.centos.org/centos/7/virt/x86_64/libvirt-latest/
```

--------------------------------

### Install libvirt (CentOS 7)

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/INSTALL-QEMU-AND-GPU-IOMMU.md

Installs the libvirt virtualization management library using yum. libvirt is crucial for managing virtual machines and interacting with hypervisors like QEMU.

```bash
yum install libvirt -y
```

--------------------------------

### Verify libvirt and QEMU Version

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/INSTALL-QEMU-AND-GPU-IOMMU.md

Checks the installed versions of libvirt and QEMU using the 'virsh' command. This helps confirm that the installation was successful and that the versions are compatible.

```bash
virsh -c qemu:///system version --daemon
```

--------------------------------

### Install QEMU Dependencies (CentOS 7)

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/INSTALL-QEMU-AND-GPU-IOMMU.md

Installs necessary development packages for building QEMU on CentOS 7. This includes Python, glib2-devel, and cairo-devel, which are essential for QEMU's compilation process.

```bash
sudo yum install python glib2-devel cairo-devel -y
```

--------------------------------

### fetch-macOS.py - macOS Installer Downloader

Source: https://context7.com/sickcodes/docker-osx/llms.txt

A Python script used to download official macOS installers directly from Apple's servers, supporting various versions and output formats.

```APIDOC
## fetch-macOS.py - macOS Installer Downloader

### Description
`fetch-macOS.py` is a utility script designed to download official macOS installer applications directly from Apple's software update servers. It supports downloading specific versions, the latest available version, and offers options for compression and raw image output.

### Method
`./fetch-macOS.py` (executable script)

### Endpoint
N/A (Local script execution)

### Parameters
#### Command Line Arguments
- **--version** (string) - Required - Specifies the macOS version to download. Use `latest` for the newest version, or a specific version string (e.g., `10.15.7`, `13.0.0`).
- **--workdir** (string) - Optional - The directory where the installer will be downloaded and processed (e.g., `./downloads`).
- **--list-versions** - Optional - Lists all available macOS versions that can be downloaded.
- **--compress** - Optional - Downloads and compresses the installer (default behavior for installer apps).
- **--raw** - Optional - Downloads the installer as a raw disk image.

### Request Example
```bash
# Download the latest macOS installer to the 'downloads' directory
./fetch-macOS.py --version latest --workdir ./downloads

# Download macOS Catalina (10.15.7) as a raw image
./fetch-macOS.py --version 10.15.7 --raw --workdir ./catalina_raw

# List all supported macOS versions
./fetch-macOS.py --list-versions
```

### Response
#### Success Response (Download Complete)
- The script downloads the specified macOS installer application or raw image to the designated work directory.

#### Response Example (Output)
```
# Example output for downloading an installer:
# Downloading BaseSystem.dmg from https://example.com/swupdate/... 
# Downloading InstallAssistant.pkg from https://example.com/swupdate/... 
# Creating compressed DMG...
# macOS_13.0.0.dmg saved to ./downloads/macOS_13.0.0.dmg

# Example output for --list-versions:
# Available versions:
# - 13.6.1 (Ventura)
# - 12.7.0 (Monterey)
# - 11.7.10 (Big Sur)
# ...
```
```

--------------------------------

### Build QEMU from Source

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/INSTALL-QEMU-AND-GPU-IOMMU.md

Clones the QEMU repository, configures the build with debug options, and compiles QEMU from source. This process ensures the latest version is installed and allows for debugging capabilities. Adjust the '-j' flag based on your system's CPU cores.

```bash
git clone git://git.qemu.project.org/qemu.git
cd qemu
mkdir -p bin/debug/native
cd bin/debug/native
../../../configure --enable-debug
make -j24
make install
```

--------------------------------

### Build Big Sur Naked Image (Minimal)

Source: https://context7.com/sickcodes/docker-osx/llms.txt

This command builds a minimal Docker image for 'big-sur' using the 'Dockerfile.naked'. The 'naked' variant typically provides a streamlined setup without additional utilities.

```bash
# Build Big Sur naked image (minimal)
docker build -t docker-osx-bigsur-naked \
    --build-arg SHORTNAME=big-sur \
    -f Dockerfile.naked .
```

--------------------------------

### Check Kernel Command Line Parameters

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/INSTALL-QEMU-AND-GPU-IOMMU.md

Verifies that the IOMMU-related kernel parameters have been correctly applied by examining the contents of `/proc/cmdline`. This step is crucial after updating the GRUB configuration.

```bash
cat /proc/cmdline
```

--------------------------------

### fetch-macOS.py: Download macOS Installers

Source: https://context7.com/sickcodes/docker-osx/llms.txt

A Python script used to download official macOS installers directly from Apple's servers. It supports downloading the latest release, specific versions, and offers options for compressed or raw image formats. The script requires a working directory to store the downloaded files.

```bash
# Download latest macOS installer
./fetch-macOS.py --version latest --workdir ./downloads

# Download specific version
./fetch-macOS.py --version 10.15.7 --workdir ./catalina

# List available versions first
./fetch-macOS.py --list-versions

# Download Big Sur with compression (default)
./fetch-macOS.py --version 11.7.10 --compress

# Download Monterey as raw image
./fetch-macOS.py --version 12.7.0 --raw
```

--------------------------------

### Verify VFIO Driver Loading

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/INSTALL-QEMU-AND-GPU-IOMMU.md

Checks the kernel messages for any information related to the `vfio` driver. This helps confirm whether the `vfio-pci` driver has been loaded correctly and is ready for GPU passthrough.

```bash
dmesg | grep -i vfio
```

--------------------------------

### Install QEMU and Virtualization Dependencies for CentOS/RHEL/Fedora

Source: https://github.com/sickcodes/docker-osx/blob/master/README.md

Installs libvirt and qemu-kvm on CentOS, RHEL, and Fedora systems. These packages provide the necessary virtualization capabilities for running Docker-OSX containers.

```bash
# CENTOS RHEL FEDORA
sudo yum install libvirt qemu-kvm
```

--------------------------------

### Install KVM and Utilities in WSL2

Source: https://github.com/sickcodes/docker-osx/blob/master/README.md

Command to install necessary packages for KVM acceleration and virtualization within your WSL2 distribution. This includes bridge utilities, CPU checker, libvirt, and QEMU.

```bash
sudo apt -y install bridge-utils cpu-checker libvirt-clients libvirt-daemon qemu qemu-kvm
```

--------------------------------

### Rebuild Initramfs

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/INSTALL-QEMU-AND-GPU-IOMMU.md

Creates a backup of the current initramfs and then rebuilds it with the new `vfio-pci` configuration. This step is necessary for the changes to the kernel modules to take effect on the next boot. This process can be time-consuming.

```bash
cp -p /boot/initramfs-$(uname -r).img /boot/initramfs-$(uname -r).img.bak
dracut -f
```

--------------------------------

### Enable VFIO PCI Driver

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/INSTALL-QEMU-AND-GPU-IOMMU.md

Ensures that the `vfio-pci` module is loaded during the boot process by creating a configuration file in `/etc/modules-load.d/`. This is a prerequisite for the system to recognize and use the `vfio-pci` driver for device passthrough.

```bash
echo 'vfio-pci' > /etc/modules-load.d/vfio-pci.conf
```

--------------------------------

### Install QEMU and Virtualization Dependencies for Ubuntu/Debian

Source: https://github.com/sickcodes/docker-osx/blob/master/README.md

Installs QEMU, KVM, libvirt clients and daemon, bridge-utils, virt-manager, and libguestfs-tools on Ubuntu and Debian-based systems. These dependencies are crucial for enabling hardware virtualization and managing virtual machines.

```bash
# UBUNTU DEBIAN
sudo apt install qemu qemu-kvm libvirt-clients libvirt-daemon-system bridge-utils virt-manager libguestfs-tools
```

--------------------------------

### Identify GPU Hardware IDs

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/INSTALL-QEMU-AND-GPU-IOMMU.md

Uses the `lspci` command to list all PCI devices and filters the output to find the hardware IDs of NVIDIA devices. These IDs are required for configuring `vfio-pci` to claim the GPU for passthrough.

```bash
lspci -nn | grep -i nvidia
```

--------------------------------

### Install QEMU and Virtualization Dependencies for Arch Linux

Source: https://github.com/sickcodes/docker-osx/blob/master/README.md

Installs QEMU, libvirt, dnsmasq, virt-manager, bridge-utils, iptables-nft, and edk2-ovmf on Arch Linux systems. These packages are essential for running virtual machines and Docker containers that require hardware virtualization.

```bash
# ARCH
sudo pacman -S qemu libvirt dnsmasq virt-manager bridge-utils flex bison iptables-nft edk2-ovmf
```

--------------------------------

### Configure GRUB for IOMMU Passthrough

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/INSTALL-QEMU-AND-GPU-IOMMU.md

Modifies the GRUB bootloader configuration to enable IOMMU (Input-Output Memory Management Unit) support, which is essential for GPU passthrough. The `iommu=pt` and `intel_iommu=on` parameters are added to the kernel command line.

```bash
GRUB_CMDLINE_LINUX="... iommu=pt intel_iommu=on"
```

--------------------------------

### Install and Run usbfluxd on macOS Guest

Source: https://github.com/sickcodes/docker-osx/blob/master/README.md

Installs necessary dependencies, clones and builds usbfluxd, and then runs the service to connect to a host. It requires brew, git, and the usbfluxd repository. The output is a running usbfluxd service that allows USB device access.

```zsh
# on the guest
brew install make automake autoconf libtool pkg-config gcc libmobiledevice usbmuxd

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

./autogen.sh
make
sudo make install
```

--------------------------------

### Update KVM Device Permissions

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/INSTALL-QEMU-AND-GPU-IOMMU.md

Adjusts permissions and ownership for the KVM device to allow access for the root user within the kvm group. These commands are often necessary for libvirt to properly manage KVM instances.

```bash
chmod 660 -R /dev/kvm && chown 1000:1000 /dev/kvm
usermod -a -G kvm root
```

--------------------------------

### Set LimitMEMLOCK for libvirtd Service

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/INSTALL-QEMU-AND-GPU-IOMMU.md

Adds `LimitMEMLOCK=infinity` to the `libvirtd.service` systemd unit file. This explicitly sets the memory locking limit for the libvirtd daemon, ensuring it can allocate necessary memory for virtualization tasks.

```ini
[Unit]
Description=Virtualization daemon
...

[Service]
...
LimitMEMLOCK=infinity
```

--------------------------------

### Enable and Load KVM Kernel Module

Source: https://github.com/sickcodes/docker-osx/blob/master/README.md

Enables and starts the libvirtd and virtlogd services, ignores MSR exceptions for KVM, and loads the KVM kernel module. This is a critical step for ensuring hardware virtualization is properly configured and accessible.

```bash
sudo systemctl enable --now libvirtd
sudo systemctl enable --now virtlogd

echo 1 | sudo tee /sys/module/kvm/parameters/ignore_msrs

sudo modprobe kvm
```

--------------------------------

### Configure VFIO PCI IDs for GPU Passthrough

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/INSTALL-QEMU-AND-GPU-IOMMU.md

Specifies the hardware IDs of the GPU that should be managed by the `vfio-pci` driver. This file prevents other drivers from binding to the GPU, allowing it to be passed through to a virtual machine.

```bash
options vfio-pci ids=10de:1b81,10de:10f0
```

--------------------------------

### Set up xhost for Display Server Access (Bash)

Source: https://github.com/sickcodes/docker-osx/blob/master/README.md

Configures the X Window System host access control to allow connections from other machines or containers. Essential for GUI applications running in Docker. Includes package installation commands for different Linux distributions.

```bash
echo $DISPLAY
```

```bash
# ARCH
sudo pacman -S xorg-xhost
```

```bash
# UBUNTU DEBIAN
sudo apt install x11-server-utils
```

```bash
# CENTOS RHEL FEDORA
sudo yum install xorg-x11-server-utils
```

```bash
# then run
xhost +
```

--------------------------------

### Increase Memory Locking Limits for KVM Users

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/INSTALL-QEMU-AND-GPU-IOMMU.md

Modifies the `/etc/security/limits.conf` file to grant unlimited memory locking capabilities (`memlock`) to users in the `kvm` group. This is crucial for preventing memory-related errors during VM operation, especially with GPU passthrough.

```bash
@kvm            soft    memlock         unlimited
@kvm            hard    memlock         unlimited
```

--------------------------------

### Update GRUB2 Configuration

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/INSTALL-QEMU-AND-GPU-IOMMU.md

Regenerates the GRUB2 configuration file after modifying boot parameters. This command ensures that the changes made to `/etc/default/grub` are applied on the next boot. The output path may vary depending on the system's boot configuration.

```bash
grub2-mkconfig -o /boot/efi/EFI/clearos/grub.cfg
```

--------------------------------

### iPhone USB Passthrough with usbfluxd in Docker-OSX

Source: https://context7.com/sickcodes/docker-osx/llms.txt

Enables iPhone connectivity from within the macOS guest for iOS development. This setup involves starting usbmuxd on the host, running Docker-OSX, installing necessary tools inside the guest, and configuring usbfluxd to forward USB traffic.

```bash
# On Linux host: Start usbmuxd and expose it
sudo systemctl start usbmuxd
sudo socat tcp-listen:5000,fork unix-connect:/var/run/usbmuxd &

# Start Docker-OSX with network access
docker run -it \
    --device /dev/kvm \
    -p 50922:10022 \
    --add-host=host.docker.internal:host-gateway \
    -e RAM=16 \
    -e SMP=8 \
    sickcodes/docker-osx:auto

# Inside macOS guest, install dependencies
brew install make automake autoconf libtool pkg-config gcc libimobiledevice usbmuxd

# Clone and build usbfluxd
git clone https://github.com/corellium/usbfluxd.git
cd usbfluxd
./autogen.sh
make
sudo make install

# Connect to host's usbmuxd (172.17.0.1 is Docker bridge IP)
sudo launchctl unload /Library/LaunchDaemons/com.apple.usbmuxd.plist
export PATH=/usr/local/sbin:${PATH}
sudo usbfluxd -f -r 172.17.0.1:5000

# Plug iPhone into Linux host
# On Linux host, verify device detected
lsusb | grep iPhone

# Inside macOS guest, verify device visible
idevice_id -l

# Use Xcode or other tools normally
xcrun simctl list devices
```

--------------------------------

### Setup usbfluxd for iPhone USB Passthrough on Linux

Source: https://github.com/sickcodes/docker-osx/blob/master/README.md

This set of bash commands configures Linux to expose an iPhone/iPad's usbmuxd service over TCP port 5000, enabling USB passthrough to a macOS Docker container. It involves installing necessary packages (usbmuxd, socat, usbfluxd), starting system services, and running socat and usbfluxd in separate terminals. This method works on laptops and desktops.

```bash
# 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
sudo systemctl start usbmuxd
sudo avahi-daemon

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

# Terminal 3:
sudo usbfluxd -f -n
```

--------------------------------

### Generate Random Serial Numbers with DIY Installer and Custom Resolution

Source: https://github.com/sickcodes/docker-osx/blob/master/README.md

This command initiates a Docker-OSX container using the DIY installer, generating unique serial numbers automatically. It also sets a custom display resolution of 800x600. This is a convenient way to quickly start a macOS VM with randomized hardware identifiers and a specific screen size.

```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 WIDTH=800 \
    -e HEIGHT=600 \
    sickcodes/docker-osx:latest
```

--------------------------------

### Install WSL2 on Windows

Source: https://github.com/sickcodes/docker-osx/blob/master/README.md

Command to install the Windows Subsystem for Linux (WSL), which defaults to installing Ubuntu. Ensure you run this in an administrator PowerShell.

```bash
wsl --install
```

--------------------------------

### Start Docker Daemon using systemd (Bash)

Source: https://github.com/sickcodes/docker-osx/blob/master/README.md

Starts the Docker daemon using systemd. This is suitable for background operation and can be configured to start on boot. Dependencies: `systemctl` and `sudo` privileges.

```bash
sudo systemctl --start dockerd
```

```bash
sudo systemctl --enable --now dockerd
```

```bash
sudo nohup dockerd &
```

```bash
systemctl start docker
```

--------------------------------

### Automate macOS Builds and Tests

Source: https://context7.com/sickcodes/docker-osx/llms.txt

This script automates macOS boot processes for testing and CI/CD. It defines a series of macOS commands to be executed upon container startup, including package management, code cloning, dependency installation, testing, and building. Results can be accessed via SSH and artifacts downloaded using SCP.

```bash
# Run build commands automatically on boot
docker run -it \
    --device /dev/kvm \
    -p 50922:10022 \
    -e USERNAME=builduser \
    -e PASSWORD=build123 \
    -e OSX_COMMANDS="$(cat <<'EOF'\nset -e\n# Update Homebrew\nbrew update\n\n# Install Xcode command line tools\nxcode-select --install || true\n\n# Clone repository\ncd ~\ngit clone https://github.com/myorg/myapp.git\ncd myapp\n\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build app\nnpm run build\n\n# Output results\necho \"Build completed successfully\" > ~/build-status.txt\nls -lah ./dist/\nEOF\n)" \
    sickcodes/docker-osx:auto

# Expected behavior:
# - Boots to macOS
# - Auto-logs in as builduser
# - Executes all commands in OSX_COMMANDS
# - Commands run in shell context
# - Errors stop execution (set -e) 

# Access results via SSH
ssh builduser@localhost -p 50922 "cat ~/build-status.txt"
# Expected output: Build completed successfully

# Download build artifacts
scp -P 50922 builduser@localhost:~/myapp/dist/* ./artifacts/
```

--------------------------------

### Run macOS Container with Insecure VNC

Source: https://github.com/sickcodes/docker-osx/blob/master/README.md

This command starts a macOS container with VNC enabled for remote access. It maps VNC port 5999 and uses the `-e EXTRA="-display none -vnc 0.0.0.0:99,password=on"` argument to configure QEMU for VNC output. Note that this setup is not secure and is intended for local use only. You must interact with the QEMU console directly and ensure you change the VNC password.

```bash
docker run -i \
    --device /dev/kvm \
    -p 50922:10022 \
    -p 5999:5999 \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -e "DISPLAY=${DISPLAY:-:0.0}" \
    -e EXTRA="-display none -vnc 0.0.0.0:99,password=on" \
    sickcodes/docker-osx:big-sur

# type `change vnc password myvncusername` into the docker terminal and set a password
# connect to localhost:5999 using VNC
# qemu 6 seems to require a username for vnc now
```

--------------------------------

### Deploy Docker-OSX with Helm on Kubernetes

Source: https://context7.com/sickcodes/docker-osx/llms.txt

This section details deploying Docker-OSX on Kubernetes using Helm charts for scalable macOS build infrastructure. It includes adding the Helm repository, creating a custom values file for configuration (VNC, serial numbers, resources, persistence), installing the chart, managing deployments, and uninstalling.

```bash
# Add Helm repository
helm repo add docker-osx https://sickcodes.github.io/Docker-OSX/
helm repo update

# Create values file for customization
cat > my-values.yaml <<EOF
vnc:
  password: "myVncPass123"
  port: 8888

configPlist:
  MLB: "C02935401J9H69FAD"
  SystemSerialNumber: "C02YX0GHHX87"
  SystemUUID: "5CCB366D-9118-4C61-A00A-E5BAF3BED451"

resources:
  requests:
    memory: "16Gi"
    cpu: "8"
  limits:
    memory: "32Gi"
    cpu: "16"

qemu:
  ramSize: "16384M"
  cpuCount: "8"
  cpuCores: "8"

service:
  type: LoadBalancer
  ip: 192.168.1.100

persistence:
  enabled: true
  storageClass: "fast-ssd"
  size: "250Gi"
EOF

# Install chart
helm install macos-builder docker-osx/docker-osx \
    --values my-values.yaml \
    --namespace macos-builds \
    --create-namespace

# Check deployment status
kubectl get pods -n macos-builds
# Expected:
# NAME                           READY   STATUS    RESTARTS   AGE
# macos-builder-0                1/1     Running   0          5m

# View logs
kubectl logs -f macos-builder-0 -n macos-builds

# Port forward for local access
kubectl port-forward -n macos-builds macos-builder-0 50922:10022 5999:8888

# SSH into Kubernetes-hosted macOS
ssh user@localhost -p 50922

# VNC into Kubernetes-hosted macOS
vncviewer localhost:5999
# Password: myVncPass123

# Scale deployment (multiple macOS instances)
kubectl scale statefulset macos-builder --replicas=3 -n macos-builds

# Upgrade configuration
helm upgrade macos-builder docker-osx/docker-osx \
    --values my-values.yaml \
    --namespace macos-builds

# Uninstall
helm uninstall macos-builder -n macos-builds
```

--------------------------------

### Install X11 Apps in WSL2

Source: https://github.com/sickcodes/docker-osx/blob/master/README.md

Command to install the x11-apps package, which is required for graphical output when using X11 forwarding or WSLg.

```bash
sudo apt install x11-apps -y
```

--------------------------------

### Configure Docker Default Ulimits and Memlock

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/INSTALL-QEMU-AND-GPU-IOMMU.md

Appends a configuration to Docker's `daemon.json` to set default limits for open files (`nofile`) and memory locking (`memlock`). These settings ensure that Docker containers have sufficient resources, especially when running resource-intensive applications like VMs.

```json
{
    "default-ulimits": {
        "nofile": {
            "name": "nofile",
            "hard": 65536,
            "soft": 1024
        },
        "memlock":
        {
            "name": "memlock",
            "soft": -1,
            "hard": -1
        }
    }
}
```

--------------------------------

### Start Docker Daemon in Foreground (Bash)

Source: https://github.com/sickcodes/docker-osx/blob/master/README.md

Starts the Docker daemon in the foreground, allowing for direct interaction and debugging. This is a common method for interactive use. Dependencies: `sudo` privileges.

```bash
sudo dockerd
```

--------------------------------

### Load VFIO Modules on Boot

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/INSTALL-QEMU-AND-GPU-IOMMU.md

Ensures that necessary VFIO modules are loaded automatically during system boot. This involves creating or modifying the /etc/modules file to include vfio, vfio_iommu_type1, vfio_pci, and vfio_virqfd. After modification, initramfs must be rebuilt and the system rebooted for changes to take effect.

```shell
echo 'vfio
vfio_iommu_type1
vfio_pci
vfio_virqfd' > /etc/modules
```

```shell
cp -p /boot/initramfs-$(uname -r).img /boot/initramfs-$(uname -r).img.bak
dracut -f
```

--------------------------------

### Start and Attach to a Docker Container (Bash)

Source: https://github.com/sickcodes/docker-osx/blob/master/README.md

Starts a stopped Docker container and attaches the terminal's standard input, output, and error streams to it. Useful for interactive sessions with existing containers. Dependencies: Docker CLI.

```bash
docker start -ai abc123xyz567
```

```bash
docker start -ai -i <Replace this with your ID>
```

--------------------------------

### Set VFIO and KVM Permissions

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/INSTALL-QEMU-AND-GPU-IOMMU.md

Configures the necessary file permissions for VFIO and KVM devices, which is crucial for allowing user access to these resources. These commands adjust read/write permissions and ownership for /dev/kvm and the /dev/vfio directory, including specific IOMMU groups, to prevent permission-related errors during device passthrough.

```shell
chmod 660 -R /dev/kvm && chown 1000:1000 /dev/kvm
chmod 777 -R /dev/vfio && chown 1000:1000 -R /dev/vfio
```

--------------------------------

### Configure and Start usbfluxd Service

Source: https://github.com/sickcodes/docker-osx/blob/master/README.md

Configures the environment for usbfluxd by starting the usbmuxd service and setting the PATH. It then runs the usbfluxd daemon, connecting to a specified host IP and port. This is crucial for enabling USB over TCP connections.

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

--------------------------------

### Docker Run: Headless Mode with VNC Access

Source: https://context7.com/sickcodes/docker-osx/llms.txt

Starts Docker-OSX in headless mode, meaning no local GUI is displayed. Instead, it provides VNC server access, which is essential for remote management and server environments. A VNC password must be set via the QEMU monitor prompt within the container. Users can then connect using any VNC client.

```bash
# Start headless with VNC on port 5999
docker run -it \
    --device /dev/kvm \
    -p 50922:10022 \
    -p 5999:5999 \
    -e HEADLESS=true \
    -e EXTRA="-display none -vnc 0.0.0.0:99,password=on" \
    -e RAM=8 \
    -e SMP=4 \
    sickcodes/docker-osx:auto

# Container starts with QEMU monitor prompt
# Set VNC password at the (qemu) prompt:
change vnc password
# Enter password when prompted: mySecurePass123

# Connect from VNC client
# Address: localhost:5999
# Password: mySecurePass123

# Verify VNC connection from command line
vncviewer localhost:5999
```

--------------------------------

### Docker Container Runtime - Pre-installed Auto Mode

Source: https://context7.com/sickcodes/docker-osx/llms.txt

Launches a Docker container with a pre-installed macOS image that automatically logs in. This is ideal for automated testing and development workflows.

```APIDOC
## Docker Container Runtime - Pre-installed Auto Mode

### Description
Starts a pre-installed macOS image (e.g., Catalina) in a Docker container with automatic login. This mode is optimized for automated testing and development workflows, providing a ready-to-use desktop environment. SSH is available on port 50922.

### Method
`docker run`

### Endpoint
`sickcodes/docker-osx:auto`

### Parameters
#### Environment Variables
- **DISPLAY** (string) - Optional - The display to use for the GUI (e.g., `${DISPLAY:-:0.0}`).
- **USERNAME** (string) - Required - The username for auto-login (e.g., `testuser`).
- **PASSWORD** (string) - Required - The password for auto-login (e.g., `testpass123`).
- **HEADLESS** (boolean) - Optional - Set to `false` for GUI access, `true` for headless operation (default: `false`).
- **GENERATE_UNIQUE** (boolean) - Optional - If `true`, a unique serial number will be generated (default: `false`).
- **NETWORKING** (string) - Optional - Network adapter type (e.g., `vmxnet3`).

### Request Example
```bash
docker run -it \
    --device /dev/kvm \
    -p 50922:10022 \
    -p 5999:5999 \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -e "DISPLAY=${DISPLAY:-:0.0}" \
    -e "USERNAME=testuser" \
    -e "PASSWORD=testpass123" \
    -e "HEADLESS=false" \
    -e "GENERATE_UNIQUE=true" \
    -e "NETWORKING=vmxnet3" \
    sickcodes/docker-osx:auto
```

### SSH Connection Example
```bash
ssh testuser@localhost -p 50922
# Password: testpass123
```

### Response
#### Success Response (Container Started)
- The container boots directly into the macOS desktop with the specified user logged in.
- SSH server is available on `localhost:50922`.

#### Response Example (Inside macOS)
```
# Verify system information
sw_vers
# Expected output:
# ProductName:    macOS
# ProductVersion: 10.15.7
# BuildVersion:   19H15

# Verify serial number
ioreg -l | grep IOPlatformSerialNumber
# Shows generated unique serial number
```
```

--------------------------------

### Build docker-osx-vnc Docker Image

Source: https://github.com/sickcodes/docker-osx/blob/master/helm/README.md

This command builds the `sickcodes/docker-osx-vnc` Docker image using the Dockerfile located in the `helm` folder. Ensure you are in the root directory of the project before running this command. The built image is tagged as `latest`.

```bash
docker build \
    -t sickcodes/docker-osx-vnc:latest \
    -f helm/Dockerfile .

```

--------------------------------

### Persistent Storage and State Management for Docker-OSX

Source: https://context7.com/sickcodes/docker-osx/llms.txt

Covers methods for managing the state and persistence of the Docker-OSX container. This includes running with named containers for easy management, exporting disk images, committing changes to new images, and cleaning up old containers.

```bash
# Run with named container for easy management
docker run -it \
    --name macos-persistent \
    --device /dev/kvm \
    -p 50922:10022 \
    -e GENERATE_UNIQUE=true \
    sickcodes/docker-osx:auto

# After installation/configuration, stop container
docker stop macos-persistent

# Restart same container (fast boot, preserves state)
docker start -ai macos-persistent

# Export disk image for backup or reuse
docker exec macos-persistent cat /home/arch/OSX-KVM/mac_hdd_ng.img > macos-backup.img

# Verify exported image
qemu-img info macos-backup.img

# Commit container to new image
docker commit macos-persistent my-custom-macos:v1

# Create new container from committed image
docker run -it \
    --name macos-clone \
    --device /dev/kvm \
    -p 50923:10022 \
    my-custom-macos:v1

# List all Docker-OSX containers
docker ps -a --filter "ancestor=sickcodes/docker-osx:auto"

# Remove old containers
docker rm macos-persistent
```