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

> Discover the extensive capabilities of the vphoned daemon within your VM. Explore features like input injection, file transfer, app management, and more, all detailed in this guide.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: complete-capability-guide
- Published: 2026-09-10

---

**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](https://github.com/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`](https://github.com/Lakr233/vphone-cli/blob/main/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.

```swift
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.

```swift
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.

```swift
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.

```swift
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`](https://github.com/Lakr233/vphone-cli/blob/main/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.