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

> Explore vphone-mcp integration for programmatic VM control in vphone-cli. Inject taps, swipes, key presses, and capture screenshots via a TCP bridge for external tool integration.

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

---

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

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

```

Expected response format:

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

```

Simulate a tap with automatic preview:

```bash
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:

```python
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`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneHostControl.swift) | Implements the Unix-domain socket server, JSON parsing, and command dispatch. |
| [`sources/vphone-cli/VPhoneVirtualMachineView.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachineView.swift) | Provides `injectTap` and `injectSwipe` helpers for gesture simulation. |
| [`sources/vphone-cli/VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneHostControl.swift), with gesture logic delegated to [`VPhoneVirtualMachineView.swift`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachineView.swift), which provides the `injectTap` and `injectSwipe` methods called by [`VPhoneHostControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneHostControl.swift) when processing socket commands.