What Actions Can the vphoned Daemon Perform Inside the VM: Complete Capability Guide

The vphoned daemon exposes fourteen distinct host-to-guest service categories—including HID input injection, bidirectional file transfer, clipboard synchronization, GPS location forwarding, app lifecycle management, and IPA installation—over a length-prefixed JSON protocol on vsock port 1337.

The vphoned daemon serves as the central control plane inside the virtual iOS device for the Lakr233/vphone-cli project. Running as a background service within the VM and listening on vsock port 1337, it translates length-prefixed JSON commands from the host into native iOS subsystem operations, enabling comprehensive automation and interaction without requiring additional guest-side software.

Architecture and Protocol Foundation

The daemon implements a binary-framed JSON protocol defined in scripts/vphoned/vphoned_protocol.h and vphoned_protocol.m. All messages traverse a vsock channel using a [uint32-big-endian length][UTF-8 JSON payload] structure. This framing ensures reliable message boundaries for the bidirectional RPC-style communication between the host’s VPhoneControl Swift interface and the guest’s Objective-C service handlers.

Input Injection and Accessibility Control

HID Event Injection via scripts/vphoned/vphoned_hid.m

The daemon injects keyboard events and single-finger touch events using private IOKit APIs. It supports arbitrary key presses with USB HID usage pages, enabling automation of keyboard shortcuts and touch gestures.

let command: [String: Any] = [
    "type": "hid",
    "action": "press",
    "page": 0x07,          // Keyboard/Keypad page
    "usage": 0x4F          // 'R' key
]
VPhoneControl.shared.send(command)

Accessibility Controls via scripts/vphoned/vphoned_accessibility.m

Provides toggles for system-wide accessibility features such as VoiceOver. This allows automated testing of accessibility paths or enabling assistive technologies remotely without manual interaction inside the VM.

Data Transfer and State Synchronization

File Transfer Operations via scripts/vphoned/vphoned_files.m

Supports upload and download of arbitrary binary data between host and guest. Files are Base64-encoded within the JSON payload, allowing the host to push resources into the guest filesystem or extract application data without direct filesystem mounting.

let upload: [String: Any] = [
    "type": "file",
    "action": "upload",
    "path": "/tmp/example.txt",
    "data": Data(contentsOf: URL(fileURLWithPath: "/host/example.txt")).base64EncodedString()
]
VPhoneControl.shared.send(upload)

Clipboard Synchronization via scripts/vphoned/vphoned_clipboard.m

Implements bidirectional clipboard sync. The daemon retrieves the current UIPasteboard contents from the guest and pushes host clipboard updates into the VM, enabling seamless copy-paste workflows across the virtualization boundary.

Settings Synchronization via scripts/vphoned/vphoned_settings.m

Propagates host system preferences—including Wi-Fi configuration and locale settings—into the guest’s NSUserDefaults, ensuring the VM environment mirrors the host’s desired state.

System Integration and Location Services

Location and GPS Forwarding via scripts/vphoned/vphoned_location.m

Mirrors the host’s CoreLocation data into the guest by injecting CLLocation updates. Apps inside the VM receive accurate latitude, longitude, and altitude data as if they were running on physical hardware.

let location: [String: Any] = [
    "type": "location",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "altitude": 10.0
]
VPhoneControl.shared.send(location)

URL Handling via scripts/vphoned/vphoned_url.m

Requests the guest to open specific URLs through UIApplication’s openURL mechanism, enabling automated launching of Safari or deep-linking into specific app states from the host.

let url: [String: Any] = [
    "type": "url",
    "action": "open",
    "url": "https://developer.apple.com"
]
VPhoneControl.shared.send(url)

Application Management via scripts/vphoned/vphoned_apps.m

Provides introspection and control over the installed application catalog. Capabilities include listing installed apps by bundle ID, launching apps into the foreground, and triggering app-specific actions programmatically without user intervention.

Push Notification Delivery via scripts/vphoned/vphoned_notify.m

Forwards remote notification payloads from the host to the guest, allowing testing of APNs-style push notifications without external network dependencies or Apple’s push servers.

Media and Deployment Capabilities

Virtual Camera Support via scripts/vphoned/vphoned_vcam.m

Supplies a virtual camera feed to the guest AVFoundation stack. The host can stream video frames into the VM, allowing apps to consume camera input without physical hardware or camera permissions.

IPA Installation via scripts/vphoned/vphoned_install.m

Performs complete application lifecycle management for IPA packages: extraction, re-signing with appropriate entitlements, and installation into the guest’s application sandbox. This enables automated deployment of custom or unsigned applications into the virtual device.

Developer and Diagnostic Operations

Developer Mode Operations via scripts/vphoned/vphoned_devmode.m

Exposes diagnostic commands including ping heartbeat checks, version queries, and runtime toggling of debug logging levels. These primitives allow the host to verify daemon health and troubleshoot protocol issues during automation workflows.

Summary

• The vphoned daemon operates on vsock port 1337 using a length-prefixed JSON framing protocol defined in scripts/vphoned/vphoned_protocol.h.
• HID injection (vphoned_hid.m) enables automation of keyboard and touch events via private IOKit APIs.
• File and clipboard operations (vphoned_files.m, vphoned_clipboard.m) support bidirectional data transfer without direct filesystem access.
• Location services (vphoned_location.m) mirror host GPS data into the guest CoreLocation stack.
• App lifecycle management (vphoned_apps.m, vphoned_install.m) allows installation, listing, and launching of applications.
• Virtual hardware support includes camera feeds (vphoned_vcam.m) and push notification simulation (vphoned_notify.m).
• System integration covers URL opening, settings sync, accessibility toggles, and developer diagnostics.

Frequently Asked Questions

What protocol does vphoned use for host-guest communication?

The daemon uses a custom binary-framed JSON protocol over AF_VSOCK. Messages are prefixed with a 32-bit big-endian length field followed by UTF-8 JSON payload, implemented in scripts/vphoned/vphoned_protocol.m. This design ensures message boundary integrity over the stream-based vsocket.

Can vphoned simulate multi-touch gestures?

The current implementation in scripts/vphoned/vphoned_hid.m supports single-finger touch events and keyboard input according to USB HID usage pages. Multi-touch gestures would require extending the HID report structures to support additional touch contacts and contact identifiers.

How does file transfer handle binary data?

Files are transmitted as Base64-encoded strings within the JSON payload. While this introduces approximately 33% overhead compared to raw binary, it ensures compatibility with the text-based protocol and avoids additional socket complexity or framing logic.

Is root privilege required inside the VM to run vphoned?

Yes, many capabilities—including private IOKit HID injection, accessibility overrides, system settings manipulation, and app installation—require the daemon to run with elevated privileges or within a privileged container that can access restricted iOS APIs normally unavailable to sandboxed applications.

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