Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

docs: streamline README and re-sync ko/ja/zh translations

zqxwceecf798e690f9
diff --git a/README.md b/README.md
index f12eac35..1fb45e3e 100644
--- a/README.md
+++ b/README.md
@@ -4,99 +4,36 @@
Boot a virtual iPhone via Apple's Virtualization.framework using PCC research VM infrastructure.
-Everything runs through the single `vphone-cli` binary — create, patch, restore, install, boot, and manage VMs. No `make` needed after building.
-
![poc](./docs/demo.jpeg)
-## Tested Environments
-
-| Host | iPhone | CloudOS |
-| --------------- | --------------------- | --------------- |
-| Mac16,11 27.0b2 | `17,3_18.6.2_22G100` | `26.1-23B85` |
-| Mac16,8 26.5.1 | `17,3_26.0_23A341` | `26.1-23B85` |
-| Mac16,8 26.5.1 | `17,3_26.0.1_23A355` | `26.1-23B85` |
-| Mac16,12 26.3 | `17,3_26.1_23B85` | `26.1-23B85` |
-| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.1-23B85` |
-| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.3-23D128` |
-| Mac16,12 26.3 | `17,3_26.3.1_23D8133` | `26.3-23D128` |
-| Mac16,11 26.2 | `17,3_26.4_23E246` | `26.4-23E5207q` |
-| Mac16,11 26.2 | `17,3_26.5_23F77` | `26.4-23E5207q` |
-| Mac16,11 27.0b2 | `17,3_26.5.2_23F84` | `26.4-23E5207q` |
-| Mac16,6 25.4.1 | `17,3_26.6_23G71` | `26.4-23E5207q` |
-| Mac16,11 27.0b2 | `17,3_27.0_24A5380h` | `26.4-23E5207q` |
-| Mac16,6 25.4.1 | `17,3_27.0_24A5390f` | `26.4-23E5207q` |
-
-iOS ≤ 26.0.1 use the 26.1 PCC vphone600 stack plus the CFW-time `IOMobileFramebuffer` SwapEnd payload-size patch. iOS 27.0 uses the 26.4 PCC vphone600 stack plus the CFW-time force-kern `IOMobileFramebuffer` present-path patch and the dyld shared-cache `maxSlide` fit.
-
-> **Note:** GPU/Metal acceleration does not work on iOS 18.x — the 18.x Metal/IOGPU framework has no paravirtualized GPU implementation, so Metal-rendered content (web pages, images, wallpaper) does not render. Touch, networking, and apps work normally.
-
-## Firmware Variants
-
-Five patch variants with increasing security bypass — pass one to `--variant`:
-
-| Variant | Boot Chain | CFW | Notes |
-| ------------ | ----------- | --------- | ----------------------------------------------------------------- |
-| `less` | 4 patches | 2 phases | Patchless — keeps iOS mitigations enabled |
-| `regular` | 42 patches | 10 phases | AMFI/SSV/Img4/TXM bypass |
-| `dev` | 53 patches | 12 phases | + TXM entitlement/debug bypass |
-| `jb` | 113 patches | 14 phases | + full jailbreak (Sileo, TrollStore auto-install on first boot) |
-| `exp` | 141 patches | 18 phases | JB superset + anti-VM-detection research patches |
-
-See [`research/0_binary_patch_comparison.md`](./research/0_binary_patch_comparison.md) for the per-component breakdown.
-
## Prerequisites
-**Host:** macOS 15+ (Sequoia), a non-nested Mac (Virtualization.framework can't nest). The private PV=3 entitlements + unsigned-binary workflow need SIP/AMFI relaxed. Pick **one** of these two paths — the SIP setting and the AMFI setting go together, don't mix them:
-
-**Option A — fully disable SIP, then disable AMFI via boot-arg (most permissive).** In Recovery (long-press power → Terminal):
+**Host:**
-```bash
-csrutil disable
-csrutil allow-research-guests enable
-```
-
-Then reboot into macOS and set the AMFI boot-arg (needs SIP fully off to take effect):
+- Apple Silicon
+- macOS 15+ (Sequoia)
+- [SIP/AMFI relaxation to allow private PV=3 entitlements with unsigned-binary](#sipamfi-relaxation)
-```bash
-sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # reboot after
-```
-
-**Option B — keep SIP on (debug-only relaxed), then allowlist the binary with amfidont** (leaves AMFI enabled system-wide). In Recovery:
+**Dependencies:**
```bash
-csrutil enable --without debug
-csrutil allow-research-guests enable
+brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone libusb ipsw zstd
```
-Then reboot into macOS and allowlist the repo with [`amfidont`](https://github.com/zqxwce/amfidont) (or [`amfree`](https://github.com/retX0/amfree)):
+## Install
```bash
-sudo amfidont --path <path_to_vphone-cli.app>
+brew install zqxwce/tap/vphone-cli
```
-> The `less` (patchless) variant needs Option A, or Option B with `amfidont -S` (`sudo amfidont -S --path <path_to_vphone-cli.app>`).
-
-**Dependencies:**
+## Build
```bash
git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
-brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone libusb ipsw zstd
-```
-
-(A modern `python3` — 3.11+ — is required; the app builds its own Python environment from it, see [Python runtime](#python-runtime).)
-
-## Build
-Two one-time bootstrap scripts (a compiled binary can't build itself), then everything is `vphone-cli`:
-
-```bash
./scripts/setup_tools.sh # install deps, build toolchain submodules, create the Python venv
./scripts/build.sh # build + sign vphone-cli, bundle the .app, cross-compile vphoned
-```
-
-Put the binary on your `PATH` so the examples below work verbatim:
-```bash
cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help
```
@@ -107,25 +44,7 @@ One command creates a VM end-to-end (download → patch → DFU restore → CFW
```bash
vphone-cli vm create myphone -V jb # -V / --variant
-```
-The user is then prompted to choose iOS <-> cloudOS paring, you can specify either one by passing **`-i`/`--iphone-source`** and/or **`-c`/`--cloudos-source`**, i.e.:
-
-```bash
-# from local IPSWs
-vphone-cli vm create myphone -V jb \
- -i ~/ipsws/iPhone17,3_26.1_23B85_Restore.ipsw \
- -c ~/ipsws/cloudOS_26.1-23B85.ipsw
-
-# or from URLs — downloaded and cached under ~/.vphone/ipsws
-vphone-cli vm create myphone -V jb \
- -i "https://.../iPhone17,3_26.1_23B85_Restore.ipsw" \
- -c "https://.../399b6..."
-```
-
-Then boot it:
-
-```bash
vphone-cli vm launch myphone
```
@@ -165,25 +84,25 @@ vphone-cli vm launch myphone # 6. first boot
Update to a newer iOS by pointing `fw prepare` at an IPSW: `--iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw`.
-## Running & Connecting
+## Firmware Variants
-`vphone-cli vm launch <name>` opens the VM window; `vphone-cli vm stop <name>` shuts it down. The guest runs an SSH server (dropbear) on port `22222` and VNC on `5901`, reachable over the VM's NAT IP (find it with `arp -a` on `bridge100`):
+Five patch variants with increasing security bypass — pass one to `--variant`:
-- **SSH (jailbreak):** `ssh -p 22222 mobile@<vm-ip>` (password `alpine`)
-- **SSH (regular/dev):** `ssh -p 22222 root@<vm-ip>`
-- **VNC:** `vnc://<vm-ip>:5901`
+| Variant | Boot Chain | CFW | Notes |
+| ------------ | ----------- | --------- | ----------------------------------------------------------------- |
+| `less` | 4 patches | 2 phases | Patchless — keeps iOS mitigations enabled |
+| `regular` | 42 patches | 10 phases | AMFI/SSV/Img4/TXM bypass |
+| `dev` | 53 patches | 12 phases | + TXM entitlement/debug bypass |
+| `jb` | 113 patches | 14 phases | + full jailbreak (Sileo, TrollStore auto-install on first boot) |
+| `exp` | 141 patches | 18 phases | JB superset + anti-VM-detection research patches |
-For the `jb`/`exp` variants, Sileo and TrollStore are installed automatically on first boot (monitor `/var/log/vphone_jb_setup.log`).
+See [`research/0_binary_patch_comparison.md`](./research/0_binary_patch_comparison.md) for the per-component breakdown.
-## Python runtime
+## Running & Connecting
-A few steps (DFU restore, IPSW handling) run through Python. On first use,
-vphone-cli provisions a self-contained venv at `~/.vphone/venv` from a modern
-host `python3` (3.11+) using the bundled `requirements.txt` — so the signed
-`.app` is **portable**: copy it anywhere (e.g. `/Applications`) and it runs
-without the repo. Provisioning is automatic; run `vphone-cli setup` to do it
-up front. Point at a specific interpreter with `VPHONE_PYTHON=/path/to/python3`,
-or relocate the venv with `VPHONE_VENV_DIR=/path`.
+- **SSH (jailbreak):** `ssh -p 22222 mobile@<vm-ip>` (password `alpine`)
+- **SSH (regular/dev):** `ssh -p 22222 root@<vm-ip>`
+- **VNC:** `vnc://<vm-ip>:5901`
## Locations
@@ -197,6 +116,56 @@ Everything vphone-cli creates lives under `~/.vphone/` — kept outside the repo
| `~/.vphone/debs/` | Cached `.deb` packages the `jb`/`exp` CFW install lays into the guest (Sileo, apt, …). |
| `~/.vphone/venv/` | Auto-provisioned Python environment (see [Python runtime](#python-runtime); override with `$VPHONE_VENV_DIR`). |
+## SIP/AMFI Relaxation
+
+**Option A — fully disable SIP, then disable AMFI via boot-arg (most permissive).**
+
+In Recovery (long-press power → Terminal):
+
+```bash
+csrutil disable
+csrutil allow-research-guests enable
+```
+
+Then reboot into macOS and set the AMFI boot-arg (needs SIP fully off to take effect):
+
+```bash
+sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # reboot after
+```
+
+**Option B — keep SIP on (debug-only relaxed), then allowlist the binary with amfidont** (leaves AMFI enabled system-wide).
+
+In Recovery:
+
+```bash
+csrutil enable --without debug
+csrutil allow-research-guests enable
+```
+
+Then reboot into macOS and:
+
+```bash
+vphone-amfidont # .build/vphone-cli.app/Contents/Resources/vphone-amfidont for local builds
+```
+
+## Tested Environments
+
+| Host | iPhone | CloudOS |
+| --------------- | --------------------- | --------------- |
+| Mac16,11 27.0b2 | `17,3_18.6.2_22G100` | `26.1-23B85` |
+| Mac16,8 26.5.1 | `17,3_26.0_23A341` | `26.1-23B85` |
+| Mac16,8 26.5.1 | `17,3_26.0.1_23A355` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.1_23B85` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.3-23D128` |
+| Mac16,12 26.3 | `17,3_26.3.1_23D8133` | `26.3-23D128` |
+| Mac16,11 26.2 | `17,3_26.4_23E246` | `26.4-23E5207q` |
+| Mac16,11 26.2 | `17,3_26.5_23F77` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_26.5.2_23F84` | `26.4-23E5207q` |
+| Mac16,6 25.4.1 | `17,3_26.6_23G71` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_27.0_24A5380h` | `26.4-23E5207q` |
+| Mac16,6 25.4.1 | `17,3_27.0_24A5390f` | `26.4-23E5207q` |
+
## FAQ
**`zsh: killed ./vphone-cli`** — AMFI/debug restrictions aren't bypassed; see [Prerequisites](#prerequisites) (`amfi_get_out_of_my_way=1` or `amfidont`).
diff --git a/docs/README_ja.md b/docs/README_ja.md
index 25eeb611..3fd8893d 100644
--- a/docs/README_ja.md
+++ b/docs/README_ja.md
@@ -4,99 +4,36 @@
PCC リサーチ VM インフラストラクチャを使用し、Apple の Virtualization.framework 経由で仮想 iPhone を起動します。
-すべての処理は単一の `vphone-cli` バイナリを通じて実行されます — VM の作成、パッチ適用、復元、インストール、起動、管理。ビルド後は `make` は不要です。
-
![poc](./demo.jpeg)
-## 動作確認済み環境
-
-| ホスト | iPhone | CloudOS |
-| --------------- | --------------------- | --------------- |
-| Mac16,11 27.0b2 | `17,3_18.6.2_22G100` | `26.1-23B85` |
-| Mac16,8 26.5.1 | `17,3_26.0_23A341` | `26.1-23B85` |
-| Mac16,8 26.5.1 | `17,3_26.0.1_23A355` | `26.1-23B85` |
-| Mac16,12 26.3 | `17,3_26.1_23B85` | `26.1-23B85` |
-| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.1-23B85` |
-| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.3-23D128` |
-| Mac16,12 26.3 | `17,3_26.3.1_23D8133` | `26.3-23D128` |
-| Mac16,11 26.2 | `17,3_26.4_23E246` | `26.4-23E5207q` |
-| Mac16,11 26.2 | `17,3_26.5_23F77` | `26.4-23E5207q` |
-| Mac16,11 27.0b2 | `17,3_26.5.2_23F84` | `26.4-23E5207q` |
-| Mac16,6 25.4.1 | `17,3_26.6_23G71` | `26.4-23E5207q` |
-| Mac16,11 27.0b2 | `17,3_27.0_24A5380h` | `26.4-23E5207q` |
-| Mac16,6 25.4.1 | `17,3_27.0_24A5390f` | `26.4-23E5207q` |
-
-iOS ≤ 26.0.1 では 26.1 PCC vphone600 スタックと、CFW 適用時の `IOMobileFramebuffer` SwapEnd ペイロードサイズパッチを使用します。iOS 27.0 では 26.4 PCC vphone600 スタックと、CFW 適用時の force-kern `IOMobileFramebuffer` present-path パッチ、および dyld shared-cache の `maxSlide` フィットを使用します。
-
-> **注意:** GPU/Metal アクセラレーションは iOS 18.x では動作しません — 18.x の Metal/IOGPU フレームワークには準仮想化 GPU 実装がないため、Metal でレンダリングされるコンテンツ(Web ページ、画像、壁紙)は描画されません。タッチ、ネットワーク、アプリは正常に動作します。
-
-## ファームウェアバリアント
-
-セキュリティバイパスの度合いが段階的に増す 5 つのパッチバリアント — いずれか 1 つを `--variant` に渡します:
-
-| バリアント | ブートチェーン | CFW | 備考 |
-| ------------ | ----------- | --------- | ----------------------------------------------------------------- |
-| `less` | 4 patches | 2 phases | パッチなし — iOS の緩和策を有効なまま維持 |
-| `regular` | 42 patches | 10 phases | AMFI/SSV/Img4/TXM バイパス |
-| `dev` | 53 patches | 12 phases | + TXM エンタイトルメント/デバッグバイパス |
-| `jb` | 113 patches | 14 phases | + 完全な脱獄(Sileo、TrollStore を初回起動時に自動インストール) |
-| `exp` | 141 patches | 18 phases | JB のスーパーセット + VM 検出対策リサーチパッチ |
-
-コンポーネントごとの内訳については [`research/0_binary_patch_comparison.md`](../research/0_binary_patch_comparison.md) を参照してください。
-
## 前提条件
-**ホスト:** macOS 15+ (Sequoia)、ネストされていない Mac(Virtualization.framework はネストできません)。プライベートな PV=3 エンタイトルメント + 未署名バイナリのワークフローには SIP/AMFI の緩和が必要です。以下の 2 つの方法から **1 つ** を選んでください — SIP の設定と AMFI の設定はセットです。混在させないでください:
-
-**オプション A — SIP を完全に無効化し、boot-arg で AMFI を無効化する(最も緩い)。** リカバリーモードで(電源ボタン長押し → ターミナル):
+**ホスト:**
-```bash
-csrutil disable
-csrutil allow-research-guests enable
-```
-
-その後 macOS で再起動し、AMFI の boot-arg を設定します(有効化には SIP を完全に無効化する必要があります):
+- Apple Silicon
+- macOS 15+ (Sequoia)
+- [未署名バイナリでプライベートな PV=3 エンタイトルメントを許可するための SIP/AMFI の緩和](#sipamfi-の緩和)
-```bash
-sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # 後で再起動
-```
-
-**オプション B — SIP を有効なまま(デバッグのみ緩和)にし、amfidont でバイナリを許可リストに追加する**(AMFI はシステム全体で有効なまま)。リカバリーモードで:
+**依存関係:**
```bash
-csrutil enable --without debug
-csrutil allow-research-guests enable
+brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone libusb ipsw zstd
```
-その後 macOS で再起動し、[`amfidont`](https://github.com/zqxwce/amfidont)(または [`amfree`](https://github.com/retX0/amfree))でリポジトリを許可リストに追加します:
+## インストール
```bash
-sudo amfidont --path <path_to_vphone-cli.app>
+brew install zqxwce/tap/vphone-cli
```
-> `less`(パッチなし)バリアントにはオプション A、またはオプション B に `amfidont -S` を組み合わせたもの(`sudo amfidont -S --path <path_to_vphone-cli.app>`)が必要です。
-
-**依存関係:**
+## ビルド
```bash
git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
-brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone libusb ipsw zstd
-```
-
-(最新の `python3` — 3.11+ — が必要です。アプリはそこから独自の Python 環境を構築します。[Python ランタイム](#python-ランタイム) を参照してください。)
-
-## ビルド
-一度きりのブートストラップスクリプトが 2 つあります(コンパイル済みバイナリは自分自身をビルドできないため)。その後はすべて `vphone-cli` で行います:
-
-```bash
./scripts/setup_tools.sh # 依存関係のインストール、ツールチェーンのサブモジュールのビルド、Python venv の作成
./scripts/build.sh # vphone-cli のビルド + 署名、.app のバンドル、vphoned のクロスコンパイル
-```
-
-以下の例をそのまま実行できるように、バイナリを `PATH` に追加します:
-```bash
cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help
```
@@ -107,25 +44,7 @@ vphone-cli --help
```bash
vphone-cli vm create myphone -V jb # -V / --variant
-```
-その後、iOS <-> cloudOS のペアリングを選ぶよう促されます。**`-i`/`--iphone-source`** および/または **`-c`/`--cloudos-source`** を渡して、どちらか(または両方)を指定することもできます。例:
-
-```bash
-# ローカルの IPSW から
-vphone-cli vm create myphone -V jb \
- -i ~/ipsws/iPhone17,3_26.1_23B85_Restore.ipsw \
- -c ~/ipsws/cloudOS_26.1-23B85.ipsw
-
-# または URL から — ~/.vphone/ipsws 以下にダウンロードしてキャッシュ
-vphone-cli vm create myphone -V jb \
- -i "https://.../iPhone17,3_26.1_23B85_Restore.ipsw" \
- -c "https://.../399b6..."
-```
-
-その後、起動します:
-
-```bash
vphone-cli vm launch myphone
```
@@ -165,19 +84,25 @@ vphone-cli vm launch myphone # 6. 初回起動
新しい iOS に更新するには、`fw prepare` を IPSW に向けます: `--iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw`。
-## 実行と接続
+## ファームウェアバリアント
-`vphone-cli vm launch <name>` は VM のウィンドウを開き、`vphone-cli vm stop <name>` はシャットダウンします。ゲストはポート `22222` で SSH サーバー(dropbear)を、`5901` で VNC を実行しており、VM の NAT IP 経由でアクセスできます(`bridge100` 上で `arp -a` を実行して確認):
+セキュリティバイパスの度合いが段階的に増す 5 つのパッチバリアント — いずれか 1 つを `--variant` に渡します:
-- **SSH(脱獄):** `ssh -p 22222 mobile@<vm-ip>`(パスワード `alpine`)
-- **SSH(regular/dev):** `ssh -p 22222 root@<vm-ip>`
-- **VNC:** `vnc://<vm-ip>:5901`
+| バリアント | ブートチェーン | CFW | 備考 |
+| ------------ | ----------- | --------- | ----------------------------------------------------------------- |
+| `less` | 4 patches | 2 phases | パッチなし — iOS の緩和策を有効なまま維持 |
+| `regular` | 42 patches | 10 phases | AMFI/SSV/Img4/TXM バイパス |
+| `dev` | 53 patches | 12 phases | + TXM エンタイトルメント/デバッグバイパス |
+| `jb` | 113 patches | 14 phases | + 完全な脱獄(Sileo、TrollStore を初回起動時に自動インストール) |
+| `exp` | 141 patches | 18 phases | JB のスーパーセット + VM 検出対策リサーチパッチ |
-`jb`/`exp` バリアントでは、Sileo と TrollStore が初回起動時に自動的にインストールされます(`/var/log/vphone_jb_setup.log` で監視)。
+コンポーネントごとの内訳については [`research/0_binary_patch_comparison.md`](../research/0_binary_patch_comparison.md) を参照してください。
-## Python ランタイム
+## 実行と接続
-いくつかのステップ(DFU 復元、IPSW 処理)は Python を通じて実行されます。初回使用時、vphone-cli はバンドルされた `requirements.txt` を使用して、最新のホスト `python3`(3.11+)から `~/.vphone/venv` に自己完結型の venv をプロビジョニングします — そのため署名済みの `.app` は **ポータブル** です。任意の場所(例: `/Applications`)にコピーすればリポジトリなしで動作します。プロビジョニングは自動ですが、事前に行うには `vphone-cli setup` を実行します。特定のインタプリタを指定するには `VPHONE_PYTHON=/path/to/python3`、venv の場所を変更するには `VPHONE_VENV_DIR=/path` を使用します。
+- **SSH(脱獄):** `ssh -p 22222 mobile@<vm-ip>`(パスワード `alpine`)
+- **SSH(regular/dev):** `ssh -p 22222 root@<vm-ip>`
+- **VNC:** `vnc://<vm-ip>:5901`
## 場所
@@ -185,12 +110,62 @@ vphone-cli が生成するものはすべて `~/.vphone/` 以下に置かれま
| パス | 内容 |
| ----------------- | ------------------------------------------------------------------------------------------ |
-| `~/.vphone/VMs/` | VM バンドル — VM ごとに 1 ディレクトリ。ライブラリであり、`$VPHONE_LIBRARY_ROOT` で上書きできます。 |
+| `~/.vphone/VMs/` | VM バンドル — VM ごとに 1 ディレクトリ。これがライブラリです。`$VPHONE_LIBRARY_ROOT` で上書きできます。 |
| `~/.vphone/ipsws/`| ダウンロードされた iPhone + cloudOS の IPSW。キャッシュされ、複数の VM で再利用されます。 |
| `~/.vphone/tools/`| `fw prepare` 中に取得された APFS seal-volume アーティファクト(`apfs_sealvolume_<version>`)のキャッシュ。 |
| `~/.vphone/debs/` | `jb`/`exp` の CFW インストールがゲストに配置する `.deb` パッケージのキャッシュ(Sileo、apt など)。 |
| `~/.vphone/venv/` | 自動的にプロビジョニングされる Python 環境([Python ランタイム](#python-ランタイム) を参照。`$VPHONE_VENV_DIR` で上書き可能)。 |
+## SIP/AMFI の緩和
+
+**オプション A — SIP を完全に無効化し、boot-arg で AMFI を無効化する(最も緩い)。**
+
+リカバリーモードで(電源ボタン長押し → ターミナル):
+
+```bash
+csrutil disable
+csrutil allow-research-guests enable
+```
+
+その後 macOS で再起動し、AMFI の boot-arg を設定します(有効化には SIP を完全に無効化する必要があります):
+
+```bash
+sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # 後で再起動
+```
+
+**オプション B — SIP を有効なまま(デバッグのみ緩和)にし、amfidont でバイナリを許可リストに追加する**(AMFI はシステム全体で有効なまま)。
+
+リカバリーモードで:
+
+```bash
+csrutil enable --without debug
+csrutil allow-research-guests enable
+```
+
+その後 macOS で再起動し:
+
+```bash
+vphone-amfidont # ローカルビルドの場合は .build/vphone-cli.app/Contents/Resources/vphone-amfidont
+```
+
+## 動作確認済み環境
+
+| ホスト | iPhone | CloudOS |
+| --------------- | --------------------- | --------------- |
+| Mac16,11 27.0b2 | `17,3_18.6.2_22G100` | `26.1-23B85` |
+| Mac16,8 26.5.1 | `17,3_26.0_23A341` | `26.1-23B85` |
+| Mac16,8 26.5.1 | `17,3_26.0.1_23A355` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.1_23B85` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.3-23D128` |
+| Mac16,12 26.3 | `17,3_26.3.1_23D8133` | `26.3-23D128` |
+| Mac16,11 26.2 | `17,3_26.4_23E246` | `26.4-23E5207q` |
+| Mac16,11 26.2 | `17,3_26.5_23F77` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_26.5.2_23F84` | `26.4-23E5207q` |
+| Mac16,6 25.4.1 | `17,3_26.6_23G71` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_27.0_24A5380h` | `26.4-23E5207q` |
+| Mac16,6 25.4.1 | `17,3_27.0_24A5390f` | `26.4-23E5207q` |
+
## FAQ
**`zsh: killed ./vphone-cli`** — AMFI/デバッグ制限がバイパスされていません。[前提条件](#前提条件) を参照してください(`amfi_get_out_of_my_way=1` または `amfidont`)。
diff --git a/docs/README_ko.md b/docs/README_ko.md
index fbaec127..8661cab3 100644
--- a/docs/README_ko.md
+++ b/docs/README_ko.md
@@ -4,99 +4,36 @@
PCC 리서치 VM 인프라를 사용하여 Apple의 Virtualization.framework로 가상 iPhone을 부팅합니다.
-모든 것은 단일 `vphone-cli` 바이너리를 통해 실행됩니다 — VM 생성, 패치, 복원, 설치, 부팅, 관리. 빌드 후에는 `make`가 필요하지 않습니다.
-
![poc](./demo.jpeg)
-## 테스트 환경
-
-| Host | iPhone | CloudOS |
-| --------------- | --------------------- | --------------- |
-| Mac16,11 27.0b2 | `17,3_18.6.2_22G100` | `26.1-23B85` |
-| Mac16,8 26.5.1 | `17,3_26.0_23A341` | `26.1-23B85` |
-| Mac16,8 26.5.1 | `17,3_26.0.1_23A355` | `26.1-23B85` |
-| Mac16,12 26.3 | `17,3_26.1_23B85` | `26.1-23B85` |
-| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.1-23B85` |
-| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.3-23D128` |
-| Mac16,12 26.3 | `17,3_26.3.1_23D8133` | `26.3-23D128` |
-| Mac16,11 26.2 | `17,3_26.4_23E246` | `26.4-23E5207q` |
-| Mac16,11 26.2 | `17,3_26.5_23F77` | `26.4-23E5207q` |
-| Mac16,11 27.0b2 | `17,3_26.5.2_23F84` | `26.4-23E5207q` |
-| Mac16,6 25.4.1 | `17,3_26.6_23G71` | `26.4-23E5207q` |
-| Mac16,11 27.0b2 | `17,3_27.0_24A5380h` | `26.4-23E5207q` |
-| Mac16,6 25.4.1 | `17,3_27.0_24A5390f` | `26.4-23E5207q` |
-
-iOS ≤ 26.0.1은 26.1 PCC vphone600 스택에 더해 CFW 단계의 `IOMobileFramebuffer` SwapEnd 페이로드 크기 패치를 사용합니다. iOS 27.0은 26.4 PCC vphone600 스택에 더해 CFW 단계의 force-kern `IOMobileFramebuffer` present-path 패치와 dyld 공유 캐시 `maxSlide` 조정을 사용합니다.
-
-> **참고:** iOS 18.x에서는 GPU/Metal 가속이 작동하지 않습니다 — 18.x의 Metal/IOGPU 프레임워크에 반가상화 GPU 구현이 없기 때문에 Metal로 렌더링되는 콘텐츠(웹 페이지, 이미지, 배경화면)가 표시되지 않습니다. 터치, 네트워크, 앱은 정상적으로 작동합니다.
-
-## 펌웨어 변형
-
-보안 우회 수준이 점점 강해지는 5가지 패치 변형이 있습니다 — 하나를 `--variant`에 전달하세요:
-
-| 변형 | 부트 체인 | CFW | 참고 |
-| ------------ | ----------- | --------- | --------------------------------------------------------------- |
-| `less` | 4 patches | 2 phases | Patchless — iOS 완화 기능을 활성 상태로 유지 |
-| `regular` | 42 patches | 10 phases | AMFI/SSV/Img4/TXM 우회 |
-| `dev` | 53 patches | 12 phases | + TXM 권한/디버그 우회 |
-| `jb` | 113 patches | 14 phases | + 전체 탈옥 (Sileo, TrollStore가 첫 부팅 시 자동 설치) |
-| `exp` | 141 patches | 18 phases | JB 상위 집합 + VM 탐지 방지 연구 패치 |
-
-컴포넌트별 상세 분류는 [`research/0_binary_patch_comparison.md`](../research/0_binary_patch_comparison.md)를 참조하세요.
-
## 사전 요구 사항
-**호스트:** macOS 15+ (Sequoia), 중첩되지 않은 Mac (Virtualization.framework는 중첩할 수 없습니다). Private PV=3 권한 + 서명되지 않은 바이너리 워크플로우에는 SIP/AMFI 완화가 필요합니다. 다음 두 가지 방법 중 **하나**를 선택하세요 — SIP 설정과 AMFI 설정은 함께 가야 하므로 섞지 마세요:
-
-**방법 A — SIP를 완전히 비활성화한 후, boot-arg로 AMFI를 비활성화 (가장 관대).** 복구 모드에서 (전원 버튼 길게 누르기 → 터미널):
-
-```bash
-csrutil disable
-csrutil allow-research-guests enable
-```
-
-그런 다음 macOS로 재부팅하고 AMFI boot-arg를 설정합니다 (적용되려면 SIP가 완전히 꺼져 있어야 합니다):
+**호스트:**
-```bash
-sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # 이후 재부팅
-```
+- Apple Silicon
+- macOS 15+ (Sequoia)
+- [서명되지 않은 바이너리로 private PV=3 권한을 허용하기 위한 SIP/AMFI 완화](#sipamfi-완화)
-**방법 B — SIP 유지 (디버그만 완화), 그런 다음 amfidont로 바이너리를 허용 목록에 추가** (AMFI는 시스템 전체에서 활성 상태 유지). 복구 모드에서:
+**의존성:**
```bash
-csrutil enable --without debug
-csrutil allow-research-guests enable
+brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone libusb ipsw zstd
```
-그런 다음 macOS로 재부팅하고 [`amfidont`](https://github.com/zqxwce/amfidont) (또는 [`amfree`](https://github.com/retX0/amfree))로 저장소를 허용 목록에 추가합니다:
+## 설치
```bash
-sudo amfidont --path <path_to_vphone-cli.app>
+brew install zqxwce/tap/vphone-cli
```
-> `less` (patchless) 변형은 방법 A, 또는 `amfidont -S`를 포함한 방법 B(`sudo amfidont -S --path <path_to_vphone-cli.app>`)가 필요합니다.
-
-**의존성:**
+## 빌드
```bash
git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
-brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone libusb ipsw zstd
-```
-
-(최신 `python3` — 3.11+ — 이 필요합니다; 앱은 이를 사용하여 자체 Python 환경을 빌드합니다. [Python 런타임](#python-런타임)을 참조하세요.)
-
-## 빌드
-두 개의 일회성 부트스트랩 스크립트(컴파일된 바이너리는 스스로를 빌드할 수 없습니다)를 실행하면, 그 다음부터는 모든 것이 `vphone-cli`입니다:
-
-```bash
./scripts/setup_tools.sh # 의존성 설치, 툴체인 서브모듈 빌드, Python venv 생성
./scripts/build.sh # vphone-cli 빌드 및 서명, .app 번들 생성, vphoned 크로스 컴파일
-```
-
-아래 예제가 그대로 작동하도록 바이너리를 `PATH`에 추가하세요:
-```bash
cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help
```
@@ -107,25 +44,7 @@ vphone-cli --help
```bash
vphone-cli vm create myphone -V jb # -V / --variant
-```
-그러면 iOS <-> cloudOS 페어링을 선택하라는 안내가 표시됩니다. **`-i`/`--iphone-source`** 및/또는 **`-c`/`--cloudos-source`**를 전달하여 둘 중 하나(또는 둘 다)를 직접 지정할 수도 있습니다. 예:
-
-```bash
-# 로컬 IPSW에서
-vphone-cli vm create myphone -V jb \
- -i ~/ipsws/iPhone17,3_26.1_23B85_Restore.ipsw \
- -c ~/ipsws/cloudOS_26.1-23B85.ipsw
-
-# 또는 URL에서 — 다운로드되어 ~/.vphone/ipsws 아래에 캐시됨
-vphone-cli vm create myphone -V jb \
- -i "https://.../iPhone17,3_26.1_23B85_Restore.ipsw" \
- -c "https://.../399b6..."
-```
-
-그런 다음 부팅합니다:
-
-```bash
vphone-cli vm launch myphone
```
@@ -165,25 +84,25 @@ vphone-cli vm launch myphone # 6. 첫 부팅
최신 iOS로 업데이트하려면 `fw prepare`를 IPSW로 지정하세요: `--iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw`.
-## 실행 및 연결
+## 펌웨어 변형
-`vphone-cli vm launch <name>`은 VM 창을 엽니다; `vphone-cli vm stop <name>`은 종료합니다. 게스트는 포트 `22222`에서 SSH 서버(dropbear)를, `5901`에서 VNC를 실행하며, VM의 NAT IP로 접근할 수 있습니다 (`bridge100`에서 `arp -a`로 찾으세요):
+보안 우회 수준이 점점 강해지는 5가지 패치 변형이 있습니다 — 하나를 `--variant`에 전달하세요:
-- **SSH (탈옥):** `ssh -p 22222 mobile@<vm-ip>` (비밀번호 `alpine`)
-- **SSH (regular/dev):** `ssh -p 22222 root@<vm-ip>`
-- **VNC:** `vnc://<vm-ip>:5901`
+| 변형 | 부트 체인 | CFW | 참고 |
+| ------------ | ----------- | --------- | --------------------------------------------------------------- |
+| `less` | 4 patches | 2 phases | Patchless — iOS 완화 기능을 활성 상태로 유지 |
+| `regular` | 42 patches | 10 phases | AMFI/SSV/Img4/TXM 우회 |
+| `dev` | 53 patches | 12 phases | + TXM 권한/디버그 우회 |
+| `jb` | 113 patches | 14 phases | + 전체 탈옥 (Sileo, TrollStore가 첫 부팅 시 자동 설치) |
+| `exp` | 141 patches | 18 phases | JB 상위 집합 + VM 탐지 방지 연구 패치 |
-`jb`/`exp` 변형의 경우, Sileo와 TrollStore가 첫 부팅 시 자동으로 설치됩니다 (`/var/log/vphone_jb_setup.log`로 모니터링).
+컴포넌트별 상세 분류는 [`research/0_binary_patch_comparison.md`](../research/0_binary_patch_comparison.md)를 참조하세요.
-## Python 런타임
+## 실행 및 연결
-일부 단계(DFU 복원, IPSW 처리)는 Python을 통해 실행됩니다. 최초 사용 시,
-vphone-cli는 번들된 `requirements.txt`를 사용하여 최신 호스트 `python3`(3.11+)로부터
-`~/.vphone/venv`에 독립적인 venv를 프로비저닝합니다 — 따라서 서명된
-`.app`은 **이식 가능**합니다: 어디든(예: `/Applications`) 복사하면 저장소
-없이도 실행됩니다. 프로비저닝은 자동으로 이루어집니다; 미리 실행하려면 `vphone-cli setup`을
-실행하세요. 특정 인터프리터를 지정하려면 `VPHONE_PYTHON=/path/to/python3`을,
-venv 위치를 변경하려면 `VPHONE_VENV_DIR=/path`를 사용하세요.
+- **SSH (탈옥):** `ssh -p 22222 mobile@<vm-ip>` (비밀번호 `alpine`)
+- **SSH (regular/dev):** `ssh -p 22222 root@<vm-ip>`
+- **VNC:** `vnc://<vm-ip>:5901`
## 위치
@@ -197,6 +116,56 @@ vphone-cli가 생성하는 모든 것은 `~/.vphone/` 아래에 있습니다 —
| `~/.vphone/debs/` | `jb`/`exp` CFW 설치가 게스트에 넣는 `.deb` 패키지 캐시 (Sileo, apt 등). |
| `~/.vphone/venv/` | 자동으로 프로비저닝되는 Python 환경 ([Python 런타임](#python-런타임) 참조; `$VPHONE_VENV_DIR`로 재정의). |
+## SIP/AMFI 완화
+
+**방법 A — SIP를 완전히 비활성화한 후, boot-arg로 AMFI를 비활성화 (가장 관대).**
+
+복구 모드에서 (전원 버튼 길게 누르기 → 터미널):
+
+```bash
+csrutil disable
+csrutil allow-research-guests enable
+```
+
+그런 다음 macOS로 재부팅하고 AMFI boot-arg를 설정합니다 (적용되려면 SIP가 완전히 꺼져 있어야 합니다):
+
+```bash
+sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # 이후 재부팅
+```
+
+**방법 B — SIP 유지 (디버그만 완화), 그런 다음 amfidont로 바이너리를 허용 목록에 추가** (AMFI는 시스템 전체에서 활성 상태 유지).
+
+복구 모드에서:
+
+```bash
+csrutil enable --without debug
+csrutil allow-research-guests enable
+```
+
+그런 다음 macOS로 재부팅하고:
+
+```bash
+vphone-amfidont # 로컬 빌드의 경우 .build/vphone-cli.app/Contents/Resources/vphone-amfidont
+```
+
+## 테스트 환경
+
+| 호스트 | iPhone | CloudOS |
+| --------------- | --------------------- | --------------- |
+| Mac16,11 27.0b2 | `17,3_18.6.2_22G100` | `26.1-23B85` |
+| Mac16,8 26.5.1 | `17,3_26.0_23A341` | `26.1-23B85` |
+| Mac16,8 26.5.1 | `17,3_26.0.1_23A355` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.1_23B85` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.3-23D128` |
+| Mac16,12 26.3 | `17,3_26.3.1_23D8133` | `26.3-23D128` |
+| Mac16,11 26.2 | `17,3_26.4_23E246` | `26.4-23E5207q` |
+| Mac16,11 26.2 | `17,3_26.5_23F77` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_26.5.2_23F84` | `26.4-23E5207q` |
+| Mac16,6 25.4.1 | `17,3_26.6_23G71` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_27.0_24A5380h` | `26.4-23E5207q` |
+| Mac16,6 25.4.1 | `17,3_27.0_24A5390f` | `26.4-23E5207q` |
+
## FAQ
**`zsh: killed ./vphone-cli`** — AMFI/디버그 제한이 우회되지 않았습니다; [사전 요구 사항](#사전-요구-사항)을 참조하세요 (`amfi_get_out_of_my_way=1` 또는 `amfidont`).
diff --git a/docs/README_zh.md b/docs/README_zh.md
index 1927ae32..ee886f15 100644
--- a/docs/README_zh.md
+++ b/docs/README_zh.md
@@ -4,99 +4,36 @@
使用 PCC 研究虚拟机基础设施,通过 Apple 的 Virtualization.framework 启动一台虚拟 iPhone。
-所有操作都通过单个 `vphone-cli` 二进制文件完成——创建、打补丁、恢复、安装、启动以及管理虚拟机。构建完成后无需再使用 `make`。
-
![poc](./demo.jpeg)
-## 测试环境
-
-| 宿主机 | iPhone | CloudOS |
-| --------------- | --------------------- | --------------- |
-| Mac16,11 27.0b2 | `17,3_18.6.2_22G100` | `26.1-23B85` |
-| Mac16,8 26.5.1 | `17,3_26.0_23A341` | `26.1-23B85` |
-| Mac16,8 26.5.1 | `17,3_26.0.1_23A355` | `26.1-23B85` |
-| Mac16,12 26.3 | `17,3_26.1_23B85` | `26.1-23B85` |
-| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.1-23B85` |
-| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.3-23D128` |
-| Mac16,12 26.3 | `17,3_26.3.1_23D8133` | `26.3-23D128` |
-| Mac16,11 26.2 | `17,3_26.4_23E246` | `26.4-23E5207q` |
-| Mac16,11 26.2 | `17,3_26.5_23F77` | `26.4-23E5207q` |
-| Mac16,11 27.0b2 | `17,3_26.5.2_23F84` | `26.4-23E5207q` |
-| Mac16,6 25.4.1 | `17,3_26.6_23G71` | `26.4-23E5207q` |
-| Mac16,11 27.0b2 | `17,3_27.0_24A5380h` | `26.4-23E5207q` |
-| Mac16,6 25.4.1 | `17,3_27.0_24A5390f` | `26.4-23E5207q` |
-
-iOS ≤ 26.0.1 使用 26.1 PCC vphone600 栈,外加 CFW 阶段的 `IOMobileFramebuffer` SwapEnd 载荷大小补丁。iOS 27.0 使用 26.4 PCC vphone600 栈,外加 CFW 阶段的强制内核 `IOMobileFramebuffer` present-path 补丁以及 dyld 共享缓存 `maxSlide` 适配。
-
-> **注意:** GPU/Metal 加速在 iOS 18.x 上无法工作——18.x 的 Metal/IOGPU 框架没有半虚拟化 GPU 实现,因此由 Metal 渲染的内容(网页、图片、壁纸)不会显示。触控、网络和应用可正常工作。
-
-## 固件变体
-
-五种补丁变体,安全绕过程度递增——将其中之一传给 `--variant`:
-
-| 变体 | 引导链 | CFW | 说明 |
-| ------------ | ----------- | --------- | ------------------------------------------------- |
-| `less` | 4 patches | 2 phases | 无补丁——保持 iOS 缓解措施启用 |
-| `regular` | 42 patches | 10 phases | 绕过 AMFI/SSV/Img4/TXM |
-| `dev` | 53 patches | 12 phases | + 绕过 TXM 授权/调试 |
-| `jb` | 113 patches | 14 phases | + 完整越狱(首次启动时自动安装 Sileo、TrollStore)|
-| `exp` | 141 patches | 18 phases | JB 超集 + 反虚拟机检测研究补丁 |
-
-各组件的详细拆解见 [`research/0_binary_patch_comparison.md`](../research/0_binary_patch_comparison.md)。
-
## 前置条件
-**宿主机:** macOS 15+(Sequoia),一台非嵌套的 Mac(Virtualization.framework 无法嵌套)。私有 PV=3 授权 + 未签名二进制的工作流需要放宽 SIP/AMFI。请从以下两条路径中选择**一条**——SIP 设置和 AMFI 设置是配套的,不要混用:
+**宿主机:**
-**方案 A——完全禁用 SIP,然后通过 boot-arg 禁用 AMFI(最宽松)。** 在恢复模式下(长按电源键 → 终端):
+- Apple Silicon
+- macOS 15+(Sequoia)
+- [放宽 SIP/AMFI,以允许未签名二进制使用私有 PV=3 授权](#放宽-sipamfi)
-```bash
-csrutil disable
-csrutil allow-research-guests enable
-```
-
-然后重启进入 macOS 并设置 AMFI boot-arg(需要 SIP 完全关闭才能生效):
-
-```bash
-sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # 之后重启
-```
-
-**方案 B——保持 SIP 开启(仅放宽 debug),然后用 amfidont 将二进制加入白名单**(AMFI 在系统范围内保持启用)。在恢复模式下:
+**依赖:**
```bash
-csrutil enable --without debug
-csrutil allow-research-guests enable
+brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone libusb ipsw zstd
```
-然后重启进入 macOS,用 [`amfidont`](https://github.com/zqxwce/amfidont)(或 [`amfree`](https://github.com/retX0/amfree))将仓库加入白名单:
+## 安装
```bash
-sudo amfidont --path <path_to_vphone-cli.app>
+brew install zqxwce/tap/vphone-cli
```
-> `less`(无补丁)变体需要方案 A,或者搭配 `amfidont -S` 的方案 B(`sudo amfidont -S --path <path_to_vphone-cli.app>`)。
-
-**依赖:**
+## 构建
```bash
git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
-brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone libusb ipsw zstd
-```
-
-(需要一个较新的 `python3`——3.11+;应用会基于它构建自己的 Python 环境,见 [Python 运行时](#python-运行时)。)
-
-## 构建
-
-两个一次性的引导脚本(编译后的二进制无法自行构建),之后一切都通过 `vphone-cli` 完成:
-```bash
./scripts/setup_tools.sh # 安装依赖、构建工具链子模块、创建 Python venv
./scripts/build.sh # 构建并签名 vphone-cli、打包 .app、交叉编译 vphoned
-```
-把二进制加入你的 `PATH`,这样下面的示例就能原样运行:
-
-```bash
cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help
```
@@ -107,25 +44,7 @@ vphone-cli --help
```bash
vphone-cli vm create myphone -V jb # -V / --variant
-```
-
-随后会提示你选择 iOS <-> cloudOS 配对;你也可以通过传入 **`-i`/`--iphone-source`** 和/或 **`-c`/`--cloudos-source`** 指定其中之一(或两者)。例如:
-```bash
-# 使用本地 IPSW
-vphone-cli vm create myphone -V jb \
- -i ~/ipsws/iPhone17,3_26.1_23B85_Restore.ipsw \
- -c ~/ipsws/cloudOS_26.1-23B85.ipsw
-
-# 或使用 URL——下载后缓存到 ~/.vphone/ipsws
-vphone-cli vm create myphone -V jb \
- -i "https://.../iPhone17,3_26.1_23B85_Restore.ipsw" \
- -c "https://.../399b6..."
-```
-
-然后启动它:
-
-```bash
vphone-cli vm launch myphone
```
@@ -165,19 +84,25 @@ vphone-cli vm launch myphone # 6. 首次启动
要升级到更新的 iOS,把 `fw prepare` 指向一个 IPSW:`--iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw`。
-## 运行与连接
+## 固件变体
-`vphone-cli vm launch <name>` 会打开虚拟机窗口;`vphone-cli vm stop <name>` 会将其关闭。客户机在端口 `22222` 上运行 SSH 服务器(dropbear),在 `5901` 上运行 VNC,可通过虚拟机的 NAT IP 访问(在 `bridge100` 上用 `arp -a` 查找):
+五种补丁变体,安全绕过程度递增——将其中之一传给 `--variant`:
-- **SSH(越狱):** `ssh -p 22222 mobile@<vm-ip>`(密码 `alpine`)
-- **SSH(regular/dev):** `ssh -p 22222 root@<vm-ip>`
-- **VNC:** `vnc://<vm-ip>:5901`
+| 变体 | 引导链 | CFW | 说明 |
+| --------- | ----------- | --------- | ------------------------------------------------- |
+| `less` | 4 patches | 2 phases | 无补丁——保持 iOS 缓解措施启用 |
+| `regular` | 42 patches | 10 phases | 绕过 AMFI/SSV/Img4/TXM |
+| `dev` | 53 patches | 12 phases | + 绕过 TXM 授权/调试 |
+| `jb` | 113 patches | 14 phases | + 完整越狱(首次启动时自动安装 Sileo、TrollStore)|
+| `exp` | 141 patches | 18 phases | JB 超集 + 反虚拟机检测研究补丁 |
-对于 `jb`/`exp` 变体,Sileo 和 TrollStore 会在首次启动时自动安装(可监控 `/var/log/vphone_jb_setup.log`)。
+各组件的详细拆解见 [`research/0_binary_patch_comparison.md`](../research/0_binary_patch_comparison.md)。
-## Python 运行时
+## 运行与连接
-有几个步骤(DFU 恢复、IPSW 处理)通过 Python 运行。首次使用时,vphone-cli 会基于宿主机上较新的 `python3`(3.11+)并使用捆绑的 `requirements.txt`,在 `~/.vphone/venv` 处配置一个自包含的 venv——因此签名后的 `.app` 是**可移植的**:把它复制到任何地方(例如 `/Applications`),无需仓库即可运行。配置是自动进行的;运行 `vphone-cli setup` 可提前完成配置。用 `VPHONE_PYTHON=/path/to/python3` 指定特定的解释器,或用 `VPHONE_VENV_DIR=/path` 迁移 venv。
+- **SSH(越狱):** `ssh -p 22222 mobile@<vm-ip>`(密码 `alpine`)
+- **SSH(regular/dev):** `ssh -p 22222 root@<vm-ip>`
+- **VNC:** `vnc://<vm-ip>:5901`
## 位置
@@ -191,6 +116,56 @@ vphone-cli 创建的所有内容都位于 `~/.vphone/` 下——保存在仓库
| `~/.vphone/debs/` | `jb`/`exp` CFW 安装写入客户机的 `.deb` 包缓存(Sileo、apt 等)。 |
| `~/.vphone/venv/` | 自动配置的 Python 环境(见 [Python 运行时](#python-运行时);可用 `$VPHONE_VENV_DIR` 覆盖)。 |
+## 放宽 SIP/AMFI
+
+**方案 A——完全禁用 SIP,然后通过 boot-arg 禁用 AMFI(最宽松)。**
+
+在恢复模式下(长按电源键 → 终端):
+
+```bash
+csrutil disable
+csrutil allow-research-guests enable
+```
+
+然后重启进入 macOS 并设置 AMFI boot-arg(需要 SIP 完全关闭才能生效):
+
+```bash
+sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # 之后重启
+```
+
+**方案 B——保持 SIP 开启(仅放宽 debug),然后用 amfidont 将二进制加入白名单**(AMFI 在系统范围内保持启用)。
+
+在恢复模式下:
+
+```bash
+csrutil enable --without debug
+csrutil allow-research-guests enable
+```
+
+然后重启进入 macOS 并执行:
+
+```bash
+vphone-amfidont # 本地构建见 .build/vphone-cli.app/Contents/Resources/vphone-amfidont
+```
+
+## 测试环境
+
+| 宿主机 | iPhone | CloudOS |
+| --------------- | --------------------- | --------------- |
+| Mac16,11 27.0b2 | `17,3_18.6.2_22G100` | `26.1-23B85` |
+| Mac16,8 26.5.1 | `17,3_26.0_23A341` | `26.1-23B85` |
+| Mac16,8 26.5.1 | `17,3_26.0.1_23A355` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.1_23B85` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.3-23D128` |
+| Mac16,12 26.3 | `17,3_26.3.1_23D8133` | `26.3-23D128` |
+| Mac16,11 26.2 | `17,3_26.4_23E246` | `26.4-23E5207q` |
+| Mac16,11 26.2 | `17,3_26.5_23F77` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_26.5.2_23F84` | `26.4-23E5207q` |
+| Mac16,6 25.4.1 | `17,3_26.6_23G71` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_27.0_24A5380h` | `26.4-23E5207q` |
+| Mac16,6 25.4.1 | `17,3_27.0_24A5390f` | `26.4-23E5207q` |
+
## 常见问题
**`zsh: killed ./vphone-cli`** —— AMFI/debug 限制未被绕过;见[前置条件](#前置条件)(`amfi_get_out_of_my_way=1` 或 `amfidont`)。