lakr233/vphone-cli/vphone-guest-control

Driving vphone

vphone runs a virtual iPhone on an Apple Silicon Mac through Virtualization.framework. Two pieces matter to you:

Use vphone-launchpad-cli for everything. The app does the privileged and signed work for you; a second route (sudo, a copy of vphone-cli, devicectl) either lacks the entitlements, bypasses the checks the app records, or times out against these guests.

How a session should go

1. Find out where the user is. Run vphone-launchpad-cli status. If the

command does not exist, go to install. Otherwise the JSON tells you the next step:

• canInstallBundles: false or helper not ready: the user must finish

Host Setup in the app (administrator password, Developer Tools access). You cannot do this for them; say exactly what is missing.

• defaultBundle: null or bundleReady: false: install or verify a bundle.

Each machine runs with its own bundle (vm list → bundle); the default only decides what new machines get.

• machines: 0: create one (machines).
• Otherwise: list machines, start the one the user named, then control it.

1. Pick the reference for the task, and read it before acting.

1. Verify with the guest, not with assumptions. After an input, take a

screenshot or read ui.describe; after a launch, check apps.foreground. The guest is a real device with timing, so a command that returned ok has not necessarily produced the visible result.

Output and errors

• Progress lines go to stderr as they arrive. The result is **one JSON

document on stdout**. Exit 0 is success; exit 1 is failure with the reason on stderr. Parse stdout, and read stderr when the exit code is 1.

• vphone-launchpad-cli help prints every command with its options and is

authoritative if this skill and the installed version disagree.

• Quote JSON in single quotes: guest rpc myphone apps.launch '{"bundle_id":"com.apple.Preferences"}'.
• Interrupting the CLI cancels exec, waits and CFW install. A bundle install

or a machine creation belongs to the app window and keeps going, so do not start a second one because the CLI went quiet; run vm log <name> --kind create.

• Pass --root <library> only when two libraries hold a machine with the same

name; the error lists the libraries.

Rules that save the user's machine

These exist because each one has cost the user real time or disk before.

• Use the machines the user named. Do not vm create to reproduce a

problem; diagnose on the existing guest. A creation takes tens of GB and several restarts, and a half-built machine is harder to clean up than the bug.

• Creating is one at a time, after checking free disk. IPSWs plus the

restore tree are large, and a full disk fails halfway with confusing errors.

• Never change host security settings (SIP, boot-args, AMFI, Research

Guests) and never run bundle accept, bundle remove, cfw install or a second vm create over existing work unless the user asked. Report what is needed; the Mac's owner decides.

• `force` methods need the user's intent. processes.kill, services.stop,

services.kickstart with kill, apps.uninstall, system.respring, system.reboot, system.shutdown and similar refuse to run without "force":true. Passing it is the confirmation, so pass it only for an action the user asked for.

• Do not edit a machine's folder (`~/.vphone/machines/<name>/`) while it runs.

Use RPC for guest files instead.

• Keep the host API listener on loopback. --api-listen sends its token in

clear text.

• Install apps through installd (ideviceinstaller) when the point is to

test installation; apps.install bypasses installd. Never use xcrun devicectl to install or launch (it times out); listing devices is fine.

• When stuck, read before experimenting. The repository's guides and

Research/ notes quote real failures; see references/finding-docs.md.