vphone-linux

Run vphone-cli's virtual iPhone on a Linux x86_64 host.

iOS 27.0.1 (iPhone 16 Pro, at 2x) running on a Linux PC (Fedora, NVIDIA GPU) in vphone-linux, created with setup/create-vm.sh.

vphone-cli runs iOS on an Apple Silicon Mac with Apple's Virtualization.framework, on the vresearch101 virtual platform that Apple's Private Cloud Compute (PCC) research VMs use. vphone-linux boots the same VM bundle on Linux, with no Apple code at run time, and can also **create it on Linux with no Mac at all** (see docs/CREATE-ON-LINUX.md):

• QEMU (a fork of ChefKissInc/QEMUAppleSilicon) gains a

• reims-vgpu implements Apple's ParavirtualizedGraphics

• metal2vulkan translates the guest's Metal work to

This repository is the glue: the launcher (run-vphone.sh), the test and profiling tools (tools/), the Linux build of vphone-cli's firmware tooling (linux-create/) and the documentation. The three forks are git submodules (see Repository layout).

Development updates: @YahiaDev on X.

Status

So far tested on one PC: Fedora 44, Intel i7-14700K, 62 GB RAM, NVIDIA RTX 4080 SUPER (driver 615.71.09).

Tested guest pairings on Linux:

| Device | iOS | cloudOS | State | |---|---|---|---| | iPhone17,3 (iPhone 16 Pro) | 26.6.2 (23G90) | 26.4 (23E5207q) | end-to-end: the home screen, created with no Mac | | iPhone17,3 (iPhone 16 Pro) | 27.0.1 (24A446) | 26.4 (23E5207q) | end-to-end with setup/create-vm.sh: the home screen at 2x, Auto-Lock Never | | iPhone19,4 (iPhone Duo) | 27.1 (24A94425) | 26.4 (23E5207q) | the home screen: display, wallpaper, touch (keep it at 3x); needs this repo's QEMU (native X1 and CSSC) |

Works

• A full boot: AVPBooter, iBoot, SPTM/TXM, XNU, sepOS on the emulated SEP, the encrypted Data volume,

• Home screen, wallpaper, widgets, Control Center and built-in apps (Settings, Calendar, Maps, Photos,

• Touch: QEMU's usb-touchscreen, which iOS accepts as the built-in main-screen digitizer. Taps,

• Home: a swipe up from the bottom edge, or a middle click. QEMU turns these into Cmd+H, iOS's Home

• vphoned, vphone-cli's guest daemon, over vsock (port 1339): health, screen.unlock, apps.launch,

• Your own apps: an iOS app built on Linux with xtool installs

Creating the VM on Linux, with no Mac

• Done end to end on the test PC (2026-10-24), from an empty bundle: vphone-cli 2.12.1's

• The boot ROMs are OpenAVB and OpenSEP, the open-source ROMs vphone-cli ships, in place of

Known limits

• Speed. The guest's arm64e code runs under TCG (there is no hardware virtualization of arm64 on

• Creating the VM needs root for several steps, about 45 GB free disk, and about an hour plus the

• Only the NVIDIA host GPU has been tested. reims-vgpu documents what AMD GPUs need (/dev/udmabuf).
• vphoned's GET /v1/files/content stops after 64 KiB on the default vhost-vsock datapath; use

• reims-vgpu runs in census mode by default: a Metal feature it cannot model costs an inexact frame

• Untested: networking, audio, multiple VMs at once.
• Never boot two VMs on one Disk.img: the drives are opened with file.locking=off, and a second

Quick start

You need a Linux x86_64 PC with a Vulkan GPU (NVIDIA tested), 16 GB RAM or more, about 100 GB free disk, and sudo. No Mac. Two steps:

git clone https://github.com/YahiaAngelo/vphone-linux.git && cd vphone-linux
./setup/setup.sh                    # deps + sources + all binaries (re-runnable)
./setup/create-vm.sh                # pick a device and an iOS version; it creates the VM

create-vm.sh menus down to a tested device/iOS pairing, runs the whole create flow (fw prepare + fw patch, the DFU restore, the SSH-ramdisk CFW install, the snapshot flip), keeps one state file per VM so a re-run resumes after a failed step, and starts QEMU exactly once at the end (never killed by the scripts). Non-interactive:

./setup/create-vm.sh --device "iPhone17,3" --ios 26.6.2 --scale 1
./setup/create-vm.sh --list         # every device and its tested pairings

The pairings tested here: iPhone17,3 + iOS 26.6.2 and + iOS 27.0.1 (end to end with these scripts: the home screen), and iPhone19,4 (the iPhone Duo) + iOS 27.1 (the home screen; keep it at 3x). Other pairings are macOS-tested and offered as "under test" with a confirmation. Already have a VM made with vphone-cli on a Mac? docs/CREATE-ON-MAC.md shows how to bring it over instead. The step-by-step manual path, with the packages and every command, is docs/SETUP.md.

Documentation

| Document | Contents | |---|---| | setup/ | The two-step setup in this repo: build everything, then pick a device and an iOS version and create the VM | | docs/SETUP.md | The manual step-by-step: what you need, dependencies, building, creating the VM, first boot, your own apps | | docs/CREATE-ON-LINUX.md | The create flow in detail: firmware, restore over USB/IP, custom firmware, first boot | | docs/CREATE-ON-MAC.md | Optional: creating the VM with vphone-cli on a Mac and copying it over | | docs/TROUBLESHOOTING.md | Known problems and fixes | | docs/ADVANCED.md | Building by hand, display scale, services, GPU clocks | | docs/ARCHITECTURE.md | How the machine model, SEP, GIC, USB touch, vsock and the GPU path fit together | | docs/PERFORMANCE.md | The TCG performance work, every tuning switch, and how to profile | | docs/TOOLS.md | Each script in tools/ | | docs/LICENSING.md | Licenses of the parts | | CONTRIBUTING.md | How to contribute |

Repository layout

vphone-linux/
├── build.sh               builds the submodules and QEMU
├── run-vphone.sh          the launcher: a vphone-cli VM bundle -> QEMU command line
├── tools/                 test, input, vphoned and profiling scripts (docs/TOOLS.md)
├── linux-create/          vphone-cli's firmware tooling built for Linux (fw, restore, cfw)
├── patches/               small patches for vphone-cli (Mac side)
├── docs/
├── qemu/                  submodule: qemu-vphone, branch vphone
├── reims-vgpu/            submodule: reims-vgpu fork, branch vphone
├── metal2vulkan/          submodule: metal2vulkan fork, branch vphone
├── vms/                   your VM bundles (ignored by git)
└── runs/                  test-run output (ignored by git)

The submodules are qemu-vphone, reims-vgpu and metal2vulkan, each on its vphone branch. reims-vgpu's Cargo.toml takes metal2vulkan from ../metal2vulkan, so the submodules must stay side by side as above. vphone-cli is not a submodule: on a Mac it runs from its own releases, and linux-create/sync-sources.sh builds its firmware tooling from a vphone-cli 2.12.1 checkout without changing its files.

Credits

• QEMU and ChefKissInc/QEMUAppleSilicon

• reims-vgpu, metal2vulkan

• vphone-cli by Lakr233 and contributors (VM creation, firmware

• The Asahi Linux project's documentation of Apple's GXF.

Legal

This project contains no Apple software. It does not ship firmware, IPSWs, ROMs, kernelcaches or VM images, and the emulator uses no code from Virtualization.framework. You create your own VM from firmware Apple publishes, on Linux or with vphone-cli on your own Mac. On Linux, vphone-cli's tooling downloads the IPSWs you name from Apple's servers, and the VM boots on the open-source OpenAVB/OpenSEP ROMs from vphone-cli's release.

Apple's software licenses restrict where and how its operating systems may run. Running an iOS or PCC guest outside Virtualization.framework on a Mac may not be permitted by those terms. vphone-cli describes its purpose as security research, reverse engineering and debugging; this project has the same purpose. You are responsible for complying with the licenses of the software you run.

"Apple", "iPhone", "iOS" and "Metal" are trademarks of Apple Inc. This project is not affiliated with or endorsed by Apple, ChefKiss, or the authors of the upstream projects.

The glue in this repository is MIT-licensed (LICENSE). The submodules have their own licenses: see docs/LICENSING.md.