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

> Discover the vphone-cli guest daemon functionalities. It offers 15+ remote control features like HID input, file management, and location simulation for your host device.

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

---

**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`](https://github.com/Lakr233/vphone-cli/blob/main/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](https://github.com/Lakr233/vphone-cli/blob/main/scripts/vphoned/vphoned.m#L29-L43)). 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](https://github.com/Lakr233/vphone-cli/blob/main/scripts/vphoned/vphoned.m#L4-L38)), 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](https://github.com/Lakr233/vphone-cli/blob/main/scripts/vphoned/vphoned.m#L92-L102), with the actual event synthesis implemented in `scripts/vphoned/vphoned_hid.m`.

```swift
// 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](https://github.com/Lakr233/vphone-cli/blob/main/scripts/vphoned/vphoned.m#L12-L38) 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](https://github.com/Lakr233/vphone-cli/blob/main/scripts/vphoned/vphoned.m#L49-L58))
- **`"location_stop"`** — Clears simulation via `vp_location_clear` ([vphoned.m L61‑63](https://github.com/Lakr233/vphone-cli/blob/main/scripts/vphoned/vphoned.m#L61-L63))

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

```swift
// 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](https://github.com/Lakr233/vphone-cli/blob/main/scripts/vphoned/vphoned.m#L92-L98)) 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](https://github.com/Lakr233/vphone-cli/blob/main/scripts/vphoned/vphoned.m#L100-L105)).

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](https://github.com/Lakr233/vphone-cli/blob/main/scripts/vphoned/vphoned.m#L108-L113)).

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](https://github.com/Lakr233/vphone-cli/blob/main/scripts/vphoned/vphoned.m#L116-L122)), 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](https://github.com/Lakr233/vphone-cli/blob/main/scripts/vphoned/vphoned.m#L124-L130)). 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](https://github.com/Lakr233/vphone-cli/blob/main/scripts/vphoned/vphoned.m#L132-L138)).

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](https://github.com/Lakr233/vphone-cli/blob/main/scripts/vphoned/vphoned.m#L140-L146)).

```swift
// 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](https://github.com/Lakr233/vphone-cli/blob/main/scripts/vphoned/vphoned.m#L148-L154)). 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](https://github.com/Lakr233/vphone-cli/blob/main/scripts/vphoned/vphoned.m#L45-L47))
- **`"version"`** — Returns the daemon build hash via `VPHONED_BUILD_HASH` ([vphoned.m L66‑70](https://github.com/Lakr233/vphone-cli/blob/main/scripts/vphoned/vphoned.m#L66-L70))

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](https://github.com/Lakr233/vphone-cli/blob/main/scripts/vphoned/vphoned.m#L72-L74)). 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](https://github.com/Lakr233/vphone-cli/blob/main/scripts/vphoned/vphoned.m#L74-L84)) 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`](https://github.com/Lakr233/vphone-cli/blob/main/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.