Tóm tắt nhanh:
vphone-cli cho phép bạn boot một virtual iPhone chạy iOS 26+ trực tiếp trên Mac Apple Silicon bằng Apple Virtualization.framework, với khả năng jailbreak, SSH, VNC và control socket cho automation, rất phù hợp cho iOS security research, reverse engineering, automated testing và AI agent E2E.
vphone-cli là một công cụ dòng lệnh open-source giúp boot một virtual iPhone (iOS 26.x) trên macOS 15+ (Sequoia) bằng Apple Virtualization.framework và hạ tầng Private Cloud Compute (PCC) dùng cho research VM. Khác với iOS Simulator, đây là một kernel iOS thật với filesystem thật và stack bảo mật thực, nên rất phù hợp cho nghiên cứu bảo mật, jailbreak và phân tích hệ thống.
Dự án được phát triển bởi Lakr233, hiện có hàng nghìn sao trên GitHub và được cộng đồng iOS security, reverse engineering, cybersercurity và jailbreak sử dụng rộng rãi.
Yêu cầu hệ thống và lưu ý bảo mật
Để chạy vphone-cli, bạn bắt buộc phải dùng Mac Apple Silicon (M1–M4) với macOS 15 Sequoia hoặc mới hơn, chạy trên hardware thật chứ không phải trong VM (Virtualization.framework không hỗ trợ nested). Bạn nên chuẩn bị ít nhất 80–100GB dung lượng trống để lưu firmware, VM bundle và các cache liên quan.
Vì vphone-cli sử dụng private entitlements và unsigned binaries, bạn phải nới lỏng hoặc vô hiệu hóa một số cơ chế bảo mật như SIP (System Integrity Protection) và AMFI (Apple Mobile File Integrity). Có hai lựa chọn phổ biến:
- Option A: tắt hoàn toàn SIP rồi bật boot-args
amfi_get_out_of_my_way=1. - Option B: giữ SIP ở trạng thái “mostly on” nhưng nới debug và dùng công cụ như amfidont hoặc amfree để allowlist binary.
LƯU Ý: Đây là môi trường “research mode”, nên bạn không nên dùng Mac này cho công việc sản xuất hoặc chứa dữ liệu nhạy cảm; tốt nhất là dùng một máy riêng chuyên cho nghiên cứu.
Chuẩn bị môi trường: Homebrew, Xcode, Python, dependencies
Trước khi cài vphone-cli, hãy đảm bảo bạn đã:
- Cài Xcode đầy đủ (không chỉ
xcode-select) để có iOS SDK phục vụ cross-compile guest daemon. - Cài Homebrew trên macOS theo script chính thức.
- Cài Python 3.10+ (hoặc 3.13 trong bản mới), dùng cho toolchain và script hỗ trợ.
Tiếp theo, bạn cần cài bộ dependencies bằng Homebrew để hỗ trợ download firmware, patch boot chain, sign binary và thao tác với IPSW:
brew install [email protected] aria2 wget gnu-tar openssl@3 \
ldid-procursus sshpass keystone cmake libusb ipsw zstdCác package như aria2, ipsw và zstd dùng cho tải và xử lý IPSW, trong khi ldid-procursus phục vụ ký lại binary trong quá trình jailbreak.
Cài đặt vphone-cli bằng Homebrew (nhanh nhất)
Nếu bạn chỉ muốn dùng vphone-cli mà không quan tâm nhiều đến quy trình build, cách đơn giản nhất là cài từ Homebrew tap do tác giả cung cấp:
brew install zqxwce/tap/vphone-cliLệnh này sẽ cài một ứng dụng vphone-cli.app đã được build và ký sẵn, cùng với binary vphone-cli ở trong bundle, giúp bạn có thể chạy ngay mà không cần clone repo. Đây là lựa chọn tốt nếu bạn muốn nhanh chóng thử virtual iPhone, nhưng vẫn phải đảm bảo các yêu cầu về SIP/AMFI đã được cấu hình trước đó.
Build từ source: Toàn quyền kiểm soát
Nếu bạn muốn kiểm soát chi tiết hơn hoặc phát triển thêm tính năng, hãy build từ source trên GitHub:
git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
cd vphone-cli
./scripts/setup_tools.sh # cài deps, build toolchain submodules, tạo Python venv
./scripts/build.sh # build + sign vphone-cli, bundle .app, cross-compile vphonedCác script này sẽ:
- Tạo Python virtualenv với các module như
pymobiledevice3,aria2cphục vụ restore và ramdisk. - Build các công cụ hỗ trợ như trustcache, insert_dylib, cùng việc sign ứng dụng để có thể chạy trong môi trường macOS đã nới bảo mật.
Sau khi build xong, bạn có thể vào thư mục .build/vphone-cli.app/Contents/MacOS/ và chạy:
./vphone-cli --helpCấu trúc dữ liệu và vị trí lưu VM
Mặc định, toàn bộ dữ liệu vphone-cli được lưu dưới thư mục ~/.vphone/ để tách biệt với repo và .app đã ký. Một số path quan trọng:
~/.vphone/VMs/: mỗi VM là một bundle riêng, đây là “library” virtual iPhone của bạn.~/.vphone/ipsws/: cache các IPSW iPhone và cloudOS đã tải để dùng lại cho nhiều VM.~/.vphone/debs/: cache.debmà CFW jailbreak sẽ dùng (Sileo, apt, v.v.).
Bạn có thể override toàn bộ root bằng biến môi trường VPHONE_ROOT hoặc từng phần như VPHONE_LIBRARY_ROOT, VPHONE_VENV_DIR nếu muốn lưu trên ổ phụ hoặc thư mục riêng.
Quick start: Tạo và boot một virtual iPhone
Sau khi cài vphone-cli và cấu hình bảo mật xong, cách nhanh nhất để có một virtual iPhone là dùng lệnh “all-in-one”:
vphone-cli vm create myphone -V jb # tạo VM + tải firmware + patch + restore + CFW + first boot
vphone-cli vm launch myphone # boot VMTrong đó:
myphonelà tên VM, bạn có thể đặt tùy ý cho từng môi trường.-V jbchọn firmware variant dạng “jailbreak”, tự động cài Sileo và TrollStore khi boot lần đầu.
Nếu muốn kiểm soát từng bước, bạn có thể chạy pipeline thủ công:
# 1. Tạo bundle VM trống
vphone-cli vm new myphone
# 2. Chuẩn bị firmware
vphone-cli fw prepare myphone --iphone-version 26.1
# 3. Patch boot chain (jailbreak variant)
vphone-cli fw patch myphone --variant jb
# 4. DFU boot + restore
vphone-cli vm launch myphone --dfu &
vphone-cli restore myphone --get-shsh
vphone-cli restore myphone
vphone-cli vm stop myphone
# 5. Cài custom firmware (CFW)
vphone-cli cfw install myphone --variant jb
# 6. First boot
vphone-cli vm launch myphoneQuy trình này phù hợp nếu bạn cần debug từng step, đo thời gian restore, hoặc thử các variant khác nhau.
Các variant firmware: Less, Regular, Dev, Jailbreak, Experimental
vphone-cli cung cấp 5 biến thể firmware với mức độ bypass bảo mật tăng dần, được chọn qua --variant hoặc biến môi trường khi dùng Makefile.
| Variant | Đặc điểm chính |
|---|---|
less | Patch rất ít, giữ phần lớn mitigations iOS, phù hợp cho test gần với thiết bị thật. |
regular | Bypass AMFI, SSV, Img4, TXM; thích hợp cho đa số nghiên cứu hệ thống. |
dev | Thêm bypass entitlement/debug TXM, tiện cho developer, debug kernel/userland. |
jb | Full jailbreak, auto setup Sileo + TrollStore, cho phép cài tweak, Frida, v.v. |
exp | Mở rộng trên jb với patch chống VM-detection và các hack nghiên cứu sâu hơn. |
Khi mới bắt đầu, bạn nên thử regular hoặc jb để có môi trường vừa linh hoạt vừa “ít nguy hiểm” hơn so với exp.
Kết nối vào virtual iPhone: SSH, VNC, automation
Sau khi VM boot thành công, bạn có thể kết nối vào iOS bằng SSH hoặc VNC:
- Đối với variant jailbreak (
jb/exp), kết nối SSH theo usermobilecổng 22222 và mật khẩu mặc địnhalpine:
ssh -p 22222 mobile@<vm-ip>- Với
regular/dev, kết nối SSH userroot:
ssh -p 22222 root@<vm-ip>- VNC để xem màn hình iOS GUI và thao tác “như thật”:
vnc://<vm-ip>:5901Ngoài ra, mỗi VM có một host control socket vphone.sock cho phép bạn gửi lệnh chụp screenshot, mô phỏng touch, swipe, phím cứng, clipboard… và nhận lại screenshot inline, rất phù hợp cho automation và AI-driven E2E testing. Có dự án vphone-mcp xây một MCP server trên socket này, giúp tích hợp với LLM/agent framework dễ dàng.
Một số use case thực tế cho dev, security và AI agent
vphone-cli mở ra khá nhiều kịch bản thú vị cho dân kỹ thuật:
- iOS security research & reverse engineering: bạn có một môi trường iOS jailbreak được tái tạo nhanh, phục vụ phân tích kernel, sandbox, code signing, exploit chain mà không cần liên tục restore thiết bị thật.
- Automated mobile testing: thay vì rack đầy iPhone thật, bạn spin up/burn down các virtual iPhone bằng script, kết nối CI/CD, chạy test qua SSH/VNC hoặc control socket.
- Network / privacy lab: gắn Burp, mitmproxy, quan sát lưu lượng của app iOS trong môi trường dễ reset và snapshot.
- AI agent cho mobile: dùng control socket và screenshot feed để tạo agent tự động thao tác UI iOS, rất phù hợp với các workflow E2E testing hoặc automation thông minh.
Nếu muốn tham khảo một hướng dẫn rất chi tiết, bạn có thể xem bài “Mastering vphone-cli: Building a Jailbroken iOS 26.1 Virtual iPhone on Apple Silicon” trên Medium, trong đó tác giả đi qua từng bước từ SIP/AMFI đến make setup_machine JB=1.
Lời khuyên thực tế khi triển khai vphone-cli
Một vài kinh nghiệm thực tế giúp bạn đỡ “đau đầu” khi dùng vphone-cli:
- Chỉ dùng trên máy dành cho research: việc tắt/nới SIP/AMFI không nên áp dụng cho máy production hay máy chính dùng hàng ngày.
- Ưu tiên
make setup_machinecho lần đầu: Makefile của vphone-cli hỗ trợ target “lazy”make setup_machineđể tự động hóa download firmware, patch, restore và first boot; rất nên dùng trước khi thử pipeline thủ công. - Đừng chọn region Japan/EU khi setup iOS: tác giả warning rằng chọn Nhật hoặc EU có thêm regulatory checks mà VM khó thỏa điều kiện, dễ khiến system app không install được; hãy chọn United States hoặc region “dễ chịu” hơn.
- Theo dõi log jailbreak setup: với variant
jb/exp, script thiết lập Sileo/TrollStore chạy qua LaunchDaemon; nếu có lỗi, hãy xem log ở/var/log/vphone_jb_setup.logtrong guest. - Cập nhật ldid-procursus nếu bị treo khi re-sign: bản cũ của
ldid-procursuscó bug ghi buffer vô hạn với entitlements value0; nếucfw installtreo, bạn nên buildldid-procursustừ HEAD để tránh lỗi.
vphone-cli là mảnh ghép quan trọng cho mobile lab hiện đại
Nếu bạn đang làm iOS security, reverse engineering, automated mobile testing hoặc muốn xây AI agent tương tác UI iOS, vphone-cli là một mảnh ghép cực kỳ đáng thử trong lab của bạn. Nó đưa firmware iOS 26.x vào môi trường virtual hóa native trên Mac Apple Silicon, cho phép bạn thao tác với thiết bị “ảo mà thật” bằng SSH/VNC/script, và tái tạo môi trường chỉ bằng vài lệnh CLI.
Hãy bắt đầu bằng việc đọc README trên GitHub, chuẩn bị một Mac cho research mode, chạy brew install zqxwce/tap/vphone-cli hoặc build từ source, rồi thử vphone-cli vm create myphone -V jb để boot virtual iPhone đầu tiên của bạn. Từ đó, bạn có thể mở rộng sang nhiều VM, nhiều biến thể firmware và tích hợp với CI, toolchain security, hoặc hệ thống AI agent mà bạn đang xây dựng.
