What Functionalities Does the vphone‑cli Guest Daemon Provide? A Complete Technical Breakdown

The vphoned guest daemon exposes 15+ remote control capabilities to the host via a vsock-based length-prefixed JSON protocol, including HID input, location simulation, file management, keychain access, and accessibility tree extraction.

The vphone‑cli guest daemon (vphoned) runs as a launch daemon inside the iOS virtual machine and serves as the bridge between the host vphone-cli tool and the guest system. According to the Lakr233/vphone‑cli source code, this daemon implements a comprehensive command protocol that enables full remote administration of the virtual device. This article examines each functional area with direct references to the implementation in scripts/vphoned/vphoned.m and its helper modules.

Core Protocol and Handshake Mechanism

The daemon communicates over vsock using a length-prefixed JSON framing scheme defined in scripts/vphoned/vphoned_protocol.h. The vp_read_message and vp_write_message helpers handle message serialization.

During connection establishment, vphoned advertises its capabilities through the caps array constructed in handle_client (vphoned.m lines 29‑43). The host receives this capability list before issuing commands, ensuring compatibility across different daemon versions.

The daemon also reports the VM's primary IPv4 address via primary_ipv4_address during handshake (vphoned.m L4‑38), allowing the host to coordinate network-level operations.

HID Input and Touch Screen Emulation

The Human Interface Device (HID) subsystem enables keyboard, button, and multi-touch events from the host to reach the guest iOS system. The handle_command block processes two related command types:

• "hid" — Dispatches to vp_hid_key, vp_hid_press, and related functions
• "touch" — Dispatches to vp_hid_touch for multi-touch simulation

Both command types are handled in vphoned.m lines 92‑102, with the actual event synthesis implemented in scripts/vphoned/vphoned_hid.m.

// Host-side Swift example: sending a key press
let cmd: [String: Any] = [
    "t": "hid",
    "page": 0x01,           // kHIDPage_KeyboardOrKeypad
    "usage": 0x04,          // 'a' key
]
vphoneControl.send(command: cmd)

Touch events include phase information (began/moved/ended/cancelled) and normalized X/Y coordinates for full gesture recreation.

Developer Mode Operations

The developer mode control subsystem queries and enables Xcode development features on the guest. The "devmode" command accepts two sub-operations:

• "status" — Returns current developer mode state via vp_devmode_status
• "enable" — Arms developer mode for subsequent Xcode pairing via vp_devmode_arm

Implementation resides in vphoned.m lines 12‑38 with XPC-based detection logic in scripts/vphoned/vphoned_devmode.m.

Location Services Simulation

Vphoned provides complete GPS spoofing capabilities for testing location-dependent applications:

• "location" — Sets mock coordinates with full metadata via vp_location_simulate (vphoned.m L49‑58)
• "location_stop" — Clears simulation via vp_location_clear (vphoned.m L61‑63)

The location command accepts latitude, longitude, altitude, horizontal/vertical accuracy, speed, and course parameters.

// Simulating San Francisco coordinates
let locationCmd: [String: Any] = [
    "t": "location",
    "lat": 37.7749,
    "lon": -122.4194,
    "alt": 10.0,
    "hacc": 5.0,
    "vacc": 5.0,
    "speed": 0.0,
    "course": 0.0
]
vphoneControl.send(command: locationCmd)

CoreLocation integration is implemented in scripts/vphoned/vphoned_location.m.

File Transfer and Management

The file subsystem supports bidirectional transfer and filesystem operations through commands prefixed with "file_". The dispatcher vp_handle_file_command (vphoned.m L92‑98) routes to:

• Upload and download with inline binary transfer
• Directory listing
• Delete and rename operations

This enables remote file system introspection without SSH or other auxiliary services. Implementation details are in scripts/vphoned/vphoned_files.m.

Keychain Access

Keychain operations allow the host to query, add, and delete items from the iOS keychain. The "keychain_" command prefix routes through vp_handle_keychain_command (vphoned.m L100‑105).

This capability supports security research and automated testing scenarios requiring credential manipulation. See scripts/vphoned/vphoned_keychain.m for the SecItem implementation.

Clipboard Synchronization

Bidirectional clipboard sync handles text and binary payloads between host and guest. The "clipboard_" command prefix invokes vp_handle_clipboard_command (vphoned.m L108‑113).

Implementation in scripts/vphoned/vphoned_clipboard.m uses UIPasteboard APIs with proper encoding for non-text data.

Application Management

The app subsystem provides runtime control over installed applications:

• List installed apps with metadata
• Launch applications by bundle identifier
• Terminate running processes

The "app_" command prefix routes to vp_handle_apps_command (vphoned.m L116‑122), implemented in scripts/vphoned/vphoned_apps.m using private LSApplicationWorkspace APIs.

URL Handling and System Integration

The daemon can instruct Safari to open URLs via the "open_url" command, dispatched to vp_handle_url_command (vphoned.m L124‑130). This enables automated web workflows and deep-link testing.

Implementation in scripts/vphoned/vphoned_url.m uses standard UIApplication openURL mechanisms.

Settings Manipulation

User defaults access allows reading and writing preference values, toggling system features, and modifying configuration plists. The "settings_" command prefix routes through vp_handle_settings_command (vphoned.m L132‑138).

This subsystem in scripts/vphoned/vphoned_settings.m wraps NSUserDefaults and CoreFoundation preference APIs.

Accessibility Tree Extraction

For UI automation and testing, the "accessibility_tree" command retrieves the complete accessibility hierarchy via vp_handle_accessibility_command (vphoned.m L140‑146).

// Requesting the accessibility tree
let accCmd: [String: Any] = ["t": "accessibility_tree"]
vphoneControl.send(command: accCmd) { response in
    print(response)   // JSON hierarchy of UI elements
}

The scripts/vphoned/vphoned_accessibility.m implementation traverses the UIAccessibilityElement tree and serializes element properties (label, value, frame, traits, children) to JSON.

System Notifications and Power Management

The daemon receives low-power mode state changes from the host via the "low_power_mode" command, handled by vp_handle_notify_command (vphoned.m L148‑154). This synchronizes battery saver state between host orchestration and guest UI.

Implementation in scripts/vphoned/vphoned_notify.m posts appropriate NSDistributedNotificationCenter notifications.

Health Check and Version Query

Two simple diagnostic commands provide operational visibility:

• "ping" — Returns "pong" for connectivity verification (vphoned.m L45‑47)
• "version" — Returns the daemon build hash via VPHONED_BUILD_HASH (vphoned.m L66‑70)

These enable host-side health monitoring and version compatibility checks.

IPA Installation

Custom IPA package installation is supported through the "ipa_install" command, which forwards to vp_handle_custom_install (vphoned.m L72‑74). This subsystem in scripts/vphoned/vphoned_install.m handles app sideloading workflows.

Auto-Update and Self-Restart Capability

Vphoned implements over-the-air self-updating to simplify deployment in research environments. The "update" command sequence (vphoned.m L74‑84) and receive_update routine accept binary payloads from the host, validate signatures, write to cache, and trigger daemon restart.

This eliminates the need to rebuild the VM image for daemon patches.

Summary

The vphone‑cli guest daemon provides comprehensive remote control over virtual iOS devices:

• Input systems: HID keyboard, buttons, and multi-touch via vphoned_hid.m
• System state: Developer mode, location simulation, low-power notifications, and settings via dedicated modules
• Data access: Files, keychain, and clipboard with full binary support
• App lifecycle: Installation, listing, launch, and termination
• Automation: Accessibility tree extraction for UI introspection
• Operational: Health checks, version reporting, network info, and self-updating

All functionality is exposed through a single JSON-over-vsock protocol with automatic capability negotiation, making vphoned a complete remote administration layer for iOS virtualization.

Frequently Asked Questions

How does vphoned communicate with the host vphone-cli tool?

The daemon uses vsock (virtio socket) transport with a length-prefixed JSON protocol. The vp_read_message and vp_write_message helpers in vphoned_protocol.h frame each message with a 4-byte length header followed by UTF-8 JSON payload. This design ensures message boundaries are preserved over the stream socket and allows straightforward parsing in both Objective-C (daemon) and Swift (host) implementations.

Can vphoned simulate complex multi-touch gestures?

Yes. The "touch" command supports full multi-touch event synthesis including touch phase (began, moved, ended, cancelled), finger identifier, and normalized screen coordinates. The vp_hid_touch function in vphoned_hid.m constructs appropriate IOHIDEvent objects that iOS interprets as genuine touch input, enabling pinch, rotate, and multi-finger swipe recreation from the host.

What security considerations exist for the keychain and file access features?

Both subsystems execute with the daemon's privileges, which typically run as mobile or root depending on launchd configuration. The keychain commands in vphoned_keychain.m use standard SecItem APIs with kSecAttrAccessible attributes preserved from original items. The file commands in vphoned_files.m respect iOS sandbox boundaries for the calling process—access outside the app container requires appropriate entitlements. Network communication over vsock is isolated to the host and not exposed externally.

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