vphone-web README

The project's README from github.com/34306/vphone-web. As one markdown file: README.md.

vphone-web

I vibe code this repo so please if you had anything issue with AI then just skip it. (i vibed but still checking the function before sharing so it must be work fine)

A self-hosted web platform for running multiple virtual iPhones at once in the browser — user accounts + RBAC, per-user device assignment, live screen streaming (WebRTC with an MJPEG/WebSocket fallback), touch & hardware-key input, IPA/TIPA install, an in-browser root shell and a file browser, on top of the vphone-cli engine (Apple Virtualization.framework, PV=3 research VMs).

You need build the vphone-cli and create your own base VM locally, i did not included it here due to large files.

Requirements

1. Clone (recursive)

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

This also creates vendor/vphone-cli/ with the full engine + toolchain.

2. Build the vphone-cli engine

cd vendor/vphone-cli
make setup_tools     # brew deps, build toolchain, create its Python venv
make build           # build + sign the vphone-cli binary
make bundle          # app bundle (bundles the IPA signing cert) — recommended
cd ../..

3. Create a base VM

Each web VM is an instant copy-on-write clone of a base VM directory. Build one with vphone-cli's automated pipeline (downloads IPSW + cloudOS, restores, patches, installs CFW, first boot).

See vendor/vphone-cli/README.md for the full firmware matrix, supported iOS/cloudOS builds, variants (regular / dev / jb / exp), and how to resolve IPSW URLs. When it finishes, the base lives at vendor/vphone-cli/vm/ (contains Disk.img, nvram.bin, SEPStorage, config.plist, AVPBooter*.bin, .vphoned.signed).

Tip — one base per iOS version. Keep each version's base in its own folder (vm/, vm-26.5/, vm-27/, …) and point the matching VPHONE_BASE_VM* env var at it. The web only offers versions whose Disk.img actually exists.

Boot cleanly. Always Stop a VM from the web UI (or Ctrl-C the process) and let it finish shutting down before copying/promoting a base — a hard kill leaves the APFS volume dirty and the next boot does a slow fsck replay.

4. Configure & run the web

cp .env.example .env          # then edit paths (see below)
make web_setup                # create .venv, install web deps
make web_seed_admin USER=admin PASS='choose-a-strong-password'
make web_run                  # serves http://127.0.0.1:8080

Open http://127.0.0.1:8080, sign in as the admin, then:

  1. Admin → Create VM — pick an iOS version; it clones the base instantly.
  2. Admin → assign the VM to one or more users.
  3. As a user: Start → Open → interact; drag on the screen for touch, use the home/power/volume buttons, or the SSH/Files tabs. Drop an .ipa/.tipa on the install zone to install.

Admin-only logs dashboard live-tails every VM at /logs.

5. (Optional) Expose it with a Cloudflare Tunnel

The server binds 127.0.0.1 only. To reach it from the internet without opening a port, use a Cloudflare Tunnel. You need a domain on Cloudflare.

brew install cloudflared
cloudflared tunnel login                      # authorize your domain (opens browser)
cloudflared tunnel create vphone              # creates a tunnel + credentials json
cloudflared tunnel route dns vphone phone.example.com   # your hostname

Create ~/.cloudflared/config.yml (replace the id + hostname with yours):

tunnel: <YOUR-TUNNEL-ID>
credentials-file: /Users/<you>/.cloudflared/<YOUR-TUNNEL-ID>.json
ingress:
  - hostname: phone.example.com
    service: http://localhost:8080
  - service: http_status:404

Run it:

cloudflared tunnel run vphone

Notes:

Auto-start on boot (macOS LaunchAgent, optional)

Run the web + tunnel automatically after a reboot/power-restore by creating two per-user LaunchAgents (~/Library/LaunchAgents/…) that RunAtLoad + KeepAlive: one execs make web_run (or uvicorn directly) from this repo, the other execs cloudflared tunnel run vphone. Web VMs need a GUI login session (WindowServer), so use a LaunchAgent (per-user), not a system LaunchDaemon; enable macOS Automatic Login for a fully unattended restore.

Credits

Built on vphone-cli by Lakr233. This repo adds the web platform layer on top.

vphone-web (34306/vphone-web)

Searching Database…

374 ·GitHub
Vphone-web
What is this?It is a self-hosted web platform for running multiple virtual iPhones in the browser at once, with user accounts, RBAC, live screen streaming, touch input, IPA install, a root shell and a file browser, built on top of the vphone-cli engine using Apple's Virtualization.framework.
Is this a standalone app or a layer on top of something else?It is a web layer (a server you run with uvicorn/make) that sits on top of the vphone-cli engine, which does the actual iOS virtualization; this repo only adds the multi-user browser UI on top of it.
How do I get it running?Clone the repo recursively to pull in vendor/vphone-cli, build the vphone-cli engine, create a base VM with vphone-cli's automated download/restore/patch pipeline, then configure and run the web server and sign in as admin to create and assign VMs.
Do I need a specific Mac for this, or will any machine do?You need macOS 15+ (Sequoia) on Apple Silicon specifically because it relies on PV=3 private virtualization, plus SIP and AMFI disabled, Xcode command-line tools, Homebrew and Python 3.11+.
Does it come with a ready-to-use virtual iPhone image?No — the base VM isn't included due to large file sizes; you have to build vphone-cli yourself and run its pipeline (IPSW + cloudOS download, restore, patch, first boot) to create your own base image before the web UI can clone VMs from it.
Can multiple people use the same install?Yes — it has user accounts with role-based access control and per-user device assignment, so an admin creates VMs and assigns them to specific users who then each get their own device.
Can I expose this to the internet safely?The server only binds to 127.0.0.1 by default; to reach it remotely you set up a Cloudflare Tunnel with your own domain, and the live video automatically falls back to MJPEG-over-WebSocket since Cloudflare can't proxy WebRTC UDP.
What is vphone-cli and how does it relate to this repo?vphone-cli (by Lakr233) is the underlying engine that performs the actual iOS virtualization via Apple's private Virtualization.framework APIs; vphone-web just adds a multi-user web frontend on top of it.
How do I install apps on a virtual iPhone?Drop an .ipa or .tipa file onto the install zone in a VM's web UI; uploads use chunked transfer to get around proxy body-size limits.
Should I trust that this code actually works?The author calls it vibe-coded, says they checked the functions before sharing, but also warns to skip AI-generated issue reports — so treat it as experimental, community-maintained code.
Does storage choice matter for the VMs?Yes — keep VM images on an internal SSD, not a slow external/USB disk, since iOS first boot does thousands of small writes that are impractically slow on slower storage.
What are similar projects?vphone-aio, macos, financial_intelligence_system_web, codflow, walle-web, macPad, scam-with-your-friends-web, windows
Which topics is it in?remote-desktop, jailbreak, file-manager, virtual-machine, webrtc, admin-dashboard, rbac, virtualization, cloudflare, apple, websocket, apple-silicon
Creator
34306
Size
0.2 MB
Stars
374
Updated
CommitSep 05
Age
1mo
Commits · 90 Days