Skip to content
Get packs

Guide · Agent skill

How to use the Drive a Virtual iPhone agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The vphone-guest-control skill teaches an AI agent how to set up and operate vphone, a tool that runs a virtual iPhone on an Apple Silicon Mac. It is for iOS developers and security researchers who already use vphone and want an agent to drive it from Claude Code or another SKILL.md-compatible agent. After reading this guide you will know what the skill does, how to install it, how to phrase requests so it triggers, and what safety limits apply.

Drive a Virtual iPhoneLakr233/vphone-cli · MIT

Quick start

  1. 1Install the app and bundle. Install vphone-launchpad and vphone-launchpad-cli, then download and verify VPhone.bundle in the app. Finish Host Setup with your administrator password and Developer Tools access.
  2. 2Download the skill ZIP. Download the vphone-guest-control ZIP from this page and unzip it.
  3. 3Place the skill folder. Move the unzipped folder into ~/.claude/skills/ or a project's .claude/skills/, or upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
  4. 4Check status. Ask the agent to run vphone-launchpad-cli status and report what is missing.
  5. 5Make a request. Ask for a concrete action on a named machine, such as starting it or taking a screenshot.
  6. 6Verify the result. Ask the agent to confirm with a screenshot or UI tree read before trusting the outcome.

What is an agent skill, and what does this one do?

An agent skill is a folder containing a SKILL.md file and reference notes. When you ask an agent something that matches the skill's description, the agent reads those instructions and follows them, so you do not have to explain the tool each time.

This skill covers vphone. Its main client is vphone-launchpad-cli, which talks to the vphone-launchpad Mac app. Through it the agent can check the app's status, create and start machines, tap, swipe, type and take screenshots in the virtual phone, call guest methods for apps, files, logs and the UI tree, and troubleshoot black screens or boot problems.

  • Checks Launchpad and helper status and tells you which Host Setup step is missing
  • Creates, starts and stops virtual iPhone machines
  • Sends taps, swipes, key input and screenshots to a running guest
  • Calls vphoned methods for apps, files, logs, processes and the UI tree
  • Installs an IPA, the roothide or rootless bootstrap, or a .deb, and sets up ssh

What you need before installing the skill

The skill cannot set up the hardware or the app for you. You need an Apple silicon Mac running macOS, the vphone-launchpad app, vphone-launchpad-cli, and VPhone.bundle downloaded and verified through the app. Host Setup needs an administrator password and Developer Tools access.

If you do not already use vphone, this skill is not the right starting point. Install vphone first using the project's guides.

  • Apple silicon Mac with macOS
  • vphone-launchpad app and vphone-launchpad-cli
  • VPhone.bundle downloaded and verified in the app
  • Administrator password and Developer Tools access for Host Setup

Install the skill from the ZIP

Download the ZIP for vphone-guest-control from this page and unzip it. Place the resulting folder in your user skills directory or in a project's skills directory.

For all your projects, use ~/.claude/skills/. For one project only, put it in that project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into the project's .claude/skills/
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP
~/.claude/skills/vphone-guest-control/SKILL.md

Trigger the skill with natural requests

You do not need to name the skill. The description tells the agent to use it whenever you mention vphone, vphone-launchpad, vphone-launchpad-cli, VPhone.bundle, vphoned, vphone.sock or a virtual iPhone on your Mac. Plain requests work well, such as asking the agent to check whether vphone is ready or to take a screenshot of a machine.

Name the machine when you have more than one. The agent is told to act on the machine you name and not to create a new one to reproduce a problem.

  • "Check whether my vphone setup is ready."
  • "Start the myphone machine and take a screenshot."
  • "Open Settings in the guest and tap Wi-Fi."
  • "Show me the apps running in the foreground on myphone."
  • "My virtual iPhone shows a black screen after boot, help me debug it."

What the agent does in a session

The agent first runs vphone-launchpad-cli status to find where you are. If the command is missing, it goes to the install reference. If Host Setup is incomplete, it tells you what to finish in the app, because it cannot enter the administrator password for you.

After an input, the agent verifies the result with a screenshot or a UI tree read. The guest is a real device with timing, so a command that returns ok does not guarantee the visible change happened. The CLI prints progress to stderr and one JSON document to stdout.

  • Reads status first and reports missing steps
  • Starts the machine you named before controlling it
  • Checks results with a screenshot or ui.describe
  • Reads stderr when a command exits with code 1
vphone-launchpad-cli status

Safety notes: scripts, network and host settings

This skill runs scripts and uses the network. It operates a virtual guest, and it can modify security-sensitive host settings if asked. The skill is written to avoid that. It says never to change SIP, boot-args, AMFI or Research Guests, and never to run bundle accept, bundle remove, cfw install or a second vm create over existing work unless you ask.

Destructive actions such as processes.kill, apps.uninstall, system.reboot and system.shutdown refuse to run without "force":true, so only ask for them when you intend that action. Keep the host API listener on loopback, because --api-listen sends its token in clear text. Do not use this skill on a real iPhone or a production device.

  • Do not run it on a real or production iPhone
  • Only approve force actions you actually want
  • Keep --api-listen on loopback
  • Do not edit a machine folder while it runs

Tips for reliable results

Check free disk space before creating a machine. IPSWs and the restore tree are large, and a full disk fails partway through with confusing errors. Creating one machine at a time is the safer pattern.

If a bundle install or machine creation is running in the app window, the CLI can go quiet while it continues. Do not start a second one. Check progress with vm log <name> --kind create.

  • Free disk space first; create one machine at a time
  • Use vphone-launchpad-cli help as the authority if versions differ
  • Quote JSON in single quotes
  • Install IPAs through installd with ideviceinstaller when testing installation
vphone-launchpad-cli help

What people use it for

  • Starting a named virtual iPhone and capturing a screenshot for a test report
  • Tapping through a flow in the guest and checking the screen with the UI tree
  • Listing apps and the foreground app while debugging an app launch
  • Reading guest logs to investigate a crash or failed launch
  • Diagnosing a black screen or a guest that will not boot to the UI

Frequently asked questions

How do I install the vphone agent skill?

Download the vphone-guest-control ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

What do I need to use vphone-guest-control?

You need an Apple silicon Mac running macOS, the vphone-launchpad app, vphone-launchpad-cli, and VPhone.bundle downloaded and verified through the app. Host Setup also needs an administrator password and Developer Tools access.

Is the vphone-guest-control skill free?

The skill is published under the MIT licence. This page does not list prices, so check the repository for the licence text and any other terms.

Can the skill install vphone for me?

No. The skill can check status and tell you what is missing, but Host Setup needs your administrator password and Developer Tools access, which you must enter yourself in the app.

Can I use this skill on a real iPhone?

No. The skill is meant for operating a virtual guest on an Apple silicon Mac. It is not for real or production iPhones.

Why does the agent ask before killing processes or rebooting?

Actions such as processes.kill, apps.uninstall, system.reboot and system.shutdown refuse to run without "force":true. The skill only passes that flag for an action you asked for.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you already run vphone on an Apple silicon Mac and want an agent to start machines, drive the guest and debug boot problems through vphone-launchpad-cli. Pick something else if you lack an Apple silicon Mac or vphone, or if you want to control a real iPhone.

Download the skill