Overzicht van vphone-cli
vphone-cli is een tool waarmee gebruikers een virtuele iPhone kunnen draaien op Apple Silicon-hosts met macOS 15 (Sequoia) of nieuwer. De tool maakt gebruik van Apple's Virtualization.framework en de VM-infrastructuur van PCC research.
Belangrijkste kenmerken:
- Automatisering: Met het commando
vm create kan de volledige pipeline (downloaden, patchen, DFU-herstel en booten) in één keer worden uitgevoerd.
- Firmware-varianten: Er zijn vijf verschillende varianten beschikbaar, variërend van minimale patches (
less) tot volledige jailbreaks (jb) en research-patches voor anti-VM-detectie (exp).
- Beheer: De tool biedt uitgebreide opties voor het beheren van VM's, waaronder klonen, exporteren, importeren en configuratie-aanpassingen (CPU/RAM).
- Connectiviteit: Interactie met de virtuele iPhone is mogelijk via SSH (voor terminaltoegang) en VNC (voor visuele bediening).
- Automatisering & AI: Via een host-control socket kunnen acties zoals touch, swipes en screenshots programmatisch worden aangestuurd, wat handig is voor E2E-tests.
Technische vereisten en installatie:
De software vereist specifieke systeeminstellingen, waaronder het versoepelen van SIP (System Integrity Protection) en AMFI om onondertekende binaries toe te staan. Installatie kan via Homebrew of handmatig via GitHub.
vphone-cli
Voorwaarden
Host-systeem
- Hardware: Apple Silicon
- Besturingssysteem: macOS 15+ (Sequoia)
- Software: Xcode + iOS SDK (voor het cross-compileren van de guest-daemon)
- Systeeminstellingen: SIP/AMFI-ontspanning om private PV=3-entitlements met onondertekende binaries toe te staan.
Afhankelijkheden
Installeer de volgende pakketten via Homebrew: brew install python@3.13 aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd
Installatie
Via Homebrew
brew install zqxwce/tap/vphone-cli
Handmatig builden
- Clone de repository:
git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
- Installeer afhankelijkheden, build de toolchain-submodules en maak de Python venv aan:
./scripts/setup_tools.sh
- Build en onderteken vphone-cli, bundel de .app en cross-compile vphoned:
./scripts/build.sh
- Navigeer naar de binary en bekijk de help:
cd .build/vphone-cli.app/Contents/MacOS/ vphone-cli --help
Snelstart
Met één commando kan een VM end-to-end worden gemaakt (downloaden → patchen → DFU-herstel → CFW-installatie → eerste boot):
vphone-cli vm create myphone -V jb (waarbij -V of --variant de variant bepaalt) vphone-cli vm launch myphone
Opdrachten
Hoewel vphone-cli vm create de volledige pipeline automatiseert, kunnen de onderstaande stappen handmatig worden uitgevoerd of opnieuw worden gedraaid.
Beheer
- VM's weergeven:
vphone-cli vm list (gebruik --json voor scripting)
- Informatie over één VM tonen:
vphone-cli vm info myphone
- Lege bundle maken:
vphone-cli vm new myphone (opties voor cpu/mem/disk)
- Configuratie aanpassen:
vphone-cli vm config myphone --cpu 8 --memory 8192
- VM klonen:
vphone-cli vm clone myphone myphone-2 (snelle APFS-kloon, nieuwe device-identiteit)
- VM exporteren:
vphone-cli vm export myphone --out myphone.tzst (standaard zstd; --max gebruikt xz -9; --out kan een map zijn; slaat restore-dir en staging-bestanden over)
- VM importeren:
vphone-cli vm import myphone.tzst --name restored
- VM hernoemen:
vphone-cli vm rename myphone iphone16
- VM verwijderen:
vphone-cli vm delete iphone16
Handmatig een VM bouwen
- Lege bundle maken:
vphone-cli vm new myphone
- IPSW's downloaden en mergen:
vphone-cli fw prepare myphone --iphone-version 26.1
- Boot-chain patchen:
vphone-cli fw patch myphone --variant jb
- Booten in DFU (op de achtergrond):
vphone-cli vm launch myphone --dfu &
- SHSH ophalen:
vphone-cli restore myphone --get-shsh
- DFU-herstel:
vphone-cli restore myphone
- DFU-boot stoppen:
vphone-cli vm stop myphone
- CFW installeren (host-mount; vereist sudo):
vphone-cli cfw install myphone --variant jb
- Eerste boot:
vphone-cli vm launch myphone
Om te updaten naar een nieuwere iOS, wijs fw prepare naar een IPSW via --iphone-source /pad/naar.ipsw --cloudos-source /pad/naar.ipsw.
Firmware-varianten
Er zijn vijf patch-varianten beschikbaar met toenemende security-bypass. Gebruik --variant om een keuze te maken:
| Variant | Boot Chain | CFW | Notities |
|---|
| less | 4 patches | 2 fases | Patchless — houdt iOS mitigaties ingeschakeld |
| regular | 42 patches | 10 fases | AMFI/SSV/Img4/TXM bypass |
| dev | 53 patches | 12 fases | + TXM entitlement/debug bypass |
| jb | 113 patches | 14 fases | + volledige jailbreak (Sileo, TrollStore auto-install bij eerste boot) |
| exp | 141 patches | 18 fases | JB superset + anti-VM-detectie research patches |
Zie research/0binarypatch_comparison.md voor een gedetailleerde uitsplitsing per component.
Uitvoeren en Verbinding maken
- SSH (jailbreak):
ssh -p 22222 mobile@<vm-ip> (wachtwoord: alpine)
- SSH (regular/dev):
ssh -p 22222 root@<vm-ip>
- VNC:
vnc://<vm-ip>:5901
Bestandslocaties
Alle bestanden die vphone-cli aanmaakt, bevinden zich onder ~/.vphone/. Dit is buiten de repo en de .app-bundel geplaatst zodat de signed bundle draagbaar blijft. De gehele boom kan worden omgeleid met $VPHONE_ROOT.
| Pad | Inhoud |
|---|
~/.vphone/ | De root voor gebruikersdata — override met $VPHONE_ROOT. |
~/.vphone/VMs/ | VM bundles — één map per VM. Override met $VPHONELIBRARYROOT. |
~/.vphone/ipsws/ | Gedownloade iPhone + cloudOS IPSW's, gecachet voor hergebruik. |
~/.vphone/tools/ | Gecachte APFS seal-volume artifacts (apfssealvolume<versie>) opgehaald tijdens fw prepare. |
~/.vphone/debs/ | Gecachte .deb pakketten die de jb/exp CFW installatie in de guest plaatst (Sileo, apt, etc.). |
~/.vphone/venv/ | Automatisch geprovisioneerde Python-omgeving. Override met $VPHONEVENVDIR. |
Prioriteit: Specifieke overrides ($VPHONELIBRARYROOT, $VPHONEVENVDIR) gaan voor $VPHONE_ROOT, wat weer gaat voor de standaard ~/.vphone. De caches ipsws/, tools/ en debs/ bevinden zich altijd direct onder de actieve root.
SIP/AMFI-ontspanning (Relaxation)
Optie A — Volledige uitschakeling
Schakel SIP volledig uit en daarna AMFI via een boot-arg (meest permissief).
- In Recovery (lang indrukken power → Terminal):
csrutil disable csrutil allow-research-guests enable
- Herstart macOS en stel de AMFI boot-arg in (vereist volledig uitgeschakelde SIP):
sudo nvram boot-args="amfigetoutofmy_way=1 -v"
- Herstart het systeem.
Optie B — Gedeeltelijke ontspanning
Houd SIP aan (debug-only relaxed) en voeg de binary toe aan de allowlist met amfidont (houdt AMFI systeembreed ingeschakeld).
- In Recovery:
csrutil enable --without debug csrutil allow-research-guests enable
- Herstart macOS en voer uit:
vphone-amfidont (voor lokale builds: .build/vphone-cli.app/Contents/Resources/vphone-amfidont)
Geteste Omgevingen
| Host | iPhone | CloudOS |
|---|
| Mac16,11 27.0b2 | 17,318.6.222G100 | 26.1-23B85 |
| Mac16,8 26.5.1 | 17,326.023A341 | 26.1-23B85 |
| Mac16,8 26.5.1 | 17,326.0.123A355 | 26.1-23B85 |
| Mac16,12 26.3 | 17,326.123B85 | 26.1-23B85 |
| Mac16,12 26.3 | 17,326.323D127 | 26.1-23B85 |
| Mac16,12 26.3 | 17,326.323D127 | 26.3-23D128 |
| Mac16,12 26.3 | 17,326.3.123D8133 | 26.3-23D128 |
| Mac16,11 26.2 | 17,326.423E246 | 26.4-23E5207q |
| Mac16,11 26.2 | 17,326.523F77 | 26.4-23E5207q |
| Mac16,11 27.0b2 | 17,326.5.223F84 | 26.4-23E5207q |
| Mac16,6 26.4.1 | 17,326.623G71 | 26.4-23E5207q |
| Mac16,11 27.0b2 | 17,326.6.123G83 | 26.4-23E5207q |
| Mac16,11 27.0b2 | 17,327.024A5380h | 26.4-23E5207q |
| Mac16,6 26.4.1 | 17,327.024A5390f | 26.4-23E5207q |
| Mac16,6 26.6.1 | 17,327.024A5408d | 26.4-23E5207q |
| Mac16,11 27.0b2 | 17,327.024A5418b | 26.4-23E5207q |
| Mac16,11 27.0b2 | 17,327.024A5424a | 26.4-23E5207q |
Veelgestelde Vragen (FAQ)
zsh: killed ./vphone-cli — De AMFI/debug restricties zijn niet omzeild. Raadpleeg de sectie Voorwaarden (amfigetoutofmy_way=1 of amfidont).Virtualization is not available on this hardware — Je Mac is zelf een VM; PV=3 guest boot kan niet genest worden. Gebruik een niet-geneste macOS 15+ host.- Blijft hangen op "Press home to continue" — Maak verbinding via VNC en klik met de rechtermuisknop (klik met twee vingers) om de home-knop te simuleren.
- Systeem-apps worden niet geïnstalleerd — Kies tijdens de iOS-setup niet voor Japan of de EU als regio (vanwege extra regulatoire controles die de VM niet kan doorlopen); kies bijvoorbeeld de Verenigde Staten.
- App crasht bij opstarten met
EXCGUARD / GUARDTYPEMACHPORT — Patch opnieuw met vphone-cli fw patch <name> --variant <v> --force-exc-guard en voer vervolgens opnieuw de restore/installatie uit (#291). Dit staat standaard aan voor iOS 18 bases.
- Een .ipa/.tipa installeren — Gebruik het Install-menu van de draaiende VM (sleep-and-drop of bestandsselectie).
cfw install blijft hangen bij het opnieuw ondertekenen van een systeem-binary (bijv. Campo), geheugenverbruik stijgt onbeperkt — Bekende bug in ldid-procursus tot versie 2.1.5-procursus7 (de huidige Homebrew stable). De functie bytes(uint64_t) roept __builtin_clzll(0) aan zonder zero-guard, wat undefined behavior is. Dit resulteert in een loop die oneindig bytes naar een buffer schrijft. Dit wordt getriggerd door elke entitlements plist die een integerwaarde van precies 0 bevat. Opgelost in upstream, maar nog niet in een tagged release; build handmatig vanuit source: brew install --HEAD ldid-procursus && brew link --overwrite ldid-procursus. Beëindig eerst het hangende ldid-proces (sudo kill -9 <pid>).
Automatisering
vphone-cli biedt een host-control socket (<bundle>/vphone.sock) voor programmatische besturing — screenshots, touch, swipes, hardware-toetsen, klembord. Elke actie retourneert een inline screenshot voor AI-gestuurde E2E-tests. Zie vphone-mcp voor een MCP-server die dit wrapt.
Erkenningen
wh1te4ever/super-tart-vphone-writeup
vphone-cli
Voorwaarden
Host-systeem
- Hardware: Apple Silicon
- Besturingssysteem: macOS 15+ (Sequoia)
- Software: Xcode + iOS SDK (voor het cross-compileren van de guest-daemon)
- Systeeminstellingen: SIP/AMFI-ontspanning om private PV=3-entitlements met onondertekende binaries toe te staan.
Afhankelijkheden
Installeer de volgende pakketten via Homebrew: brew install python@3.13 aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd
Installatie
Via Homebrew
brew install zqxwce/tap/vphone-cli
Handmatig builden
- Clone de repository:
git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
- Installeer afhankelijkheden, build de toolchain-submodules en maak de Python venv aan:
./scripts/setup_tools.sh
- Build en onderteken vphone-cli, bundel de .app en cross-compile vphoned:
./scripts/build.sh
- Navigeer naar de binary en bekijk de help:
cd .build/vphone-cli.app/Contents/MacOS/ vphone-cli --help
Snelstart
Met één commando kan een VM end-to-end worden gemaakt (downloaden → patchen → DFU-herstel → CFW-installatie → eerste boot):
vphone-cli vm create myphone -V jb (waarbij -V of --variant de variant bepaalt) vphone-cli vm launch myphone
Opdrachten
Hoewel vphone-cli vm create de volledige pipeline automatiseert, kunnen de onderstaande stappen handmatig worden uitgevoerd of opnieuw worden gedraaid.
Beheer
- VM's weergeven:
vphone-cli vm list (gebruik --json voor scripting)
- Informatie over één VM tonen:
vphone-cli vm info myphone
- Lege bundle maken:
vphone-cli vm new myphone (opties voor cpu/mem/disk)
- Configuratie aanpassen:
vphone-cli vm config myphone --cpu 8 --memory 8192
- VM klonen:
vphone-cli vm clone myphone myphone-2 (snelle APFS-kloon, nieuwe device-identiteit)
- VM exporteren:
vphone-cli vm export myphone --out myphone.tzst (standaard zstd; --max gebruikt xz -9; --out kan een map zijn; slaat restore-dir en staging-bestanden over)
- VM importeren:
vphone-cli vm import myphone.tzst --name restored
- VM hernoemen:
vphone-cli vm rename myphone iphone16
- VM verwijderen:
vphone-cli vm delete iphone16
Handmatig een VM bouwen
- Lege bundle maken:
vphone-cli vm new myphone
- IPSW's downloaden en mergen:
vphone-cli fw prepare myphone --iphone-version 26.1
- Boot-chain patchen:
vphone-cli fw patch myphone --variant jb
- Booten in DFU (op de achtergrond):
vphone-cli vm launch myphone --dfu &
- SHSH ophalen:
vphone-cli restore myphone --get-shsh
- DFU-herstel:
vphone-cli restore myphone
- DFU-boot stoppen:
vphone-cli vm stop myphone
- CFW installeren (host-mount; vereist sudo):
vphone-cli cfw install myphone --variant jb
- Eerste boot:
vphone-cli vm launch myphone
Om te updaten naar een nieuwere iOS, wijs fw prepare naar een IPSW via --iphone-source /pad/naar.ipsw --cloudos-source /pad/naar.ipsw.
Firmware-varianten
Er zijn vijf patch-varianten beschikbaar met toenemende security-bypass. Gebruik --variant om een keuze te maken:
| Variant | Boot Chain | CFW | Notities |
|---|
| less | 4 patches | 2 fases | Patchless — houdt iOS mitigaties ingeschakeld |
| regular | 42 patches | 10 fases | AMFI/SSV/Img4/TXM bypass |
| dev | 53 patches | 12 fases | + TXM entitlement/debug bypass |
| jb | 113 patches | 14 fases | + volledige jailbreak (Sileo, TrollStore auto-install bij eerste boot) |
| exp | 141 patches | 18 fases | JB superset + anti-VM-detectie research patches |
Zie research/0binarypatch_comparison.md voor een gedetailleerde uitsplitsing per component.
Uitvoeren en Verbinding maken
- SSH (jailbreak):
ssh -p 22222 mobile@<vm-ip> (wachtwoord: alpine)
- SSH (regular/dev):
ssh -p 22222 root@<vm-ip>
- VNC:
vnc://<vm-ip>:5901
Bestandslocaties
Alle bestanden die vphone-cli aanmaakt, bevinden zich onder ~/.vphone/. Dit is buiten de repo en de .app-bundel geplaatst zodat de signed bundle draagbaar blijft. De gehele boom kan worden omgeleid met $VPHONE_ROOT.
| Pad | Inhoud |
|---|
~/.vphone/ | De root voor gebruikersdata — override met $VPHONE_ROOT. |
~/.vphone/VMs/ | VM bundles — één map per VM. Override met $VPHONELIBRARYROOT. |
~/.vphone/ipsws/ | Gedownloade iPhone + cloudOS IPSW's, gecachet voor hergebruik. |
~/.vphone/tools/ | Gecachte APFS seal-volume artifacts (apfssealvolume<versie>) opgehaald tijdens fw prepare. |
~/.vphone/debs/ | Gecachte .deb pakketten die de jb/exp CFW installatie in de guest plaatst (Sileo, apt, etc.). |
~/.vphone/venv/ | Automatisch geprovisioneerde Python-omgeving. Override met $VPHONEVENVDIR. |
Prioriteit: Specifieke overrides ($VPHONELIBRARYROOT, $VPHONEVENVDIR) gaan voor $VPHONE_ROOT, wat weer gaat voor de standaard ~/.vphone. De caches ipsws/, tools/ en debs/ bevinden zich altijd direct onder de actieve root.
SIP/AMFI-ontspanning (Relaxation)
Optie A — Volledige uitschakeling
Schakel SIP volledig uit en daarna AMFI via een boot-arg (meest permissief).
- In Recovery (lang indrukken power → Terminal):
csrutil disable csrutil allow-research-guests enable
- Herstart macOS en stel de AMFI boot-arg in (vereist volledig uitgeschakelde SIP):
sudo nvram boot-args="amfigetoutofmy_way=1 -v"
- Herstart het systeem.
Optie B — Gedeeltelijke ontspanning
Houd SIP aan (debug-only relaxed) en voeg de binary toe aan de allowlist met amfidont (houdt AMFI systeembreed ingeschakeld).
- In Recovery:
csrutil enable --without debug csrutil allow-research-guests enable
- Herstart macOS en voer uit:
vphone-amfidont (voor lokale builds: .build/vphone-cli.app/Contents/Resources/vphone-amfidont)
Geteste Omgevingen
| Host | iPhone | CloudOS |
|---|
| Mac16,11 27.0b2 | 17,318.6.222G100 | 26.1-23B85 |
| Mac16,8 26.5.1 | 17,326.023A341 | 26.1-23B85 |
| Mac16,8 26.5.1 | 17,326.0.123A355 | 26.1-23B85 |
| Mac16,12 26.3 | 17,326.123B85 | 26.1-23B85 |
| Mac16,12 26.3 | 17,326.323D127 | 26.1-23B85 |
| Mac16,12 26.3 | 17,326.323D127 | 26.3-23D128 |
| Mac16,12 26.3 | 17,326.3.123D8133 | 26.3-23D128 |
| Mac16,11 26.2 | 17,326.423E246 | 26.4-23E5207q |
| Mac16,11 26.2 | 17,326.523F77 | 26.4-23E5207q |
| Mac16,11 27.0b2 | 17,326.5.223F84 | 26.4-23E5207q |
| Mac16,6 26.4.1 | 17,326.623G71 | 26.4-23E5207q |
| Mac16,11 27.0b2 | 17,326.6.123G83 | 26.4-23E5207q |
| Mac16,11 27.0b2 | 17,327.024A5380h | 26.4-23E5207q |
| Mac16,6 26.4.1 | 17,327.024A5390f | 26.4-23E5207q |
| Mac16,6 26.6.1 | 17,327.024A5408d | 26.4-23E5207q |
| Mac16,11 27.0b2 | 17,327.024A5418b | 26.4-23E5207q |
| Mac16,11 27.0b2 | 17,327.024A5424a | 26.4-23E5207q |
Veelgestelde Vragen (FAQ)
zsh: killed ./vphone-cli — De AMFI/debug restricties zijn niet omzeild. Raadpleeg de sectie Voorwaarden (amfigetoutofmy_way=1 of amfidont).Virtualization is not available on this hardware — Je Mac is zelf een VM; PV=3 guest boot kan niet genest worden. Gebruik een niet-geneste macOS 15+ host.- Blijft hangen op "Press home to continue" — Maak verbinding via VNC en klik met de rechtermuisknop (klik met twee vingers) om de home-knop te simuleren.
- Systeem-apps worden niet geïnstalleerd — Kies tijdens de iOS-setup niet voor Japan of de EU als regio (vanwege extra regulatoire controles die de VM niet kan doorlopen); kies bijvoorbeeld de Verenigde Staten.
- App crasht bij opstarten met
EXCGUARD / GUARDTYPEMACHPORT — Patch opnieuw met vphone-cli fw patch <name> --variant <v> --force-exc-guard en voer vervolgens opnieuw de restore/installatie uit (#291). Dit staat standaard aan voor iOS 18 bases.
- Een .ipa/.tipa installeren — Gebruik het Install-menu van de draaiende VM (sleep-and-drop of bestandsselectie).
cfw install blijft hangen bij het opnieuw ondertekenen van een systeem-binary (bijv. Campo), geheugenverbruik stijgt onbeperkt — Bekende bug in ldid-procursus tot versie 2.1.5-procursus7 (de huidige Homebrew stable). De functie bytes(uint64_t) roept __builtin_clzll(0) aan zonder zero-guard, wat undefined behavior is. Dit resulteert in een loop die oneindig bytes naar een buffer schrijft. Dit wordt getriggerd door elke entitlements plist die een integerwaarde van precies 0 bevat. Opgelost in upstream, maar nog niet in een tagged release; build handmatig vanuit source: brew install --HEAD ldid-procursus && brew link --overwrite ldid-procursus. Beëindig eerst het hangende ldid-proces (sudo kill -9 <pid>).
Automatisering
vphone-cli biedt een host-control socket (<bundle>/vphone.sock) voor programmatische besturing — screenshots, touch, swipes, hardware-toetsen, klembord. Elke actie retourneert een inline screenshot voor AI-gestuurde E2E-tests. Zie vphone-mcp voor een MCP-server die dit wrapt.
Erkenningen
wh1te4ever/super-tart-vphone-writeup
Groetjes,