vphone-mcp Integration and Host Control Socket: Programmatic VM Control in vphone-cli

The vphone-mcp integration wraps vphone-cli's Unix-domain host control socket to enable JSON-based programmatic control of the virtual iPhone, allowing external tools to inject taps, swipes, key presses, and capture screenshots either directly or via a convenient TCP bridge.

The vphone-cli project by Lakr233 provides a lightweight iOS virtualization environment that includes a host control socket for external automation. This Unix-domain socket, implemented in VPhoneHostControl.swift, accepts structured JSON commands to manipulate the virtual machine, while the separate vphone-mcp project exposes this interface over TCP for broader accessibility.

Understanding the Host Control Socket Architecture

Socket Implementation in VPhoneHostControl.swift

Located at sources/vphone-cli/VPhoneHostControl.swift, the VPhoneHostControl class creates a SOCK_STREAM Unix socket at <bundle>/vphone.sock. The server listens for one-line JSON commands, dispatches actions to the virtual machine via VPhoneAppDelegate, and returns JSON responses that may include base64-encoded screenshot previews.

Supported JSON Command Protocol

The socket accepts five primary command types via the t field:

• screenshot: {"t":"screenshot"} with optional path and screen parameters. Captures a full-resolution image and always returns a compact grayscale JPEG in the image field.
• tap: {"t":"tap","x":<int>,"y":<int>} injects a touch event at the specified pixel coordinates.
• swipe: {"t":"swipe","x1":<int>,"y1":<int>,"x2":<int>,"y2":<int>,"ms":<int>} performs a drag gesture with configurable duration in milliseconds.
• key: {"t":"key","name":"<home|power|volup|voldown>"} simulates hardware button presses via HID injection.
• type: {"t":"type","text":"<string>"} sets the guest clipboard contents for pasting operations.

Optional modifiers include "screen":false to skip automatic screenshot capture and "delay":<milliseconds> to pause after execution before capturing.

Direct Socket Communication

For local automation, interact directly with the Unix socket using standard networking tools.

Capture a screenshot and save it to a specific path:

echo '{"t":"screenshot","path":"/tmp/vm.png"}' | nc -U /path/to/vphone.app/Contents/Resources/vphone.sock

Expected response format:

{
  "ok": true,
  "path": "/tmp/vm.png",
  "image": "/9j/4AAQSkZJRgABAQAAAQABAAD/..."
}

Simulate a tap with automatic preview:

echo '{"t":"tap","x":640,"y":1200}' | nc -U /path/to/vphone.app/Contents/Resources/vphone.sock

vphone-mcp Integration and TCP Wrapper

The vphone-mcp project (hosted at https://github.com/pluginslab/vphone-mcp) provides a Model Context Protocol server that bridges TCP connections to the Unix socket. This architecture eliminates the need for clients to handle Unix-domain sockets directly.

Architecture flow:

[External Client] --TCP--> [vphone-mcp Server] --Unix Socket--> [VPhoneHostControl]
       ^                                                            |
       |____________________ JSON Response _________________________|

The MCP server listens on TCP port 11235 by default and forwards JSON commands transparently, handling connection multiplexing and lifecycle management.

Python client example using the vphone-mcp integration:

import socket, json, base64

sock = socket.create_connection(('localhost', 11235))
sock.sendall(json.dumps({"t":"key","name":"home"}).encode() + b'\n')
resp = json.loads(sock.recv(4096).decode())
print(resp)   # {'ok': True, 'image': '...'}

sock.close()

Key Implementation Files

File	Purpose
sources/vphone-cli/VPhoneHostControl.swift	Implements the Unix-domain socket server, JSON parsing, and command dispatch.
sources/vphone-cli/VPhoneVirtualMachineView.swift	Provides injectTap and injectSwipe helpers for gesture simulation.
sources/vphone-cli/VPhoneControl.swift	Handles HID key injection and clipboard synchronization for key and type commands.
VPhoneAppDelegate	Automatically starts the host control socket via VPhoneHostControl.start(...) after VM boot.

Summary

• The host control socket in vphone-cli provides a JSON-over-Unix-socket API for VM automation at <bundle>/vphone.sock.
• Five core commands—screenshot, tap, swipe, key, and type—enable full UI control and content injection.
• The vphone-mcp integration wraps this socket in a TCP server (port 11235), making the interface accessible from any programming language without Unix socket dependencies.
• Implementation resides primarily in VPhoneHostControl.swift, with gesture logic delegated to VPhoneVirtualMachineView.swift.

Frequently Asked Questions

What is the default socket path for the vphone-cli host control socket?

The socket is created at vphone.sock inside the application bundle. At runtime, the path resolves to Bundle.main.bundlePath + "/vphone.sock", typically located within vphone.app/Contents/Resources/.

Can I disable automatic screenshots when sending commands?

Yes. Include "screen":false in your JSON payload for any command except screenshot itself. This prevents the server from capturing and encoding a preview image, reducing response latency and bandwidth.

How does vphone-mcp differ from direct socket access?

While direct access requires connecting to a Unix-domain socket file, vphone-mcp exposes the same command protocol over TCP port 11235. This allows remote clients and programming languages without Unix socket support to control the VM using identical JSON commands.

Which source file handles the actual touch injection?

Gesture execution is implemented in sources/vphone-cli/VPhoneVirtualMachineView.swift, which provides the injectTap and injectSwipe methods called by VPhoneHostControl.swift when processing socket commands.

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