# Vphone Guest Control

Install vphone-launchpad and VPhone.bundle, create and run vphone virtual iPhones, and...

- Repository: https://github.com/Lakr233/vphone-cli (16348 stars)
- Category: Design
- License: MIT
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add Lakr233/vphone-cli --skill vphone-guest-control -g -a claude-code -y`
Codex: `npx skills add Lakr233/vphone-cli --skill vphone-guest-control -g -a codex -y`
Cursor: `npx skills add Lakr233/vphone-cli --skill vphone-guest-control -g -a cursor -y`
Gemini CLI: `npx skills add Lakr233/vphone-cli --skill vphone-guest-control -g -a gemini-cli -y`

## Description

Install vphone-launchpad and VPhone.bundle, create and run vphone virtual iPhones, and drive a running guest from the command line with vphone-launchpad-cli and the per-machine vphone.sock. Make sure to use this skill whenever the user mentions vphone, vphone-launchpad, vphone-launchpad-cli, VPhone.bundle, vphoned, vphone.sock, or a virtual iPhone on their Mac, even if they do not name the tool. That includes setting vphone up, creating/starting/stopping a machine, tapping/swiping/typing/taking screenshots in the guest, calling a vphoned method (apps, files, logs, processes, UI tree), installing an IPA into a guest, installing the roothide/rootless bootstrap (Irisin), ssh into a guest, installing a .deb, or debugging a guest that shows a black screen or will not boot to the UI.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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.**

The rest: https://github.com/Lakr233/vphone-cli/blob/HEAD/Skills/vphone-guest-control/SKILL.md