vphone-cli/Documents/README_ko.md

English · 中文 · 日本語 · 한국어

vphone-cli

Apple Silicon Mac에서 가상 iPhone을 실행합니다.

vphone-cli는 Apple의 Virtualization.framework와 PCC 연구용 가상 머신으로 iOS를 실행하며, 보안 연구, 리버스 엔지니어링, 디버깅에 적합합니다.

• 그래픽 창: Mac에서 가상 iPhone의 화면을 조작하고, 앱과 파일을 탐색하며, 스크린샷을 찍고 화면을 녹화합니다.
• 커스텀 펌웨어(Custom Firmware): 시스템에 패치가 미리 적용되어 있어 패키지 환경을 설치할 수 있습니다.
• 백업과 복제: 가상 머신을 내보내고, 가져오고, 복제할 수 있습니다.
• 자동화 API: 선택적으로 사용할 수 있는 로컬 HTTP 및 WebSocket 인터페이스입니다.
• 추가 의존성 없음: 실행에 Xcode, Python, Homebrew가 필요하지 않습니다.

1.x 버전은 1.0.14 릴리스를 참고하세요. 2.x는 1.x에서 만든 가상 머신을 시작할 수 없으므로 다시 만들어야 합니다.

준비 사항

• macOS 15 이상을 실행하는 물리 Apple Silicon Mac. macOS 가상 머신에서는 사용할 수 없습니다.

• 충분한 디스크 공간. 가상 머신마다 기본적으로 64 GB 가상 디스크를 사용하며, 펌웨어와 임시 파일이 별도로 공간을 차지합니다.

• 네트워크 연결. 시스템을 복원할 때 서명 티켓을 온라인으로 받아야 합니다.

• 보안 설정 변경. macOS 복구 모드로 진입하여 터미널에서 다음 명령을 실행한 뒤 재시동합니다.

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

  SIP는 켜진 상태로 유지되며 디버깅 제한만 완화됩니다. 이유와 다른 설정 방법은 호스트 설정을 참고하세요.

빠른 시작

1. 최신 릴리스에서 vphone-launchpad-<버전>-notarized.zip을 내려받아 압축을 풀고 엽니다. 모든 릴리스가 공증된 것은 아닙니다. 최신 릴리스에 -notarized 파일이 없으면 다운로드 안내에서 공증된 버전을 선택하세요.
2. Host Setup에서 개발자 도구 권한을 부여하고 도우미 프로그램을 설치합니다.
3. Core Bundle에서 Download and Install을 클릭합니다. Launchpad가 VPhone.bundle을 내려받아 검증한 뒤, 그 안의 가상 머신 프로그램이 이 Mac에서 실행되도록 허용합니다.
4. Machines에서 New Machine을 클릭하고 펌웨어 조합을 선택한 뒤 Create를 클릭합니다.

Launchpad가 펌웨어를 내려받고, 패치를 적용하고, 시스템을 복원한 뒤 첫 부팅을 진행합니다. 완료되면 가상 머신은 계속 실행됩니다.

직접 준비한 iPhone 및 cloudOS IPSW를 사용할 수도 있습니다. 검증된 조합은 호환성 안내를 참고하세요.

에이전트에게 맡기기

이 Mac에서 코딩 에이전트(Claude Code, Codex 등)를 사용한다면 직접 단계를 따라 하는 대신 아래 프롬프트를 붙여 넣으세요. 에이전트는 vphone 스킬을 읽고, 이미 준비된 부분을 확인한 뒤 Launchpad와 VPhone.bundle을 설치합니다. 관리자 암호나 macOS 복구 모드에서의 변경처럼 사용자가 해야 하는 단계에서는 멈추고 물어봅니다.

이 Mac에 vphone을 설정해 주세요. 먼저 다음 스킬을 읽으세요:
https://raw.githubusercontent.com/Lakr233/vphone-cli/main/Skills/vphone-guest-control/SKILL.md
그리고 같은 폴더의 references/ 아래에 링크된 파일을 읽고 그대로 따라 하세요:
공증된 최신 vphone-launchpad를 설치하고(모든 릴리스에 -notarized zip이 있는 것은
아닙니다), vphone-launchpad-cli를 PATH에 추가하고, Launchpad와 같은 시리즈의
VPhone.bundle을 설치한 뒤 `vphone-launchpad-cli status`로 확인하세요. SIP,
boot-args 등 호스트 보안 설정은 변경하지 말고, 펌웨어와 여유 디스크 공간을
제가 확인하기 전에는 머신을 만들지 마세요. 제가 해야 하는 단계에서는 무엇을
해야 하는지 정확히 알려 주고 기다리세요.

패키지 환경 설치

가상 머신에는 기본적으로 패키지 관리자가 없습니다. 설치 방법은 다음과 같습니다.

1. 메뉴 막대에서 **Apps > Install Bootstrap…**을 선택하고 레이아웃으로 roothide를 선택합니다(rootless는 더 이상 권장되지 않습니다). 가상 머신에 Irisin이 설치됩니다.

2. 처음 부트스트랩 설치를 할 때는 Irisin에서 다음 패키지를 한 번에 모두 선택하고 설치 버튼을 길게 누른 뒤 Bootstrap Install을 선택합니다.

   • apt
   • bash
   • uikittools
   • launchctl
   • openssh-server

   이 패키지들은 한 번의 부트스트랩 설치로 함께 설치하는 것을 권장합니다. 일부 패키지는 서로 의존하며(예: bash와 debianutils), 특히 openssh-server는 순환하거나 부정확한 의존성 선언을 포함하고 있어 일반 설치로 하나씩 설치하면 도중에 실패할 수 있습니다.

3. 처음 설치를 마친 뒤에는 다른 패키지를 일반 설치로 설치하면 됩니다.

처음 설치에 실패했거나 설치 후 환경이 비정상적인 상태가 되었다면 그 자리에서 복구하려 하지 말고, **Apps > Uninstall Bootstrap…**으로 환경을 삭제한 뒤 1단계부터 다시 설치하십시오.

환경을 삭제하려면 **Apps > Uninstall Bootstrap…**을 선택합니다. 삭제 후 가상 머신이 재시동됩니다.

Option 키를 누른 채 Apps 메뉴를 열면 두 가지 항목이 더 있습니다.

• Install Bootstrap from File…: 로컬 Irisin .deb로 설치합니다.
• Uninstall Bootstrap Without Restarting…: 가상 머신을 재시동하지 않고 환경을 삭제합니다.

명령줄

Launchpad는 VPhone.bundle 안의 vphone-cli로 가상 머신을 관리하며, 터미널에서 직접 사용할 수도 있습니다.

작업	명령
가상 머신 목록 보기	vphone-cli vm list
가상 머신 정보 보기	vphone-cli vm info myphone
가상 머신 시작	vphone-cli vm launch myphone
가상 머신 중지	vphone-cli vm stop myphone
가상 머신 복제	vphone-cli vm clone myphone copy
가상 머신 내보내기	vphone-cli vm export myphone --out myphone.tzst
가상 머신 가져오기	vphone-cli vm import myphone.tzst --name restored

가상 머신은 기본적으로 ~/.vphone/에 저장됩니다. 전체 명령은 vphone-cli <group> --help로 확인하세요. Launchpad 없이 가상 머신을 만드는 방법은 생성 및 실행을 참고하세요.

자동화 API

시작할 때 --api-listen을 추가하면 활성화됩니다.

vphone-cli vm launch myphone --api-listen 127.0.0.1:8765
# 출력에 [api] token: …이 표시됩니다
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/v1/health

시작할 때마다 새 token이 생성됩니다. 고정된 token을 사용하려면 환경 변수 VPHONE_API_TOKEN을 설정하세요. token이 없는 요청과 웹 페이지에서 온 요청은 모두 거부됩니다. 인터페이스 설명은 API 문서를 참고하세요.

문제가 생기면

먼저 문제 해결을 확인하세요. 시스템이 가상 머신 프로그램을 거부하는 경우, 복원 실패, “Press home to continue”에서 멈추는 경우 등을 다룹니다. 그래도 해결되지 않으면 이슈를 등록해 주세요.

문서

문서	내용
다운로드 안내	공증된 Launchpad 버전과 맞는 VPhone.bundle 버전
호스트 설정	SIP 및 AMFI 설정, 소스 빌드, 환경 점검
생성 및 실행	펌웨어 출처, 생성 절차, 저장과 백업
호환성 안내	검증된 펌웨어 조합
문제 해결	자주 발생하는 오류와 해결 방법
네트워크	네트워크 모드, 그리고 Mac이 VPN이나 프록시를 쓸 때의 tunnel
Launchpad 명령줄	vphone-launchpad-cli로 로컬 빌드 설치 및 테스트
연구 기록	패치와 구현 세부 사항

프로젝트 구조

• vphone-launchpad: VPhone.bundle을 내려받아 설치하고 호스트를 설정하는 Mac 앱입니다. 별도로 배포됩니다.
• vphone-cli: 펌웨어 준비, 패치 적용, 시스템 복원, 가상 머신 관리를 담당합니다.
• vphone-vm: 가상 머신을 실행하고 가상 머신 창을 표시합니다.
• vphoned: 가상 머신 안의 제어 서비스로, 창의 기능과 API는 모두 이를 통해 동작합니다.

경로	내용
VPhoneExecutable/	vphone-cli, vphone-vm, 펌웨어 패치와 복원
VPhoneKit/	호스트 공용 라이브러리와 API 클라이언트
VPhoneDaemon/	vphoned
VPhoneGuestComponents/	가상 머신 안의 hook과 도우미 프로그램
VPhoneLaunchpad/	Launchpad 앱과 도우미 프로그램

소스에서 빌드하려면 xcodebuild -workspace VPhone.xcworkspace -scheme VPhone build를 실행합니다. 결과물은 VPhone.bundle입니다.

감사의 말

• wh1te4ever/super-tart-vphone-writeup