vphone-cli/docs/README_ko.md

🇰🇷한국어 | 🇯🇵日本語 | 🇨🇳中文 | 🇬🇧English

vphone-cli

PCC 리서치 VM 인프라를 사용하여 Apple의 Virtualization.framework로 가상 iPhone을 부팅합니다.

모든 것은 단일 vphone-cli 바이너리를 통해 실행됩니다 — VM 생성, 패치, 복원, 설치, 부팅, 관리. 빌드 후에는 make가 필요하지 않습니다.

테스트 환경

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를 참조하세요.

사전 요구 사항

호스트: macOS 15+ (Sequoia), 중첩되지 않은 Mac (Virtualization.framework는 중첩할 수 없습니다). Private PV=3 권한 + 서명되지 않은 바이너리 워크플로우에는 SIP/AMFI 완화가 필요합니다. 다음 두 가지 방법 중 하나를 선택하세요 — SIP 설정과 AMFI 설정은 함께 가야 하므로 섞지 마세요:

방법 A — SIP를 완전히 비활성화한 후, boot-arg로 AMFI를 비활성화 (가장 관대). 복구 모드에서 (전원 버튼 길게 누르기 → 터미널):

csrutil disable
csrutil allow-research-guests enable

그런 다음 macOS로 재부팅하고 AMFI boot-arg를 설정합니다 (적용되려면 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로 재부팅하고 amfidont (또는 amfree)로 저장소를 허용 목록에 추가합니다:

sudo amfidont --path <path_to_vphone-cli.app>

less (patchless) 변형은 방법 A, 또는 amfidont -S를 포함한 방법 B(sudo amfidont -S --path <path_to_vphone-cli.app>)가 필요합니다.

의존성:

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 런타임을 참조하세요.)

빌드

두 개의 일회성 부트스트랩 스크립트(컴파일된 바이너리는 스스로를 빌드할 수 없습니다)를 실행하면, 그 다음부터는 모든 것이 vphone-cli입니다:

./scripts/setup_tools.sh      # 의존성 설치, 툴체인 서브모듈 빌드, Python venv 생성
./scripts/build.sh            # vphone-cli 빌드 및 서명, .app 번들 생성, vphoned 크로스 컴파일

아래 예제가 그대로 작동하도록 바이너리를 PATH에 추가하세요:

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

빠른 시작

하나의 명령으로 VM을 처음부터 끝까지 생성합니다 (다운로드 → 패치 → DFU 복원 → CFW 설치 → 첫 부팅):

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

그러면 iOS <-> cloudOS 페어링을 선택하라는 안내가 표시됩니다. -i/--iphone-source 및/또는 **-c/--cloudos-source**를 전달하여 둘 중 하나(또는 둘 다)를 직접 지정할 수도 있습니다. 예:

# 로컬 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..."

그런 다음 부팅합니다:

vphone-cli vm launch myphone

명령어

vphone-cli vm create는 전체 파이프라인을 실행합니다; 아래 개별 단계들을 사용하면 수동으로 진행하거나 한 단계만 다시 실행할 수 있습니다.

관리

vphone-cli vm list                         # VM 목록 표시 (스크립팅용 --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.tar.xz   # xz -9; restore 디렉토리 + 스테이징 파일 건너뜀
vphone-cli vm import --in myphone.tar.xz --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. IPSW 다운로드 + 병합
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. 첫 부팅

최신 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로 찾으세요):

• SSH (탈옥): ssh -p 22222 mobile@<vm-ip> (비밀번호 alpine)
• SSH (regular/dev): ssh -p 22222 root@<vm-ip>
• VNC: vnc://<vm-ip>:5901

jb/exp 변형의 경우, Sileo와 TrollStore가 첫 부팅 시 자동으로 설치됩니다 (/var/log/vphone_jb_setup.log로 모니터링).

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를 사용하세요.

위치

vphone-cli가 생성하는 모든 것은 ~/.vphone/ 아래에 있습니다 — 서명된 번들이 이식 가능하도록 저장소와 .app 외부에 보관됩니다:

경로	내용
~/.vphone/VMs/	VM 번들 — VM마다 하나의 디렉터리. 라이브러리이며, $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 런타임 참조; $VPHONE_VENV_DIR로 재정의).

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이 충족할 수 없는 추가 규제 검사가 있습니다); 예를 들어 United States를 선택하세요.

앱이 실행 시 EXC_GUARD / GUARD_TYPE_MACH_PORT로 충돌 — vphone-cli fw patch <name> --variant <v> --force-exc-guard로 다시 패치한 다음, 다시 복원/설치하세요 (#291). iOS 18 베이스에서는 항상 켜져 있습니다.

.ipa/.tipa 설치 — 실행 중인 VM의 Install 메뉴를 사용하세요 (드래그 앤 드롭 또는 파일 선택기).

자동화

vphone-cli는 프로그래밍 방식 제어를 위한 호스트 제어 소켓(<bundle>/vphone.sock)을 노출합니다 — 스크린샷, 터치, 스와이프, 하드웨어 키, 클립보드 — 각 동작은 AI 주도 E2E 테스트를 위해 인라인 스크린샷을 반환합니다. 이를 감싸는 MCP 서버는 vphone-mcp를 참조하세요.

감사의 말

• wh1te4ever/super-tart-vphone-writeup