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

> Unlock PV=3 performance with vphone-cli by understanding the seven essential entitlements. This guide details required permissions for virtualizing iOS on macOS.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: deep-dive
- Published: 2026-09-05

---

**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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneAppDelegate.swift), where the [`VPhoneHardwareModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/Package.swift):

```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:

```bash
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`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachine.swift), PV=3 requires the Dynamic library integration configured in [`VPhoneHardwareModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/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.