Which macOS Versions Are Compatible with vphone‑cli?

vphone‑cli requires macOS 15 (Sequoia) or later because it relies on the Virtualization.framework PV=3 profile and private‑API entitlements introduced in that version.

vphone‑cli is an open‑source virtualization tool by Lakr233 that creates virtual iPhone environments using Apple’s native hypervisor. Because the implementation depends on specific hardware model profiles and entitlements only exposed in recent macOS releases, system compatibility is strictly enforced at the build, installation, and runtime levels.

Why macOS 15 Sequoia Is the Minimum Requirement

The tool is built on Apple’s Virtualization.framework using the PV=3 hardware model profile. According to the source code in sources/vphone-cli/VPhoneHardwareModel.swift, this profile requires a minimum host OS version of macOS 15.0. The private APIs necessary for iOS virtualization are not available in earlier macOS releases, making Sequoia a hard dependency.

Source Code Enforcement

The Lakr233/vphone‑cli repository enforces this constraint across multiple files:

• Package.swift: Declares the Swift package deployment target as macOS(.v15), preventing the package from resolving on older systems.
• scripts/setup_machine.sh: Contains an explicit runtime check that aborts the setup process if the host version is older than macOS 15.
• README.md: Lists "macOS 15+ (Sequoia)" as a prerequisite in the platform requirements section.
• VPhoneHardwareModel.swift: Documents that the PV=3 profile is incompatible with any macOS version prior to 15.0.

Verifying Compatibility and Building

Before compiling or running vphone‑cli, confirm your system meets the macOS 15 threshold.

Check Your Current Version

Run the following command in Terminal:

sw_vers -productVersion

The output must display 15.x or higher. If you see 14.x or earlier, the tool cannot function, and the setup script will refuse to continue.

Build Commands for macOS 15+

With Xcode 15 or later installed, compile the project using:

make build

This invokes the Swift compiler with the macOS 15 deployment target specified in Package.swift. Attempting to build on older macOS versions will fail during package resolution.

Launching Virtual Machines

Once built, start the virtual iPhone GUI with:

make boot

For headless DFU mode (useful for automated firmware workflows):

make boot_dfu

Both commands query the hardware model in VPhoneHardwareModel.swift and will exit immediately if the host does not satisfy the macOS 15 requirement.

Advanced Features on Newer macOS Versions

While core virtualization works on macOS 15, certain advanced capabilities require newer releases. According to conditional code comments in sources/vphone-cli/VPhoneVirtualMachine.swift, the kernel GDB debug‑stub query and associated low‑level debugging interfaces are only functional on macOS 26 (Ventura‑plus) and later. These features are gated by runtime version checks and will silently fail or disable themselves on macOS 15 systems.

Summary

• vphone‑cli strictly requires macOS 15 (Sequoia) or later due to Virtualization.framework PV=3 dependencies.
• The Package.swift manifest hardcodes macOS(.v15) as the minimum deployment target.
• Setup scripts in scripts/setup_machine.sh actively block installation on older systems.
• Advanced debugging features may require macOS 26+, but core virtualization is fully functional on macOS 15.
• Verify your version with sw_vers -productVersion before attempting to build.

Frequently Asked Questions

Can I run vphone‑cli on macOS 14 Sonoma?

No. The tool depends on the Virtualization.framework PV=3 profile and private entitlements introduced exclusively in macOS 15. The setup script in scripts/setup_machine.sh will explicitly abort if it detects macOS 14 or earlier, and the Swift package manifest in Package.swift will fail to resolve.

What specific framework does vphone‑cli use?

vphone‑cli uses Apple’s Virtualization.framework with a private entitlement profile. As noted in VPhoneHardwareModel.swift, the PV=3 hardware model profile requires macOS 15.0 to access the hypervisor instructions and device virtualization features needed for iOS emulation.

Are there any features that require macOS versions newer than 15?

Yes. According to VPhoneVirtualMachine.swift, the kernel GDB debug‑stub functionality and related low‑level debugging queries are only available on macOS 26 (Ventura‑plus) and later. These features are conditionally compiled and will not affect basic VM operation on macOS 15.

How does the build system enforce the macOS 15 requirement?

The Swift Package Manager manifest in Package.swift declares platforms: [.macOS(.v15)], which causes the dependency resolver to fail immediately on older systems. Additionally, scripts/setup_machine.sh performs a runtime version check and exits with an error if the host is running anything older than macOS 15.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}