MacDow

English | 한국어 | 日本語 | 简体中文 | Español

Native, open-source ARM64 virtual machine manager for Apple Silicon Macs. Windows 11 ARM64 and Linux ARM64 run on QEMU with Apple's HVF acceleration; macOS runs on Apple's Virtualization framework. Each VM is stored as a .macdowvm package.

Table of Contents

• Overview
• Features
• Requirements
• Quick Start
• Usage
• Architecture
• Building and Running
• Release Packaging
• Status
• Alpha Distribution
• Troubleshooting
• Contributing
• Security
• Changelog
• License and Third-Party Notices

Overview

MacDow is a native macOS application that lets you create and run ARM64 virtual machines on Apple Silicon. It is a single SwiftUI app built with Swift 6 and the Apple Virtualization framework. Windows 11 ARM64 and Linux ARM64 guests are powered by QEMU with Apple's Hypervisor.framework (accel=hvf) acceleration, while macOS guests use Apple's native VZVirtualMachine directly.

Every virtual machine is stored as a .macdowvm package directory containing its disk, UEFI/EFI variables, TPM state, and metadata. Windows and Linux packages reference the original installer ISO with a symbolic link, so the ISO is not embedded in exports. Installed VMs can be cloned, imported, and exported, but compatibility on another Mac still depends on the guest and host hardware.

MacDow is alpha software under active development.

Features

• Three guest families from one app
  • Windows 11 ARM64 (.iso via QEMU + HVF)
  • Linux ARM64 (.iso via QEMU + HVF)
  • macOS ARM64 (.ipsw restore image via Apple Virtualization)
• ARM64 ISO/IPSW validation — verifies bootaa64.efi presence, distinguishes Windows from Linux by checking sources/boot.wim, and validates macOS restore images through VZMacOSRestoreImage.
• EFI startup disk — a bundled startup.nsh boot helper is exposed to the guest and the Windows installation-media boot prompt is acknowledged automatically.
• Secure Boot and TPM 2.0 — each VM persists its own UEFI variable flash and TPM 2.0 state (swtpm) so Windows 11 Secure Boot / TPM requirements stay satisfied across reboots.
• Automatic Windows networking — Windows ISO detection downloads a pinned, integrity-checked Microsoft-attested ARM64 NetKVM driver and exposes it via Windows Setup's native $WinPEDriver$ discovery layout before OOBE.
• Embedded localhost-only noVNC display — guest installation runs through an embedded WebKit view using ramfb; no remote VNC surface is exposed.
• Full lifecycle — start / pause / resume / shut down / force stop.
• Saved state — pause-and-resume across app launches for macOS guests via VZVirtualMachine saved state.
• Clone, import, export — duplicate VMs, import .macdowvm packages, and export them for sharing or backup.
• Settings inspector — adjust CPU and NAT networking while a VM is stopped; memory and disk size are selected when the VM is created.
• Diagnostics export — produce a support bundle with system info and VM summaries. Virtual disks and personal files are never included.
• English and Korean localization.
• No analytics — MacDow does not collect analytics or upload diagnostics.

Requirements

• Apple Silicon Mac
• macOS 15 or newer
• Swift 6 / Xcode 16 or newer (for building from source)
• A supported ARM64 ISO (Windows 11 ARM64 or Linux ARM64) or a macOS restore IPSW
• QEMU 11 and swtpm for Windows/Linux guests (brew install qemu swtpm). The current alpha DMG does not bundle these runtimes.

Quick Start

Important

The current alpha is not notarized by Apple. After copying MacDow to Applications, try to open it once. If macOS blocks it, open Apple menu ▸ System Settings ▸ Privacy & Security, scroll down to Security, and click Open Anyway next to MacDow. Click Open Anyway again, enter your Mac login password, and click OK. This button is available for about one hour after the blocked launch attempt.

git clone https://github.com/flyingsquirrel0419/MacDow.git
cd MacDow
brew install qemu swtpm        # required for Windows/Linux guests
./script/build_and_run.sh --verify

The --verify flag launches the app and confirms the process is running. VM execution requires the com.apple.security.virtualization entitlement, which the bundle script applies automatically.

Usage

1. Launch MacDow. The VM library lives at ~/Library/Application Support/MacDow/Virtual Machines.
2. Click New VM (or File ▸ New Virtual Machine…, ⌘N).
3. Enter a name and choose an ARM64 .iso or macOS .ipsw installation image. Direct download links for Windows 11 ARM64, Ubuntu, and macOS IPSW are provided in the creator sheet.
4. Optionally expand Advanced Hardware to set CPU, memory, disk, and NAT networking. Defaults are derived from your Mac: 2–8 CPU cores, 4–8 GiB RAM, 64 GiB disk, NAT network enabled.
5. Click Create. The installer ISO is validated and the .macdowvm package is created.
6. Select the VM in the sidebar and click Start Virtual Machine.
7. For Windows/Linux, the guest installer appears in the embedded noVNC display and the boot prompt is acknowledged automatically. For macOS, the restore runs through Apple's installer and the native display opens.

See docs/USAGE.md for the full end-user guide including hardware, networking, saved state, import/export, and diagnostics.

Architecture

flowchart LR
    UI["SwiftUI Views\n(Sidebar / Detail / Creator / Inspector)"] --> Store["VMStore\n(Observation)"]
    Store --> Backend{"Guest kind?"}
    Backend -- "Windows / Linux" --> QEMU["QEMUBackend\n(QEMU + HVF + swtpm + noVNC)"]
    Backend -- "macOS" --> Apple["AppleVirtualizationBackend\n(VZVirtualMachine)"]
    QEMU --> Pkg["VMPackage (.macdowvm)\nDisk.img · UEFI_VARS.fd · TPM · metadata.json"]
    Apple --> Pkg
    Pkg --> Lib[("~/Library/Application Support/MacDow/Virtual Machines")]

Loading

Key source layout under Sources/MacDow/:

Path	Responsibility
App/MacDowApp.swift	App entry point, scene, menu commands
Models/VMModels.swift	VirtualMachineRecord, VMHardwareConfiguration, guest/backend/capability enums
Models/VMError.swift	Typed errors and byte-size formatting
Services/VMBackend.swift	VMBackend protocol both backends implement
Services/QEMUBackend.swift	QEMU + HVF + swtpm + noVNC orchestration
Services/AppleVirtualizationBackend.swift	VZVirtualMachine-based backend for macOS
Services/ISOValidator.swift	ARM64 ISO validation via hdiutil/bsdtar
Services/VMPackage.swift	.macdowvm package layout and metadata I/O
Stores/VMStore.swift	@Observable store: create/start/stop/clone/import/export/settings
Views/	SwiftUI: ContentView, SidebarView, VMDetailView, VMCreationView, VMSettingsInspector, AppSettingsView, VirtualMachineDisplay, QEMUDisplayView
Resources/Bootstrap/startup.nsh	EFI boot helper for installers
Resources/SecureBoot/	AAVMF firmware and variable template
Resources/NoVNC/	Embedded noVNC client (localhost-only)

Guest selection is automatic: the ISO validator detects the guest kind, and macOS restore images are routed to the Apple Virtualization backend. Windows and Linux always use QEMU; saved state currently works only with the Apple backend.

Building and Running

Build, sign with the bundled entitlement, and launch:

./script/build_and_run.sh --verify

Other modes supported by the script:

./script/build_and_run.sh              # build and open
./script/build_and_run.sh --debug      # build and launch under lldb
./script/build_and_run.sh --logs      # stream macOS unified logs for MacDow
./script/build_and_run.sh --telemetry # stream logs for org.macdow.MacDow subsystem

The app is staged at ~/Library/Developer/MacDow/Build/MacDow.app and symlinked into dist/MacDow.app.

To run the test suite:

swift test

Tests cover VirtualMachineRecord round-trip encoding, recommended-hardware bounds, package-version rejection, and ISO-extension validation.

Release Packaging

Production DMGs are signed, notarized, and stapled by script/package_release.sh. It requires two environment variables:

export DEVELOPER_ID_APPLICATION="Developer ID Application: Your Name (TEAMID)"
export NOTARY_PROFILE="your-notarytool-keychain-profile"
./script/package_release.sh

The script builds and verifies, re-signs with the hardened runtime and timestamp, packs a UDZO DMG, submits it to notarytool, and staples the ticket. Windows/Linux guests in a production DMG require QEMU and swtpm to be bundled inside the app's qemu/ resource directory.

Status

The alpha foundation includes Windows, Linux, and macOS VM creation, ARM64 ISO/IPSW validation, EFI/disk/NAT configuration, start/stop/pause/resume, cloning, import/export, settings, diagnostics export, and English/Korean localization. Guest integration such as shared folders and clipboard remains experimental because it requires compatible guest drivers.

Guest installation runs through an embedded localhost-only noVNC display using ramfb; MacDow supplies a small EFI startup disk and automatically acknowledges the installation-media boot prompt. Each VM also persists its own UEFI variable flash and TPM 2.0 state so Secure Boot and TPM requirements remain satisfied.

Operating-system licensing and activation are the user's responsibility.

Alpha Distribution

The v0.1.0-alpha.1 GitHub release is ad-hoc signed and not notarized. On first launch, macOS may require the Open Anyway procedure below. Windows and Linux guests require Homebrew QEMU and swtpm (brew install qemu swtpm).

If macOS still prevents MacDow from opening:

1. Choose Apple menu ▸ System Settings.
2. Click Privacy & Security in the sidebar. You may need to scroll down.
3. Scroll to the Security section and click Open Anyway next to MacDow.
4. Click Open Anyway again in the confirmation dialog.
5. Enter your Mac login password, then click OK.

The Open Anyway button is available for about one hour after you try to open MacDow. If it is not visible, try opening MacDow again and return to Privacy & Security.

Troubleshooting

QEMU is missing / "QEMU is missing. Install QEMU or use a MacDow build that bundles it."

Install via Homebrew during development:

brew install qemu swtpm

QEMU is resolved in this order: bundled qemu/bin/qemu-system-aarch64, /opt/homebrew/bin/qemu-system-aarch64, then /usr/local/bin/qemu-system-aarch64.

The ARM64 UEFI firmware / secure UEFI variable template is missing

The bundled AAVMF firmware ships in Resources/SecureBoot/. If you are running from a custom QEMU install, MacDow also probes share/qemu/edk2-aarch64-code.fd and edk2-arm-vars.fd under Homebrew and /usr/local. Reinstall QEMU or use a MacDow DMG that bundles the firmware.

"The file path is too long" when starting a VM

Current builds place QEMU monitor and TPM sockets under /tmp using the VM UUID, so VM names do not affect the socket-length limit. If an older build shows this error, update to the latest MacDow build and start the VM again.

The selected ISO is not a valid ARM64 installation image

MacDow verifies the ISO contains efi/boot/bootaa64.efi. Ensure you downloaded an ARM64 (aarch64) image, not an x86_64 build. Linux ISOs that cannot be mounted are validated via bsdtar.

Saved state is not available with the QEMU backend

Saved state (pause/resume across app restarts) currently works only with the Apple Virtualization backend (macOS guests). Windows/Linux QEMU guests can be paused/resumed within a session but not saved to disk yet.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for development setup, code style, testing requirements, and the pull-request workflow, and CODE_OF_CONDUCT.md for community standards. Issues should use the provided GitHub issue templates.

Security

Report vulnerabilities privately via the repository's Security tab — do not open a public issue. See SECURITY.md for the full policy, supported versions, and scope.

Changelog

See CHANGELOG.md for release history. The project follows Keep a Changelog and Semantic Versioning.

License and Third-Party Notices

MacDow is licensed under the GNU General Public License v3.0.

Bundled third-party components — noVNC (MPL-2.0 / BSD-2-Clause), pako (MIT), and EDK2/AAVMF firmware (BSD-2-Clause-Patent and others) — are covered in THIRD_PARTY_NOTICES.md. Their licenses apply independently of MacDow's GPL-3.0 license.

Windows installation media, QEMU, swtpm, and operating-system licenses are not included in this source repository. Users must obtain them separately under their respective licenses.