# Advanced Features of vphone-cli: A Deep Dive into Virtual iPhone Virtualization

> Explore advanced vphone-cli features like synthetic battery management, GDB kernel debugging, SEP emulation, Touch ID forwarding, and real-time media streaming. Master virtual iPhone virtualization.

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

---

**vphone-cli exposes advanced virtualization capabilities including synthetic battery management, GDB kernel debugging, SEP coprocessor emulation, Touch ID forwarding, and real-time media streaming through Apple's Virtualization.framework.**

**vphone-cli** is a macOS command-line tool that boots a Platform Version 3 (PV3) virtual iPhone using Apple's Virtualization.framework. The advanced features of vphone-cli extend far beyond basic emulation, providing a comprehensive hardware abstraction layer that allows developers to interact with the guest system as if it were physical hardware, enabling deep iOS research and development workflows.

## Synthetic Hardware and Device Simulation

### Synthetic Battery Management

The tool creates a fully controllable battery source that reports arbitrary charge levels and connectivity states to the guest OS. According to the source code, the battery is initialized in [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift) (lines 49‑59) through the `VZMacSyntheticBatterySource` API. Runtime updates are handled by the `setBattery(charge:connectivity:)` method (lines 40‑48), allowing developers to simulate low-power scenarios or charging states without physical hardware.

### SEP Coprocessor Emulation

For security research, vphone-cli implements Secure Enclave Processor (SEP) support with dedicated storage and optional ROM images. The SEP configuration is constructed in [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift) (lines 80‑89), providing the cryptographic subsystem required for testing Secure Enclave-dependent features.

### NVRAM Variable Injection

Using the **Dynamic** wrapper to invoke private Apple APIs, the tool modifies NVRAM boot arguments before VM initialization. This is implemented in [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift) (lines 36‑44), enabling custom kernel arguments and firmware configurations that are typically inaccessible on physical devices.

## Debugging and Development Infrastructure

### GDB Debug Stub Integration

vphone-cli exposes a TCP-based kernel debug stub for live debugging with LLDB or GDB. The stub is configured in [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift) (lines 61‑78) and automatically prints the connection details after VM start (lines 66‑74). Developers can specify a custom port via the `--kernel-debug-port` CLI flag, which is processed in the `start(forceDFU:)` method (lines 55‑66).

### Dynamic Private API Access

The codebase leverages the **Dynamic** Swift wrapper extensively to call undocumented Apple virtualization APIs. This approach enables features like synthetic device creation and NVRAM manipulation that are not exposed in the public Virtualization.framework headers, providing capabilities beyond standard macOS virtualization tools.

## Media Capture and Streaming Architecture

### Screen Recording Pipeline

The screen recording system captures the VM display at 30 frames per second and encodes directly to MOV format. The implementation resides in [`VPhoneScreenRecorder.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneScreenRecorder.swift) (lines 10‑327), which uses a private selector (`_takeScreenshotWithCompletionHandler:`) to capture frames from the `VZGraphicsDisplay`. Menu integration is handled in [`VPhoneMenuRecord.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneMenuRecord.swift) (lines 9‑40), providing both continuous recording and single screenshot capture to the clipboard.

### Virtual Camera Server

A vsock-based camera server runs on port 1338 inside the guest, receiving video streams from the host. The UI for source selection lives in [`VPhoneMenuCamera.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneMenuCamera.swift) (lines 6‑44), while the streaming logic and connection state management occupy lines 46‑100. The host can select between video files, test patterns, or disabled states, streaming chosen content into the virtual camera device.

## Input Simulation and Interaction

### Touch ID Forwarding

The tool detects host biometric capabilities and forwards Touch ID events to the guest's Home button sensor. Menu handling is implemented in [`VPhoneMenuKeys.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneMenuKeys.swift) (lines 19‑63), with runtime capability checks in the private extension (lines 65‑70). This allows testing biometric authentication flows within the virtual environment.

### Hardware Key Injection

The `VPhoneKeyHelper` class dispatches physical key events including Home, Power, Volume, Spotlight, and arbitrary ASCII text input. Implementation details are in [`VPhoneMenuKeys.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneMenuKeys.swift) (lines 33‑56), enabling automation of hardware button sequences and text entry.

### Location Synchronization and Replay

The host's CoreLocation data is forwarded to the guest over vsock when synchronization is enabled. [`VPhoneMenuLocation.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneMenuLocation.swift) (lines 3‑164) defines preset locations (including Apple Park and Infinite Loop) and route replay functionality. The `VPhoneLocationProvider` streams coordinate updates and supports looped route replay with configurable intervals, allowing comprehensive location-aware testing without physical movement.

## System Integration and File Management

### File Browser and Transfer

A SwiftUI-based file browser facilitates bi-directional file transfer over the vsock control channel on port 1337. The interface is implemented in [`VPhoneFileBrowserView.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneFileBrowserView.swift) and [`VPhoneFileBrowserModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneFileBrowserModel.swift), while the host-side protocol handler resides in [`VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneControl.swift). This provides direct filesystem access without requiring network configuration inside the VM.

### IPA Installation Pipeline

vphone-cli automates the extraction, re-signing, and installation of iOS application packages. The workflow is managed by [`VPhoneIPAInstaller.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneIPAInstaller.swift) with cryptographic signing operations in [`VPhoneSigner.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneSigner.swift), streamlining app deployment for testing unsigned or development builds.

### Network Device Configuration

Network connectivity is configurable via NAT, bridged, or null networking modes based on the firmware manifest. Device creation is handled by `VPhoneNetworking.makeNetworkDevice` (lines 87‑92), allowing flexible network topologies for security research and development scenarios.

## Practical Implementation Examples

### Boot with GDB Debugging

Expose a kernel debug stub on a specific port during VM initialization:

```bash
./vphone-cli boot --cpu 8 --memory 8G \
  --screen-width 1290 --screen-height 2796 \
  --kernel-debug-port 6000

```

The `--kernel-debug-port` flag is handled in `VPhoneVirtualMachine.start(forceDFU:)` (lines 55‑66).

### Runtime Battery Manipulation

Adjust battery charge and connectivity state while the VM is running:

```swift
import VPhoneCore

let vm = try VPhoneVirtualMachine(options: opts)
await vm.start(forceDFU: false)

// Set battery to 50% and indicate disconnected state
vm.setBattery(charge: 50.0, connectivity: 2)

```

The `setBattery` method updates the private `VZMacSyntheticBatterySource` (see [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift) lines 40‑48).

### Screenshot Capture

Copy the current VM display to the system pasteboard:

```swift
await VPhoneScreenRecorder().copyScreenshotToPasteboard(view: view)

```

The screenshot logic lives in [`VPhoneScreenRecorder.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneScreenRecorder.swift) – `copyScreenshotToPasteboard(view:)` (lines 32‑48).

### Camera Streaming from Video File

Stream local video content into the virtual camera device:

```swift
cameraServer?.setSource(.videoFile, videoURL: url)
cameraServer?.startStreaming()

```

Implementation details are in [`VPhoneMenuCamera.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneMenuCamera.swift) (lines 77‑99 for file selection, 101‑110 for toggling streaming).

### Location Replay of Preset Routes

Simulate movement through a predefined geographic path:

```swift
VPhoneLocationProvider.shared.sendPreset(name: "Apple Park (Cupertino)",
                                         latitude: 37.334606,
                                         longitude: -122.009102,
                                         altitude: 14)

VPhoneLocationProvider.shared.startReplay(name: "Apple Park Loop",
                                          points: locationReplayPoints,
                                          intervalSeconds: 1.5,
                                          loop: true)

```

The preset array and replay points are defined in [`VPhoneMenuLocation.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneMenuLocation.swift) (lines 10‑46), with provider methods called from menu actions (lines 30‑41).

## Summary

- **Synthetic Hardware**: vphone-cli simulates battery, SEP, and NVRAM through private APIs in [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift)
- **Debug Capabilities**: TCP-based GDB stub enables kernel debugging via configurable ports
- **Media Systems**: 30fps screen recording and vsock-based camera streaming provide comprehensive media testing
- **Interaction**: Touch ID forwarding, hardware key injection, and location replay enable realistic input simulation
- **Integration**: File browser, IPA installer, and flexible networking support complete development workflows

## Frequently Asked Questions

### What is vphone-cli primarily used for?

vphone-cli is a macOS command-line tool designed for iOS security research and development. It boots a Platform Version 3 virtual iPhone using Apple's Virtualization.framework, providing advanced capabilities like synthetic hardware manipulation, kernel debugging, and biometric simulation that are essential for testing iOS applications and firmware without physical device constraints.

### How does the GDB debug stub work in vphone-cli?

The tool exposes a TCP-based kernel debug stub configured in [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift) (lines 61‑78). When you specify the `--kernel-debug-port` flag during boot, vphone-cli initializes the stub and prints connection details (lines 66‑74), allowing you to attach LLDB or GDB to the running virtual iPhone kernel for live debugging and breakpoint analysis.

### Can vphone-cli simulate Touch ID and biometric authentication?

Yes, vphone-cli detects the host Mac's biometric capabilities through [`VPhoneMenuKeys.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneMenuKeys.swift) (lines 65‑70) and forwards Touch ID events to the guest's virtual Home button. The menu system (lines 19‑63) manages these events, enabling developers to test biometric authentication flows and Secure Enclave interactions within the virtual environment.

### How do I install custom IPA files in the virtual iPhone?

The [`VPhoneIPAInstaller.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneIPAInstaller.swift) module handles automated extraction, re-signing, and installation of IPA packages, with cryptographic operations managed by [`VPhoneSigner.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneSigner.swift). This pipeline allows developers to install unsigned or development iOS applications directly into the virtual machine for testing, bypassing the restrictions typically imposed by physical device provisioning.