vphone-cli PV=3 Entitlements: Complete Permission Guide for Virtualization

vphone-cli requires seven specific code-signing entitlements—including com.apple.private.virtualization and com.apple.private.virtualization.security-research—to enable PV=3 (Performance Virtualization) mode, which bypasses standard Hypervisor APIs to run virtualized iOS on macOS.

Running an iOS virtual machine using Apple's Virtualization.framework in Performance Virtualization mode (PV=3) demands elevated privileges beyond standard app sandboxing. The vphone-cli project by Lakr233 bundles these permissions in a dedicated entitlements file that grants access to private APIs, virtual networking, and kernel patching capabilities required for the virtualized environment.

Understanding PV=3 Entitlements for vphone-cli

PV=3 mode operates outside the standard Hypervisor (HV) path, allowing direct access to hardware acceleration and private virtualization APIs. According to the source code in sources/vphone-cli/VPhoneVirtualMachine.swift, the framework explicitly checks for these entitlements when initializing the VZVirtualMachine instance with PV=3 configuration options.

Core Virtualization Permissions

The foundation of PV=3 support rests on two virtualization-specific entitlements declared in sources/vphone.entitlements:

• com.apple.security.virtualization (line 5): Grants general permission to use Apple's Virtualization.framework
• com.apple.private.virtualization (line 7): The private entitlement specifically required for PV=3 mode access

Without com.apple.private.virtualization, the operating system blocks the private initialization paths that configure the Performance Virtualization environment, causing the VM to fail immediately during boot sequence.

Security Research and Debugging Access

PV=3 relies on undocumented security-research APIs that require explicit approval through dedicated entitlements:

• com.apple.private.virtualization.security-research (line 9): Allows invocation of privileged hooks necessary for bypassing standard virtualization constraints
• com.apple.security.get-task-allow (line 15): Enables debugging tools to attach to the running VM process for troubleshooting and inspection

These permissions are essential during development and when utilizing the jailbreak and experimental firmware variants supported by vphone-cli.

Hardware Services Integration

The virtual machine requires access to host hardware capabilities, secured through:

• com.apple.vm.networking (line 11): Grants access to the virtual networking stack (vsock) that wires the VM's network interface through the host
• com.apple.security.personal-information.location (line 13): Permits forwarding of the host's CoreLocation data into the guest iOS environment

Kernel Patching Capabilities

For advanced workflows involving custom firmware, vphone-cli requires:

• com.apple.private.bmk.allow (line 17): Enables the BMK (Boot-Memory-Kernel) patch path required for certain kernel-patching operations used across regular, development, and jailbreak firmware variants

Entitlement Configuration in sources/vphone.entitlements

All seven entitlements are declared in the project's centralized entitlements plist. The sources/vphone.entitlements file serves as the single source of truth for code-signing requirements:

com.apple.security.virtualization
com.apple.private.virtualization  
com.apple.private.virtualization.security-research
com.apple.vm.networking
com.apple.security.personal-information.location
com.apple.security.get-task-allow
com.apple.private.bmk.allow

Each entitlement corresponds to specific functionality lines in sources/vphone-cli/VPhoneAppDelegate.swift, where the VPhoneHardwareModel.swift configures the Dynamic library integration for PV=3 hardware model setup.

Build Integration and Verification

The project embeds these entitlements through SwiftPM's resource bundling mechanism defined in Package.swift:

let package = Package(
    name: "vphone-cli",
    platforms: [.macOS(.v15)],
    products: [.executable(name: "vphone-cli", targets: ["vphone-cli"])],
    targets: [
        .executableTarget(
            name: "vphone-cli",
            path: "sources/vphone-cli",
            resources: [
                .copy("../../../sources/vphone.entitlements")
            ]
        )
    ]
)

After building, verify the binary contains the correct entitlements using the codesign utility:

codesign -d --entitlements :- .build/release/vphone-cli

This command outputs the seven entitlements required for PV=3 operation, confirming the binary is properly signed for virtualization tasks.

Summary

• Seven distinct entitlements declared in sources/vphone.entitlements are mandatory for PV=3 operation
• com.apple.private.virtualization enables bypassing standard Hypervisor paths to access Performance Virtualization mode
• com.apple.private.bmk.allow provides the kernel patching capabilities specific to vphone-cli's firmware support
• Entitlements are embedded via SwiftPM resources and verified using codesign -d --entitlements
• Missing any single entitlement prevents VM startup, networking functionality, or location services access

Frequently Asked Questions

What happens if I run vphone-cli without the required entitlements?

The binary will fail to initialize the VZVirtualMachine instance. Specifically, the absence of com.apple.private.virtualization causes an immediate crash during PV=3 configuration, while missing networking or location entitlements results in silent failures of those specific subsystems without affecting the core VM boot process.

Can I use vphone-cli PV=3 mode with a standard Apple Developer account?

PV=3 mode requires private entitlements—specifically com.apple.private.virtualization and com.apple.private.bmk.allow—that Apple restrict to internal builds or specific security research agreements. Standard Developer Program provisioning profiles cannot sign binaries with these private keys, limiting PV=3 functionality to specially provisioned certificates or local builds with disabled SIP on macOS development machines.

How does PV=3 differ from standard virtualization modes in Virtualization.framework?

Standard virtualization uses the Hypervisor (HV) path with documented APIs, while PV=3 (Performance Virtualization) bypasses these layers for direct hardware access and reduced overhead. According to sources/vphone-cli/VPhoneVirtualMachine.swift, PV=3 requires the Dynamic library integration configured in VPhoneHardwareModel.swift and the private entitlement set to access undocumented initialization hooks that standard modes do not utilize.

Where can I inspect the complete list of entitlements for my build?

Check the bundled entitlements by running codesign -d --entitlements :- .build/release/vphone-cli on your compiled binary. You can also review the source definitions directly in sources/vphone.entitlements at lines 5, 7, 9, 11, 13, 15, and 17 to see the exact entitlement keys and their XML declarations.

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