vphone-guest-control

# Driving vphone vphone runs a virtual iPhone on an Apple Silicon Mac through Virtualization.framework. Two pieces matter to you: | Piece | Role | | --- | --- | | `vphone-launchpad` (Mac app) | Downloads and verifies `VPhone.bundle`, creates machines, runs them. Owns the only root helper. | | `vphone-launchpad-cli` | A stateless client of the running app. Every command also appears in the app's window and history. | 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](references/install.md). 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](references/machines.md)). - Otherwise: list machines, start the one the user named, then control it. 2. **Pick the reference for the task, and read it before acting.** | Task | Read | | --- | --- | | Install Launchpad or a bundle, host requirements, series matching | [references/install.md](references/install.md) | | An install step failed: "damaged", Developer Tools access turns off, several macOS installations, `zsh: killed`, not Apple silicon | [references/install-faq.md](references/install-faq.md) | | Create, start, stop, retry, update a machine, change its Core Bundle | [references/machines.md](references/machines.md) | | Tap, swipe, key, screenshot, anything on `vphone.sock` | [references/guest-socket.md](references/guest-socket.md) | | Call a vphoned method: apps, files, logs, UI tree, processes | [references/rpc-methods.md](references/rpc-methods.md) | | Installing an IPA | [references/rpc-methods.md](references/rpc-methods.md#installing-an-app) | | roothide vs rootless, installing the bootstrap, ssh, `/rootfs`, handing files to vphoned, `.deb` | [references/guest-layout.md](references/guest-layout.md) | | Black screen, timeouts, AMFI, "客体代理未连接" | [references/troubleshooting.md](references/troubleshooting.md) | | A symptom the above does not cover; which research note or source explains it | [references/finding-docs.md](references/finding-docs.md) | 3. **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`, `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](references/finding-docs.md).