개요
Apple 실리콘 Mac에서 가상 iPhone을 생성, 패치 및 부팅하는 커맨드라인 도구입니다. IPSW 다운로드, DFU 복원 및 커스텀 펌웨어 설치를 자동으로 수행하며, 패치가 없는 상태부터 완전한 탈옥까지 다양한 변형을 지원합니다. Apple의 Virtualization.framework와 PCC 연구 VM 인프라를 기반으로 구축되었습니다.
README 미리보기
🇰🇷한국어 | 🇯🇵日本語 | 🇨🇳中文 | 🇬🇧English\n\n# vphone-cli\n\nBoot a virtual iPhone via Apple's Virtualization.framework using PCC research VM infrastructure.\n\n\n\n## Prerequisites\n\n**Host:**\n\n- Apple Silicon\n- macOS 15+ (Sequoia)\n- Xcode + iOS SDK (cross-compiles the guest daemon)\n- [SIP/AMFI relaxation to allow private PV=3 entitlements with unsigned-binary](#sipamfi-relaxation)\n\n**Dependencies:**\n\n```bash\nbrew install python@3.13 aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd\n```\n\n## Install\n\n```bash\nbrew install zqxwce/tap/vphone-cli\n```\n\n## Build\n\n```bash\ngit clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git\n\n./scripts/setup_tools.sh # install deps, build toolchain submodules, create the Python venv\n./scripts/build.sh # build + sign vphone-cli, bundle the .app, cross-compile vphoned\n\ncd .build/vphone-cli.app/Contents/MacOS/\nvphone-cli --help\n```\n\n## Quick Start\n\nOne command creates a VM end-to-end (download → patch → DFU restore → CFW install → first boot):\n\n```bash\nvphone-cli vm create myphone -V jb # -V / --variant\n\nvphone-cli vm launch myphone\n```\n\n## Commands\n\n`vphone-cli vm create` runs the whole pipeline; the individual steps below let you drive it manually or re-run one stage.\n\n### Manage\n\n```bash\nvphone-cli vm list # list VMs (--json for scripting)\nvphone-cli vm info myphone # show one VM\nvphone-cli vm new myphone # create an empty bundle (cpu/mem/disk options)\nvphone-cli vm config myphone --cpu 8 --memory 8192\nvphone-cli vm clone myphone myphone-2 # fast APFS clone, fresh device identity\nvphone-cli vm export myphone --out myphone.tzst # zstd fast by default (--max = xz -9); --out may be a dir (auto-names .tzst/.txz); skips restore dir + staging files\nvphone-cli vm import myphone.tzst --name restored\nvphone-cli vm rename myphone iphone16\nvphone-cli vm d
FAQ (5)
문제 해결macOS 27에서 VPhone Clone 옵션이 작동하지 않는 문제를 해결하는 방법
**VPhone.bundle 2.9.0**으로 업그레이드하세요. 수정 사항은 커밋 7d22444d에 포함되어 있습니다. macOS 27에서는 /dev 디바이스 번호가 Int32.max를 초과할 수 있으며, 이로 인해 /dev/null, 디스크 이미지, SEPStorage 또는 nvram.bin을 열고 있는 프로세스를 스캔할 때 Clone의 복사 전 검사에서 크래시가 발생합니다. 이 문제는 vphone-cli vm clone, 스냅샷 및 되돌리기에도 영향을 줍니다. 2.9.0 번들을 설치한 후 기존 가상 머신 각각의 **Core Bundle** 설정을 **2.9.0**으로 업데이트한 다음, **Clone…**, 스냅샷 또는 되돌리기를 다시 사용하세요.
문제 해결apps.install을 사용하여 대용량 IPA를 설치할 때 "IPA: archive expands beyond one GiB" 오류를 어떻게 해결하나요?
**icli 0.7.18 이상**이 포함된 빌드로 업그레이드하세요. vphone-cli main은 커밋 9c9446a0부터 이를 사용합니다. 해당 버전에서는 추출 제한이 **1 GiB에서 8 GiB로** 상향되었고, 최대 항목 수가 **50,000에서 400,000으로** 늘어났습니다. 업그레이드 후 다시 시도하세요:
vphone-launchpad-cli guest rpc <machine> apps.install '{"path":"<.ipa의 게스트 경로>"}'그러면 96,764개의 항목이 있는 1.89 GB IPA가 정상적으로 추출됩니다. 이전 릴리스에서는 제한을 변경할 수 있는 환경 변수, plist 또는 런타임 설정이 없으며, 1 GiB 상한은 컴파일 타임 상수였습니다. vphone-launchpad 2.8.0/icli 0.7.17을 계속 사용하는 경우 업그레이드하거나 더 큰 kArchiveByteLimit 값으로 커스텀 icli를 빌드해야 합니다. 새로운 거부 메시지에는 실제 크기가 포함됩니다(예: IPA: archive expands to 8.79 GiB, over the 8 GiB limit).
문제 해결iOS 18의 VPhone Launchpad에서 "Set up and slim system failed" 오류 "service group(s) accounts need the trimmed service list"를 해결하는 방법
이 문제는 Launchpad 2.9.5가 "Turn off unneeded services"가 활성화되어 있을 때(기본값) 항상 --accounts-off를 전달하지만, 축소된 서비스 목록은 iOS 26/27용 vphoned에만 존재하기 때문에 발생합니다. iOS < 26(예: iOS 18.6.2)에서는 설정 단계가 실패하며, 재시도해도 동일한 실패 인수가 반복됩니다. 우회 방법: 머신을 생성할 때 Advanced Options → Services and Apps를 열고 "Turn off unneeded services"를 OFF로 설정하세요. 그러면 Launchpad가 --accounts-off 대신 --service-profile none을 전달하여 생성이 성공합니다. iOS < 26에서는 어차피 해당 버전에 축소된 서비스 목록이 존재하지 않으므로 잃는 것이 없습니다. 올바른 수정 방법은 Launchpad가 trimmedServiceProfileMajors([26, 27])에 포함된 iOS 메이저 버전에만 --accounts-off를 전달하도록 하는 것입니다.
문제 해결VPhone에서 Bark가 'Unknown Status'를 표시하고 APNs 디바이스 토큰을 가져오지 못하는 이유는 무엇인가요?
이는 예상된 동작입니다. VPhone은 Apple APNs 디바이스 토큰을 얻거나 APNs를 통해 전달되는 원격 알림을 수신하는 것을 지원하지 않습니다. APNs 등록에는 Apple 디바이스 증명(attestation)과 비공개 보안 토큰 교환이 필요하며, 이는 가상 환경에서 제공할 수 없기 때문입니다. 수정 계획은 없습니다. 알림을 활성화하거나, aps-environment: production entitlement를 보유하거나, com.apple.apsd가 실행 중임을 확인하더라도 사용 가능한 토큰이 생성되지 않습니다. 우회 방법으로, Bulletin Board와 통신하여 동등한 알림 기능을 제공하는 커스텀 데몬을 구현하세요.
문제 해결vphone에서 roothide bootstrap의 SSH(OpenSSH)가 작동하지 않는 문제를 해결하는 방법은?
roothide bootstrap 환경의 vphone 2.1.0에서 irisin 패키지 매니저로 openssh만 설치하는 것으로는 충분하지 않습니다. /private/var/containers/Bundle/Application/.jbroot-* 내부에 rootfs 심볼릭 링크가 여전히 누락되어 있습니다. 해결 방법: irisin에서 base 패키지도 함께 설치하세요. openssh와 base가 모두 설치되면 추가 단계 없이 SSH가 정상적으로 작동합니다.