vphone-web: a self-hosted web console for multiple virtual iPhones

The gap vphone-web fills between vphone-cli and a shared lab

vphone-cli runs virtual iPhones through Apple Virtualization.framework using PV=3 research VMs, but it is a command-line tool aimed at one operator on one machine. vphone-web is the layer that turns that engine into something a small team can share: user accounts with roles, per-user device assignment, live screen streaming in a browser, touch and hardware-key input, IPA and TIPA installation, an in-browser root shell and a file browser. The README describes it as "vphone-cli but you can use your mac as a host and control it over the web".

The intended user is an engineer or researcher who needs several iOS environments at once and is willing to run the host themselves. The repository does not ship a base VM. You build the engine, you build a golden base image, and the web platform clones that base per VM. That division of labour is the whole design, and it also explains why the setup section of the README is longer than the usage section.

Accounts, RBAC and copy-on-write clones: how the platform is put together

The web layer is a FastAPI application served by uvicorn, with SQLAlchemy against SQLite, passlib with bcrypt for credentials, and aiortc plus av for media. State lives in VPHONE_DATA_DIR, which the README says holds the SQLite database and the session secret. Configuration is read from a .env file by web/app/config.py and exported to child processes by the Makefile.

Each web VM is an instant copy-on-write clone of a base VM directory. The base itself is produced by vphone-cli's automated pipeline, which the README says downloads an IPSW plus cloudOS, restores, patches, installs CFW and performs a first boot. The finished base contains Disk.img, nvram.bin, SEPStorage, config.plist, AVPBooter*.bin and .vphoned.signed. Clones are written under VPHONE_VMS_DIR. Only iOS versions whose Disk.img actually exists are offered in the interface, so the version list is derived from the filesystem rather than from a fixed configuration table.

Resource accounting is explicit: VPHONE_DEFAULT_CPU and VPHONE_DEFAULT_MEM_MB set per-VM defaults, and VPHONE_RAM_BUDGET_MB makes the server refuse to start a VM if total running memory would exceed the budget. That is a coarse guard, but it is the right kind of guard for a shared host, because the failure mode it prevents (over-committing RAM until the hypervisor thrashes) is not something a user would diagnose on their own.

Installing vphone-web and creating the first admin

The clone is recursive because the engine lives in a submodule, so vendor/vphone-cli is populated at the same time.

git clone --recursive https://github.com/34306/vphone-web.git
cd vphone-web

The engine is built inside the submodule. make setup_tools installs Homebrew dependencies, builds the toolchain and creates its Python virtual environment; make build compiles and signs the vphone-cli binary; make bundle produces an app bundle that the README recommends because it bundles the IPA signing certificate.

cd vendor/vphone-cli
make setup_tools
make build
make bundle
cd ../..

At this point there is still no VM. The base image is created with vphone-cli's own pipeline, documented in vendor/vphone-cli/README.md, which also covers the firmware matrix, supported iOS and cloudOS builds, the regular, dev, jb and exp variants, and how to resolve IPSW URLs. When it finishes, the base sits at vendor/vphone-cli/vm/.

Now configure the web layer. Copy the example environment file, create the virtual environment and its dependencies, seed an admin, and start the server.

cp .env.example .env
make web_setup
make web_seed_admin USER=admin PASS='choose-a-strong-password'
make web_run

The server serves http://127.0.0.1:8080. Sign in as the admin, use Admin then Create VM to pick an iOS version and clone the base, then assign the VM to one or more users. As a user, Start then Open gives you the device; drag on the screen for touch, use the home, power and volume buttons, or the SSH and Files tabs. Dropping an .ipa or .tipa file on the install zone installs it. The admin logs dashboard live-tails every VM at /logs.

One tip from the README is worth repeating because it is easy to get wrong: keep one base per iOS version in its own folder (vm/, vm-26.5/, vm-27/) and point the matching VPHONE_BASE_VM* variable at it. The default VPHONE_BASE_VM is vendor/vphone-cli/vm and VPHONE_DEFAULT_IOS is 26.1.

Reaching it from outside, and why WebRTC falls back to MJPEG

The server binds 127.0.0.1 only. The README's recommended way to expose it without opening a port is a Cloudflare Tunnel, which requires a domain on Cloudflare. The steps are the standard ones: brew install cloudflared, cloudflared tunnel login, cloudflared tunnel create vphone, then cloudflared tunnel route dns vphone phone.example.com. A config.yml maps the hostname to http://localhost:8080 with a catch-all http_status:404 rule.

The interesting constraint is the media path. Live video uses WebRTC locally and automatically falls back to MJPEG over WebSocket through the tunnel, because Cloudflare cannot proxy WebRTC UDP. That fallback is what makes remote viewing work at all, and it is also why remote viewing should be expected to behave differently from local viewing. The README does not quantify the difference in latency or bandwidth, so treat MJPEG as the compatibility path rather than an equivalent one.

Two smaller details matter operationally. IPA upload uses chunked transfer to bypass proxy body-size limits. And if you serve subdomains such as logs.phone.example.com, you set VPHONE_COOKIE_DOMAIN=.example.com in .env so the session cookie is shared. The README warns never to commit the ~/.cloudflared/*.json credentials or cert.pem. For unattended restarts it suggests per-user LaunchAgents with RunAtLoad and KeepAlive, one for make web_run and one for cloudflared tunnel run vphone, noting that web VMs need a GUI login session with WindowServer, so a LaunchAgent rather than a system LaunchDaemon is the correct choice.

The host requirements are the real adoption cost

This is not a project you evaluate by reading the README and running a container. macOS 15 or later on Apple Silicon is required for PV=3 virtualization, and SIP plus AMFI must be disabled for the private Virtualization entitlements, with the exact recovery-mode steps living in the vphone-cli README. Disabling those protections on a machine you also use for other work is a decision that should be made deliberately, not as a setup step.

Storage is the second hard constraint. The README strongly recommends keeping VM images on an internal SSD rather than a slow external or USB disk, because iOS first boot performs thousands of small writes and is impractically slow on slow storage. That is a warning about a failure mode rather than a performance claim, and it is consistent with how copy-on-write clones behave under first boot.

There is also a data-integrity rule that is easy to violate in practice: always stop a VM from the web interface, or Ctrl-C the process, and let it finish shutting down before copying or promoting a base. A hard kill leaves the APFS volume dirty and the next boot spends time on a slow fsck replay. If your workflow involves snapshotting bases frequently, that rule shapes how you script it. Finally, the author states plainly that the repository was vibe coded and asks readers with concerns about AI-generated code to skip it, while noting the functionality was checked before sharing. That is an honest disclosure, and it should factor into how much you rely on the web layer without reading it.

Where vphone-web is the wrong tool

If you need one iOS simulator for app development, Xcode's simulator is already installed, requires no SIP changes, and does not need a base VM pipeline. vphone-web exists for the case where you want full virtual devices with a root shell and a file browser, shared across accounts, on a host you control.

If you need this to run on Linux or on Intel Macs, it will not. The requirements are macOS 15+ on Apple Silicon, and the engine depends on Apple Virtualization.framework. If you need a managed service with an SLA, nothing here provides one; you are the operator, including the tunnel, the LaunchAgents and the disk.

There is also a scaling ceiling that the configuration makes visible. VPHONE_RAM_BUDGET_MB defaults to 12288 with 4096 MB per VM, so the default budget fits roughly three running VMs before the server starts refusing to launch more. Raising the budget is a one-line change, but the underlying limit is the host's RAM and the fact that every running VM is a real virtual machine, not a lightweight sandbox.

Alternatives and the difference in approach

The closest alternative is vphone-cli on its own. It is the same engine, without the web platform: no accounts, no role separation, no per-user assignment, no browser streaming, no logs dashboard. If one person on one Mac is doing the work, the web layer adds a FastAPI service, a SQLite database, a session secret and a tunnel to maintain for capabilities nobody is using. The submodule layout makes this explicit, since vendor/vphone-cli is the full engine and toolchain and the repository's own Makefile only handles the web side.

A second alternative is a hosted device farm, where someone else runs the hardware, the network and the images. The trade is control for convenience: you would not be disabling SIP on your own machine, but you also would not have the in-browser root shell and file browser over your own base images, and you would not be choosing the iOS versions by placing Disk.img files in directories.

The distinguishing property of vphone-web is that the version catalogue is the filesystem. You add an iOS version by building a base and pointing a VPHONE_BASE_VM* variable at it, and the interface offers it only when Disk.img is present. That is a different model from a curated list maintained by a vendor, and it is the reason the setup cost is front-loaded.

Licence, maintenance and what upgrading involves

The repository is GPL-3.0. If you modify the web layer and distribute it, or offer it as a network service in a way your jurisdiction treats as distribution, the copyleft terms apply to the combined work. The engine in vendor/vphone-cli is a separate project by a different author, so its licence and its release cadence are separate questions; check that submodule directly rather than assuming it follows this repository. Nothing here is legal advice.

The last push to this repository was on 2026-09-05, and it is not archived. There are no releases retrieved, so there is no versioned upgrade path to follow: you track the main branch and the submodule pointer. That has a practical consequence. Because the base VM is built by vphone-cli and the web layer clones it, an engine update can change what a valid base looks like, and the README's advice to stop VMs cleanly before copying or promoting a base becomes part of your upgrade procedure rather than a one-off tip. Budget for rebuilding a base image when the firmware matrix in vendor/vphone-cli/README.md changes, and keep the .env paths for each version's base accurate so the version list in the interface stays truthful.

Editorial conclusion

Adopt vphone-web only if you already have a working vphone-cli base VM on Apple Silicon macOS 15+, you accept disabling SIP and AMFI on that machine, and you need several people to share virtual iPhones through a browser. Skip it if you want a ready-made hosted service, cannot dedicate a fast internal SSD, or are unwilling to build the engine and the base VM yourself. Before rolling it out, verify that VPHONE_BASE_VM points at a directory containing Disk.img, and that the web only lists the iOS versions whose Disk.img exists.

Frequently asked questions

Official sources

1. 34306/vphone-web on GitHub
2. Issues
3. License: GPL-3.0
4. README