lakr233/vphone-cliApple Silicon上で仮想iPhoneを起動・管理し、ファームウェアパッチ、脱獄（jailbreak）バリアント、iOSテスト・分析向けのセキュリティリサーチ機能を備えたツールです。
Apple Silicon Mac で仮想 iPhone を実行します。
vphone-cli は Apple の Virtualization.framework と PCC 研究用仮想マシンを使って iOS を実行します。セキュリティ研究、リバースエンジニアリング、デバッグに適しています。
1.x については 1.0.14 Release をご覧ください。2.x では 1.x で作成した仮想マシンを起動できないため、作り直す必要があります。
macOS 15 以降を搭載した物理 Apple Silicon Mac。macOS の仮想マシン上では使用できません。
十分なディスク容量。仮想マシンごとに標準で 64 GB の仮想ディスクを使用し、ファームウェアと一時ファイルにも別途容量が必要です。
ネットワーク接続。システムの復元時に署名チケットをオンラインで取得します。
セキュリティ設定の変更。macOS 復旧モードに入り、ターミナルで次のコマンドを実行してから再起動します。
csrutil enable --without debug
csrutil allow-research-guests enable
SIP は有効のまま、デバッグの制限だけを緩和します。理由と別の設定方法はホストの設定をご覧ください。
vphone-launchpad-<バージョン>-notarized.zip をダウンロードし、展開して開きます。すべてのリリースが公証済みではありません。最新リリースに -notarized ファイルがない場合は、ダウンロードガイドから公証済みのバージョンを選んでください。VPhone.bundle をダウンロードして検証し、その中の仮想マシン用プログラムがこの Mac で実行できるようにします。Launchpad がファームウェアのダウンロード、パッチの適用、システムの復元、初回起動を行います。完了後も仮想マシンは実行されたままです。
自分の iPhone と cloudOS の IPSW を使うこともできます。検証済みの組み合わせは互換性ガイドをご覧ください。
この Mac でコーディングエージェント（Claude Code、Codex など）を使っている場合は、手順を手作業で進める代わりに、次のプロンプトを貼り付けてください。エージェントは vphone スキルを読み、設定済みの部分を確認して Launchpad と VPhone.bundle をインストールします。管理者パスワードや macOS リカバリでの変更など、あなたの操作が必要な手順では止まって確認します。
この Mac に vphone をセットアップしてください。まず次のスキルを読んでください：
https://raw.githubusercontent.com/Lakr233/vphone-cli/main/Skills/vphone-guest-control/SKILL.md
および同じフォルダの references/ 以下にリンクされたファイルを読み、その手順に従います：
公証済みの最新の vphone-launchpad をインストールし（すべてのリリースに
-notarized zip があるわけではありません）、vphone-launchpad-cli を PATH に通し、
Launchpad と同じシリーズの VPhone.bundle をインストールして、
`vphone-launchpad-cli status` で確認してください。SIP、boot-args などホストの
セキュリティ設定は変更せず、ファームウェアと空きディスク容量を私が確認するまで
マシンは作成しないでください。私の操作が必要な手順では、何をすればよいかを
正確に伝えて待ってください。
仮想マシンには標準でパッケージマネージャが入っていません。インストール手順は次のとおりです。
メニューバーで Apps > Install Bootstrap… を選び、レイアウトとして roothide を選択します（rootless は非推奨です）。仮想マシンに Irisin がインストールされます。
初回のブートストラップインストールでは、Irisin で次のパッケージをまとめてチェックし、インストールボタンを長押しして Bootstrap Install を選びます。
aptbashuikittoolslaunchctlopenssh-serverこれらは一度のブートストラップインストールでまとめて導入することを推奨します。一部のパッケージは相互に依存しており（例：bash と debianutils）、特に openssh-server には循環した依存や厳密でない依存の記述があるため、通常のインストールで一つずつ導入すると途中で失敗することがあります。
初回のインストール後は、ほかのパッケージを通常どおりインストールできます。
初回のインストールに失敗した場合や、環境が不整合な状態になった場合は、その場で修復しようとせず、Apps > Uninstall Bootstrap… で環境を削除し、手順 1 からインストールし直してください。
環境を削除するには Apps > Uninstall Bootstrap… を選びます。削除後、仮想マシンは再起動します。
Option キーを押しながら Apps メニューを開くと、さらに 2 つの項目があります。
.deb を使ってインストールします。Launchpad は VPhone.bundle 内の vphone-cli を使って仮想マシンを管理しています。ターミナルから直接使うこともできます。
| 操作 | コマンド |
|---|---|
| 仮想マシンの一覧表示 | vphone-cli vm list |
| 仮想マシンの情報表示 | vphone-cli vm info myphone |
| 仮想マシンの起動 | vphone-cli vm launch myphone |
| 仮想マシンの停止 | vphone-cli vm stop myphone |
| 仮想マシンの複製 | vphone-cli vm clone myphone copy |
| 仮想マシンの書き出し | vphone-cli vm export myphone --out myphone.tzst |
| 仮想マシンの読み込み | vphone-cli vm import myphone.tzst --name restored |
仮想マシンは標準で ~/.vphone/ に保存されます。すべてのコマンドは vphone-cli <group> --help で確認できます。Launchpad を使わずに仮想マシンを作成する方法は作成と実行をご覧ください。
起動時に --api-listen を指定すると有効になります。
vphone-cli vm launch myphone --api-listen 127.0.0.1:8765
# 出力に [api] token: … と表示されます
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/v1/health
token は起動のたびに新しく生成されます。token を固定するには、環境変数 VPHONE_API_TOKEN を設定してください。token のないリクエストと Web ページからのリクエストは、どちらも拒否されます。インターフェースの説明は API ドキュメントをご覧ください。
まずトラブルシューティングをご覧ください。仮想マシン用プログラムがシステムに拒否される、復元に失敗する、「Press home to continue」で止まる、といった状況を扱っています。それでも解決しない場合は、issue を送信してください。
| ドキュメント | 内容 |
|---|---|
| ダウンロードガイド | 公証済みの Launchpad バージョンと対応する VPhone.bundle バージョン |
| ホストの設定 | SIP と AMFI の設定、ソースからのビルド、環境の確認 |
| 作成と実行 | ファームウェアの入手元、作成の流れ、ストレージとバックアップ |
| 互換性ガイド | 検証済みのファームウェアの組み合わせ |
| トラブルシューティング | よくあるエラーと対処方法 |
| ネットワーク | ネットワークモードと、Mac が VPN やプロキシを使うときの tunnel |
| Launchpad コマンドライン | vphone-launchpad-cli でローカルビルドをインストールしてテストする |
| 研究記録 | パッチと実装の詳細 |
vphone-launchpad：Mac App です。VPhone.bundle のダウンロードとインストール、ホストの設定を行います。別途配布されます。vphone-cli：ファームウェアの準備、パッチの適用、システムの復元、仮想マシンの管理を行います。vphone-vm：仮想マシンを実行し、仮想マシンのウィンドウを表示します。vphoned：仮想マシン内の制御サービスです。ウィンドウの機能と API は、すべてこれを通じて実現されています。| パス | 内容 |
|---|---|
VPhoneExecutable/ | vphone-cli、vphone-vm、ファームウェアパッチと復元 |
VPhoneKit/ | ホスト側の共有ライブラリと API クライアント |
VPhoneDaemon/ | vphoned |
VPhoneGuestComponents/ | 仮想マシン内のフックと補助プログラム |
VPhoneLaunchpad/ | Launchpad App とそのヘルパー |
ソースからのビルド：xcodebuild -workspace VPhone.xcworkspace -scheme VPhone build。成果物は VPhone.bundle です。