vphone-cli

Apple के Virtualization.framework के माध्यम से PCC रिसर्च VM इंफ्रास्ट्रक्चर का उपयोग करके एक वर्चुअल iPhone बूट करें।

पूर्वापेक्षाएँ

होस्ट:

• Apple Silicon
• macOS 15+ (Sequoia)
• Xcode + iOS SDK (गेस्ट डेमॉन को क्रॉस-कंपाइल करता है)
• अहस्ताक्षरित-बाइनरी के साथ निजी PV=3 एंटाइटलमेंट की अनुमति देने के लिए SIP/AMFI शिथिलीकरण

निर्भरताएँ:

brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd

इंस्टॉल करें

brew install zqxwce/tap/vphone-cli

बिल्ड करें

git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git

./scripts/setup_tools.sh      # निर्भरताएँ इंस्टॉल करें, टूलचेन सबमॉड्यूल बनाएं, Python venv बनाएं
./scripts/build.sh            # vphone-cli बनाएं + साइन करें, .app बंडल करें, vphoned क्रॉस-कंपाइल करें

cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help

त्वरित प्रारंभ

एक कमांड एंड-टू-एंड VM बनाता है (डाउनलोड → पैच → DFU रिस्टोर → CFW इंस्टॉल → पहला बूट):

vphone-cli vm create myphone -V jb        # -V / --variant

vphone-cli vm launch myphone

कमांड

vphone-cli vm create पूरी पाइपलाइन चलाता है; नीचे दिए गए अलग-अलग चरण आपको इसे मैन्युअल रूप से चलाने या एक चरण को फिर से चलाने की अनुमति देते हैं।

प्रबंधित करें

vphone-cli vm list                         # VMs सूचीबद्ध करें (स्क्रिप्टिंग के लिए --json)
vphone-cli vm info myphone                  # एक VM दिखाएं
vphone-cli vm new myphone                   # एक खाली बंडल बनाएं (cpu/mem/disk विकल्प)
vphone-cli vm config myphone --cpu 8 --memory 8192
vphone-cli vm clone myphone myphone-2       # तेज़ APFS क्लोन, नई डिवाइस पहचान
vphone-cli vm export myphone --out myphone.tzst   # डिफ़ॉल्ट रूप से तेज़ zstd (--max = xz -9); --out एक निर्देशिका हो सकती है (स्वतः-नाम <vm>.tzst/.txz); restore dir + staging फ़ाइलें छोड़ता है
vphone-cli vm import myphone.tzst --name restored
vphone-cli vm rename myphone iphone16
vphone-cli vm delete iphone16

मैन्युअल रूप से VM बनाएं (जो vm create स्वचालित करता है)

vphone-cli vm new myphone                              # 1. खाली बंडल
vphone-cli fw prepare myphone --iphone-version 26.1     # 2. IPSWs डाउनलोड करें + मर्ज करें
vphone-cli fw patch myphone --variant jb                # 3. बूट चेन पैच करें

vphone-cli vm launch myphone --dfu &                    # 4. DFU में बूट करें (बैकग्राउंड)
vphone-cli restore myphone --get-shsh                   #    SHSH प्राप्त करें
vphone-cli restore myphone                              #    DFU रिस्टोर
vphone-cli vm stop myphone                              #    DFU बूट रोकें

vphone-cli cfw install myphone --variant jb             # 5. CFW इंस्टॉल करें (होस्ट-माउंट; sudo मांगता है)
vphone-cli vm launch myphone                            # 6. पहला बूट

fw prepare को IPSW पर इंगित करके नए iOS में अपडेट करें: --iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw।

फर्मवेयर वेरिएंट

बढ़ती सुरक्षा बाईपास के साथ पाँच पैच वेरिएंट — --variant पर एक पास करें:

प्रति-घटक विवरण के लिए research/0_binary_patch_comparison.md देखें।

चलाना और कनेक्ट करना

• SSH (जेलब्रेक): ssh -p 22222 mobile@<vm-ip> (पासवर्ड alpine)
• SSH (regular/dev): ssh -p 22222 root@<vm-ip>
• VNC: vnc://<vm-ip>:5901

स्थान

vphone-cli जो कुछ भी बनाता है वह ~/.vphone/ के अंतर्गत रहता है — रिपॉजिटरी और .app के बाहर रखा जाता है ताकि साइन किया गया बंडल पोर्टेबल बना रहे। पूरे ट्री को $VPHONE_ROOT के साथ पुनर्निर्देशित करें:

प्राथमिकता: प्रति-आइटम ओवरराइड ($VPHONE_LIBRARY_ROOT, $VPHONE_VENV_DIR) $VPHONE_ROOT पर जीतते हैं, जो ~/.vphone डिफ़ॉल्ट पर जीतता है। ipsws/, tools/, और debs/ कैश हमेशा सीधे सक्रिय रूट के अंतर्गत रहते हैं।

SIP/AMFI शिथिलीकरण

विकल्प A — SIP को पूरी तरह से अक्षम करें, फिर बूट-आर्ग के माध्यम से AMFI को अक्षम करें (सबसे अनुमेय)।

रिकवरी में (पावर बटन लंबे समय तक दबाएं → टर्मिनल):

csrutil disable
csrutil allow-research-guests enable

फिर macOS में रीबूट करें और AMFI बूट-आर्ग सेट करें (प्रभावी होने के लिए SIP पूरी तरह से बंद होना चाहिए):

sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"   # बाद में रीबूट करें

विकल्प B — SIP चालू रखें (केवल डीबग-शिथिल), फिर amfidont के साथ बाइनरी को व्हाइटलिस्ट करें (सिस्टम-व्यापी AMFI सक्षम छोड़ता है)।

रिकवरी में:

csrutil enable --without debug
csrutil allow-research-guests enable

फिर macOS में रीबूट करें और:

vphone-amfidont         # स्थानीय बिल्ड के लिए .build/vphone-cli.app/Contents/Resources/vphone-amfidont

परीक्षण किए गए वातावरण

FAQ

zsh: killed ./vphone-cli — AMFI/डीबग प्रतिबंध बाईपास नहीं किए गए हैं; पूर्वापेक्षाएँ देखें (amfi_get_out_of_my_way=1 या amfidont)।

Virtualization is not available on this hardware — आपका Mac स्वयं एक VM है; PV=3 गेस्ट बूट नेस्ट नहीं कर सकता। गैर-नेस्टेड macOS 15+ होस्ट का उपयोग करें।

"Press home to continue" पर अटका हुआ — VNC के माध्यम से कनेक्ट करें और होम बटन का अनुकरण करने के लिए राइट-क्लिक (दो-उंगली क्लिक) करें।

सिस्टम ऐप्स इंस्टॉल नहीं होंगे — iOS सेटअप के दौरान, अपने क्षेत्र के रूप में जापान या EU न चुनें (अतिरिक्त नियामक जांच जो VM संतुष्ट नहीं कर सकता); उदाहरण के लिए संयुक्त राज्य चुनें।

EXC_GUARD / GUARD_TYPE_MACH_PORT के साथ लॉन्च पर ऐप क्रैश — vphone-cli fw patch <name> --variant <v> --force-exc-guard के साथ फिर से पैच करें, फिर फिर से रिस्टोर/इंस्टॉल करें (#291)। iOS 18 बेस के लिए हमेशा चालू।

.ipa/.tipa इंस्टॉल करें — चल रहे VM के Install मेनू का उपयोग करें (ड्रैग-ड्रॉप या फ़ाइल पिकर)।

cfw install सिस्टम बाइनरी (जैसे Campo) को फिर से साइन करते समय हैंग होता है, मेमोरी असीमित रूप से बढ़ती है — ldid-procursus में 2.1.5-procursus7 (वर्तमान Homebrew stable) तक ज्ञात बग: bytes(uint64_t) बिना ज़ीरो-गार्ड के __builtin_clzll(0) कॉल करता है, जो अपरिभाषित व्यवहार है, और इस बिल्ड पर एक 0-लंबाई में हल होता है जो एक अहस्ताक्षरित लूप काउंटर को अंडरफ्लो करता है — ldid समाप्त होने के बजाय एक बढ़ते बफर में एक बार में एक बाइट लिखते हुए घूमता है। किसी भी एंटाइटलमेंट plist द्वारा ट्रिगर किया जाता है जिसमें बिल्कुल 0 का पूर्णांक मान होता है (कुछ वास्तविक Apple सिस्टम बाइनरी में ये होते हैं)। अपस्ट्रीम में ठीक किया गया लेकिन अभी तक टैग किए गए रिलीज़ में नहीं; स्रोत से फिर से बनाएं: brew install --HEAD ldid-procursus && brew link --overwrite ldid-procursus। यदि आप पहले ही इसका सामना कर चुके हैं तो पहले हैंग किए गए ldid प्रक्रिया को मारें ()।

स्वचालन

vphone-cli प्रोग्रामेटिक नियंत्रण के लिए एक होस्ट कंट्रोल सॉकेट (<bundle>/vphone.sock) प्रदर्शित करता है — स्क्रीनशॉट, टच, स्वाइप, हार्डवेयर कुंजियाँ, क्लिपबोर्ड — प्रत्येक क्रिया AI-संचालित E2E परीक्षण के लिए एक इनलाइन स्क्रीनशॉट लौटाती है। इसे लपेटने वाले MCP सर्वर के लिए vphone-mcp देखें।

आभार

• wh1te4ever/super-tart-vphone-writeup