[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-6806":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":8,"htmlUrl":8,"language":9,"languages":8,"totalLinesOfCode":8,"stars":10,"forks":11,"watchers":12,"openIssues":13,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":14,"forks30d":14,"starsTrendScore":18,"compositeScore":19,"rankGlobal":8,"rankLanguage":8,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":8,"pushedAt":8,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":14,"starSnapshotCount":14,"syncStatus":28,"lastSyncTime":29,"discoverSource":30},6806,"vphone-cli","Lakr233\u002Fvphone-cli","Lakr233",null,"Swift",6798,1011,44,16,0,22,96,811,88,40.02,"MIT License",false,"main",true,[],"2026-06-12 02:01:30","\u003Cdiv align=\"right\">\u003Cstrong>\u003Ca href=\".\u002Fdocs\u002FREADME_ko.md\">🇰🇷한국어\u003C\u002Fa>\u003C\u002Fstrong> | \u003Cstrong>\u003Ca href=\".\u002Fdocs\u002FREADME_ja.md\">🇯🇵日本語\u003C\u002Fa>\u003C\u002Fstrong> | \u003Cstrong>\u003Ca href=\".\u002Fdocs\u002FREADME_zh.md\">🇨🇳中文\u003C\u002Fa>\u003C\u002Fstrong> | \u003Cstrong>🇬🇧English\u003C\u002Fstrong>\u003C\u002Fdiv>\n\n# vphone-cli\n\nBoot a virtual iPhone (iOS 26) via Apple's Virtualization.framework using PCC research VM infrastructure.\n\n![poc](.\u002Fdocs\u002Fdemo.jpeg)\n\n## Tested Environments\n\n| Host          | iPhone                | CloudOS       |\n| ------------- | --------------------- | ------------- |\n| Mac16,12 26.3 | `17,3_26.1_23B85`     | `26.1-23B85`  |\n| Mac16,12 26.3 | `17,3_26.3_23D127`    | `26.1-23B85`  |\n| Mac16,12 26.3 | `17,3_26.3_23D127`    | `26.3-23D128` |\n| Mac16,12 26.3 | `17,3_26.3.1_23D8133` | `26.3-23D128` |\n\n## Firmware Variants\n\nFour patch variants are available with increasing levels of security bypass:\n\n| Variant         | Boot Chain  |    CFW    | Make Targets                        |\n| --------------- | :---------: | :-------: | ----------------------------------- |\n| **Patchless**   | 3 patches   | 2 phases  | `fw_patch_less` + `boot_less`       |\n| **Regular**     | 41 patches  | 10 phases | `fw_patch` + `cfw_install`          |\n| **Development** | 52 patches  | 12 phases | `fw_patch_dev` + `cfw_install_dev`  |\n| **Jailbreak**   | 112 patches | 14 phases | `fw_patch_jb` + `cfw_install_jb`    |\n\n> JB finalization (symlinks, Sileo, apt, TrollStore) runs automatically on first boot via `\u002Fcores\u002Fvphone_jb_setup.sh` LaunchDaemon. Monitor progress: `\u002Fvar\u002Flog\u002Fvphone_jb_setup.log`.\n\nSee [research\u002F0_binary_patch_comparison.md](.\u002Fresearch\u002F0_binary_patch_comparison.md) for the detailed per-component breakdown.\n\n## Prerequisites\n\n**Host OS:** macOS 15+ (Sequoia) is required for PV=3 virtualization.\n\n**Configure SIP\u002FAMFI** — required for private Virtualization.framework entitlements and unsigned binary workflows.\n\nBoot into Recovery (long press power button), open Terminal, then choose one setup path:\n\n- **Option 1: Fully disable SIP + AMFI boot-arg (most permissive)**\n\n  In Recovery:\n\n  ```bash\n  csrutil disable\n  csrutil allow-research-guests enable\n  ```\n\n  After restarting into macOS:\n\n  ```bash\n  sudo nvram boot-args=\"amfi_get_out_of_my_way=1 -v\"\n  ```\n\n  Restart once more.\n\n- **Option 2: Keep SIP mostly enabled, disable only debug restrictions, use [`amfidont`](https:\u002F\u002Fgithub.com\u002Fzqxwce\u002Famfidont) or [`amfree`](https:\u002F\u002Fgithub.com\u002FretX0\u002Famfree)**\n\n  In Recovery:\n\n  ```bash\n  csrutil enable --without debug\n  csrutil allow-research-guests enable\n  ```\n\n  After restarting into macOS:\n\n  ```bash\n  # Using amfidont:\n  xcrun python3 -m pip install amfidont\n  sudo amfidont --path [PATH_TO_VPHONE_DIR]\n  \n  # OR Using amfree:\n  brew install retX0\u002Ftap\u002Famfree\n  sudo amfree --path [PATH_TO_VPHONE_DIR]\n  ```\n\n  Repo helper (for amfidont):\n\n  ```bash\n  make amfidont_allow_vphone\n  ```\n\n  This helper computes the current signed `vphone-cli` CDHash and uses the\n  URL-encoded project path form observed by `AMFIPathValidator`.\n\n> The Patchless variant requires either the use of option 1 or amfidont with the `-S` flag (`sudo amfidont -S --path [PATH_TO_VPHONE_DIR]`)\n\n**Install dependencies:**\n\n*You will need both brew dependencies and Git Submodule dependencies.*\n\n1. Brew dependencies:\n\n```bash\nbrew install aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone libusb ipsw\n```\n\n`scripts\u002Ffw_prepare.sh` prefers `aria2c` for faster multi-connection downloads and falls back to `curl` or `wget` when needed.\n\n2. Git Submodules\n\n**Submodules** — this repo uses git submodules for resources, vendored Swift deps, and toolchain sources under `scripts\u002Frepos\u002F`. Clone with:\n\n```bash\ngit clone --recurse-submodules https:\u002F\u002Fgithub.com\u002FLakr233\u002Fvphone-cli.git\n```\n\n## Quick Start\n\n```bash\nmake setup_machine            # full automation through \"First Boot\" (includes restore\u002Framdisk\u002FCFW)\n# options: NONE_INTERACTIVE=1 SUDO_PASSWORD=...\n# LESS=1 for patchless variant (- AMFI, SSV, Img4, TXM bypasses) \n# DEV=1 for dev variant (+ TXM entitlement\u002Fdebug bypasses)\n# JB=1 for jailbreak variant (+ full security bypass)\n```\n\n## Manual Setup\n\n```bash\nmake setup_tools              # install brew deps, build trustcache + insert_dylib, create Python venv (pymobiledevice3, aria2c included)\nmake build                    # build + sign vphone-cli\nmake vm_new                   # create VM directory with manifest (config.plist)\n# options: CPU=8 MEMORY=8192 DISK_SIZE=64\nmake fw_prepare               # download IPSWs, extract, merge, generate manifest\nmake fw_patch                 # patch boot chain (regular variant)\n# or: sudo make fw_patch_less # patchless variant (- AMFI, SSV, Img4, TXM bypasses)\n# or: make fw_patch_dev       # dev variant (+ TXM entitlement\u002Fdebug bypasses)\n# or: make fw_patch_jb        # jailbreak variant (+ full security bypass)\n```\n\n### VM Configuration\n\nStarting from v1.0, VM configuration is stored in `vm\u002Fconfig.plist`. Set CPU, memory, and disk size during VM creation:\n\n```bash\n# Create VM with custom configuration\nmake vm_new CPU=16 MEMORY=16384 DISK_SIZE=128\n\n# Boot automatically reads from config.plist\nmake boot\n```\n\nThe manifest stores all VM settings (CPU, memory, screen, ROMs, storage) and is compatible with [security-pcc's VMBundle.Config format](https:\u002F\u002Fgithub.com\u002Fapple\u002Fsecurity-pcc).\n\n## Restore\n\nYou'll need **two terminals** for the restore process. Keep terminal 1 running while using terminal 2.\n\n```bash\n# terminal 1\nmake boot_dfu                 # boot VM in DFU mode (keep running)\n```\n\n```bash\n# terminal 2\nmake restore_get_shsh         # fetch SHSH blob\nmake restore                  # flash firmware via pymobiledevice3 restore backend\n# or: make restore_offline    # offline restore (decrypts AEA images in place, uses cached .shsh blob)\n                              # for the first time should be ran with internet access for AEA decryption\n```\n\n## Install Custom Firmware\n\nStop the DFU boot in terminal 1 (Ctrl+C), then boot into DFU again for the ramdisk:\n\n```bash\n# terminal 1\nmake boot_dfu                 # keep running\n```\n\n```bash\n# terminal 2\nsudo make ramdisk_build       # build signed SSH ramdisk\nmake ramdisk_send             # send to device\n```\n\nOnce the ramdisk is running (you should see `Running server` in the output), open a **third terminal** for the usbmux tunnel, then install CFW from terminal 2:\n\n```bash\n# terminal 3 — keep running\npython3 -m pymobiledevice3 usbmux forward 2222 22\n```\n\n```bash\n# terminal 2\nmake cfw_install\n# or: make cfw_install_jb        # jailbreak variant\n```\n\n## First Boot\n\nStop the DFU boot in terminal 1 (Ctrl+C), then:\n\n```bash\nmake boot\n```\n\nAfter `cfw_install_jb`, the jailbreak variant will have **Sileo** and **TrollStore** available on first boot. You can use Sileo to install `openssh-server` for SSH access.\n\nFor the regular\u002Fdevelopment variant, the VM gives you a **direct console**. When you see `bash-4.4#`, press Enter and run these commands to initialize the shell environment and generate SSH host keys:\n\n```bash\nexport PATH='\u002Fusr\u002Flocal\u002Fsbin:\u002Fusr\u002Flocal\u002Fbin:\u002Fusr\u002Fsbin:\u002Fusr\u002Fbin:\u002Fsbin:\u002Fbin:\u002Fusr\u002Fbin\u002FX11:\u002Fusr\u002Fgames:\u002Fiosbinpack64\u002Fusr\u002Flocal\u002Fsbin:\u002Fiosbinpack64\u002Fusr\u002Flocal\u002Fbin:\u002Fiosbinpack64\u002Fusr\u002Fsbin:\u002Fiosbinpack64\u002Fusr\u002Fbin:\u002Fiosbinpack64\u002Fsbin:\u002Fiosbinpack64\u002Fbin'\n\nmkdir -p \u002Fvar\u002Fdropbear\ncp \u002Fiosbinpack64\u002Fetc\u002Fprofile \u002Fvar\u002Fprofile\ncp \u002Fiosbinpack64\u002Fetc\u002Fmotd \u002Fvar\u002Fmotd\n\n# generate SSH host keys (required for SSH to work)\ndropbearkey -t rsa -f \u002Fvar\u002Fdropbear\u002Fdropbear_rsa_host_key\ndropbearkey -t ecdsa -f \u002Fvar\u002Fdropbear\u002Fdropbear_ecdsa_host_key\n\nshutdown -h now\n```\n\n> **Note:** Without the host key generation step, dropbear (SSH server) will accept connections but immediately close them because it has no keys to perform the SSH handshake.\n\n## Subsequent Boots\n\n```bash\nmake boot\n```\n\nIn a separate terminal, start usbmux forward tunnels:\n\n```bash\npython3 -m pymobiledevice3 usbmux forward 2222 22222    # SSH (dropbear)\npython3 -m pymobiledevice3 usbmux forward 2222 22       # SSH (JB: if you install openssh-server from Sileo)\npython3 -m pymobiledevice3 usbmux forward 5901 5901     # VNC\npython3 -m pymobiledevice3 usbmux forward 5910 5910     # RPC\n```\n\nConnect via:\n\n- **SSH (JB):** `ssh -p 2222 mobile@127.0.0.1` (password: `alpine`)\n- **SSH (Regular\u002FDev):** `ssh -p 2222 root@127.0.0.1` (password: `alpine`)\n- **VNC:** `vnc:\u002F\u002F127.0.0.1:5901`\n- [**RPC:**](http:\u002F\u002Fgithub.com\u002Fdoronz88\u002Frpc-project) `rpcclient -p 5910 127.0.0.1`\n\n## VM Backup & Switch\n\nSave and switch between multiple VM environments (e.g. different iOS builds or firmware variants). Backups are stored in `vm.backups\u002F` using `rsync --sparse` for efficient sparse disk handling.\n\n```bash\nmake vm_backup NAME=26.1-clean    # save current VM\nrm -rf vm && make vm_new          # start fresh for a different build\n# ... fw_prepare, fw_patch, restore, cfw_install, boot\nmake vm_backup NAME=26.3-jb       # save the new one too\nmake vm_list                      # list all saved backups\nmake vm_switch NAME=26.1-clean    # swap between them\n```\n\n> **Note:** Always stop the VM before backup\u002Fswitch\u002Frestore.\n\n## FAQ\n\n> **Before anything else — run `git pull` to make sure you have the latest version.**\n\n**Q: I get `zsh: killed .\u002Fvphone-cli` when trying to run it.**\n\nAMFI\u002Fdebug restrictions are not bypassed correctly. Choose one setup path:\n\n- **Option 1 (full AMFI disable):**\n\n  ```bash\n  sudo nvram boot-args=\"amfi_get_out_of_my_way=1 -v\"\n  ```\n\n- **Option 2 (debug restrictions only):**\n  use Recovery mode `csrutil enable --without debug` (no full SIP disable), then install\u002Fload [`amfidont`](https:\u002F\u002Fgithub.com\u002Fzqxwce\u002Famfidont) or [`amfree`](https:\u002F\u002Fgithub.com\u002FretX0\u002Famfree) while keeping AMFI otherwise enabled.\n  For this repo, `make amfidont_allow_vphone` packages the required encoded-path\n  and CDHash allowlist startup (if using amfidont).\n\n**Q: `make boot` \u002F `make boot_dfu` starts and then fails with `VZErrorDomain Code=2 \"Virtualization is not available on this hardware.\"`**\n\nThe host itself is running inside an Apple virtual machine, so nested\nVirtualization.framework guest boot is unavailable. Run the boot flow on a\nnon-nested macOS 15+ host instead. `make boot_host_preflight` will show this as\n`Model Name: Apple Virtual Machine 1` with `kern.hv_vmm_present=1`.\n`make boot` \u002F `make boot_dfu` now fail fast through `boot_binary_check` before\nattempting VM startup on that kind of host.\n\n**Q: System apps (App Store, Messages, etc.) won't download or install.**\n\nDuring iOS setup, do **not** select **Japan** or **European Union** as your region. These regions enforce additional regulatory checks (e.g., sideloading disclosures, camera shutter requirements) that the virtual machine cannot satisfy, which prevents system apps from being downloaded and installed. Choose any other region (e.g., United States) to avoid this issue.\n\n**Q: I'm stuck on the \"Press home to continue\" screen.**\n\nConnect via VNC (`vnc:\u002F\u002F127.0.0.1:5901`) and right-click anywhere on the screen (two-finger click on a Mac trackpad). This simulates the home button press.\n\n**Q: How do I get SSH access?**\n\nInstall `openssh-server` from Sileo (available on the jailbreak variant after first boot).\n\n**Q: SSH doesn't work after installing openssh-server.**\n\nReboot the VM. The SSH server will start automatically on the next boot.\n\n**Q: Can I install `.tipa` files?**\n\nYes. The install menu supports both `.ipa` and `.tipa` packages. Drag and drop or use the file picker.\n\n**Q: Can I update to a newer iOS version?**\n\nYes. Override `fw_prepare` with the IPSW URL for the version you want:\n\n```bash\nexport IPHONE_SOURCE=\u002Fpath\u002Fto\u002Fsome_os.ipsw\nexport CLOUDOS_SOURCE=\u002Fpath\u002Fto\u002Fsome_os.ipsw\nmake fw_prepare\nmake fw_patch\n```\n\nOur patches are applied via binary analysis, not static offsets, so newer versions should work. If something breaks, ask AI for help.\n\n**Q: I used `restore_offline` and I am stuck in the setup screen**\n\nThe device is trying to contact apple for the setup, and you are probably not connected to the internet if you used `restore_offline`.\nYou can bypass most of the setup screen by making the device supervised:\n\n```bash\npython3 -m pymobiledevice3 profile supervise vphone\n```\n\n## Automation\n\nvphone-cli exposes a host control socket (`vm\u002Fvphone.sock`) for programmatic VM interaction — screenshots, touch injection, swipe gestures, hardware keys, and clipboard. Every action returns a compact grayscale screenshot inline, enabling AI-driven E2E testing workflows.\n\nSee [vphone-mcp](https:\u002F\u002Fgithub.com\u002Fpluginslab\u002Fvphone-mcp) for an MCP server that wraps this socket with high-level tools (open apps by name, navigate back, scroll, type text) usable from Claude Code or Claude Desktop.\n\n## Acknowledgements\n\n- [wh1te4ever\u002Fsuper-tart-vphone-writeup](https:\u002F\u002Fgithub.com\u002Fwh1te4ever\u002Fsuper-tart-vphone-writeup)\n","vphone-cli 是一个通过 Apple 的 Virtualization.framework 在 macOS 上启动虚拟 iPhone（iOS 26）的命令行工具。其核心功能包括利用 PCC 研究 VM 基础设施来创建和运行虚拟设备，并提供了四种固件变体，每种变体具有不同级别的安全绕过能力，从无补丁到越狱版不等。该工具特别适合开发者在不需要实际物理设备的情况下测试 iOS 应用或进行系统级研究。需要注意的是，使用此工具前必须对主机操作系统进行一些配置，比如禁用 SIP 和 AMFI 以允许加载未签名的二进制文件。",2,"2026-06-11 03:08:58","top_language"]