# vPhone Workstation: a SwiftUI front-end for booting virtual iPhones on macOS

> vPhone Workstation wraps vphone-cli in a native macOS window for browsing, creating and booting iOS research VMs. It is a GUI layer, not an emulator, and it inherits every host restriction of Apple's Virtualization.framework.

**zqxwce/vphone-ws** — A native macOS app for managing virtual iPhones - browse, create, and boot iOS research VMs from a single window.

- Repository: https://github.com/zqxwce/vphone-ws
- Stars: 960 · Forks: 78
- Language: Swift
- License: MIT
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/zqxwce-vphone-ws

## What vPhone Workstation solves, and for whom

Booting a virtual iPhone is a command-line job. The underlying tool, vphone-cli, is what starts a guest on Apple's Virtualization.framework using PCC research VMs. That means firmware variants, resource sizing, UDIDs and lifecycle commands all live in a terminal, and a researcher who wants four or five guests configured differently ends up keeping notes rather than a library.

vPhone Workstation is the window over that. The README describes it as a SwiftUI front-end for vphone-cli, and the feature list is organised around the things a CLI makes you remember: a library of every VM with live running or stopped state, the iOS and cloudOS build, a detail view with CPU, memory, disk, network, device and UDID, and buttons for start, stop and bringing the running iPhone window to the front.

The audience is narrow on purpose. You need an Apple Silicon Mac, macOS 15 (Sequoia) or newer, and vphone-cli installed. This is a tool for people doing iOS research on their own hardware, not for teams that want a hosted device farm or a CI runner. Nothing in the README suggests a server mode or a remote API.

## The create wizard is the actual product

Listing VMs is table stakes. The part of vPhone Workstation that carries weight is the create wizard, because it encodes a decision order that is easy to get wrong by hand: name, then variant, then firmware pairing, then resources.

The variant list is Less, Regular, Developer, Jailbreak and Experimental. The README frames this as picking how much of iOS's security to peel back, and then the wizard recommends a firmware pairing for that choice. That ordering matters. If you pick a firmware first and a variant second, you can end up with a pairing the app would not have suggested, and the README does not describe a validation pass that catches it afterwards.

Resource allocation (CPU, memory, disk) comes last, after the variant. Progress is streamed from vphone-cli step by step rather than shown as a single spinner, and the log can be exported for issue reports. That export is a small feature with real value: when a boot fails, the useful artefact is the CLI transcript, and the app gives you a way to hand it over without reconstructing the command you ran.

## Host readiness is where most first runs fail

Before any VM exists, vPhone Workstation checks the host. The README lists five conditions: that vphone-cli is found, that macOS is new enough, that the host is not itself a VM, that research guests are allowed via csrutil allow-research-guests, and that AMFI is bypassed through either the amfi_get_out_of_my_way boot-arg or the amfidont daemon.

Two of those are not ordinary setup steps. Allowing research guests changes a system security setting on the machine you are using, and bypassing AMFI is a deliberate weakening of code-signing enforcement at boot. The README presents each check with an actionable message when it fails, which is the right design, but the app cannot make the decision for you. If you are not prepared to run those on a given Mac, vPhone Workstation is the wrong tool for that Mac, regardless of how the GUI looks.

The host-is-not-a-VM check is also worth reading literally. Nested virtualisation is not the target here, so a macOS VM on a cloud provider is not a supported place to run this, even if it reports Apple Silicon.

## Installing vPhone Workstation and creating a first VM

The dependency comes first. vphone-cli is a separate project and the README installs it from a Homebrew tap:

```bash
brew install zqxwce/tap/vphone-cli
```

With the CLI on your PATH, the app itself installs from the same tap:

```bash
brew install zqxwce/tap/vphone-ws
```

If you would rather build from source, the repository ships a bundle script that runs a release build and assembles the app bundle:

```bash
./scripts/bundle.sh          # swift build -c release + bundle .build/vphone-ws.app
open .build/vphone-ws.app
```

On first launch, check the host readiness panel before creating anything. Every listed check (vphone-cli present, macOS version, host not a VM, research guests allowed, AMFI bypassed) should report as satisfied. If one does not, the message tells you what to change; the app does not silently continue.

Then open the create wizard and work through it in order: name the VM, choose a variant, accept or override the recommended firmware pairing, and set CPU, memory and disk. Progress streams from vphone-cli as it runs. When the VM appears in the library, use the lifecycle controls to start it, and use the front button to bring the running iPhone window forward when it ends up behind other windows.

## Where vPhone Workstation stops being the right tool

The honest limitation is architectural. vPhone Workstation is a front-end. The README says so directly, and that means every capability boundary of vphone-cli is also a boundary of the app. If the CLI cannot do something, no amount of SwiftUI will add it.

The second limitation is the variant list. Less, Regular, Developer, Jailbreak and Experimental describe a spectrum of how much of iOS's security is peeled back, and the wizard pairs each with firmware. That is a curated path, which is helpful for a first VM and constraining for someone who already knows the exact combination they want. The README does not document an arbitrary pairing route that bypasses the recommendation, so treat the wizard as the supported path rather than a general configuration editor.

The third is operational. Export produces a .tar.xz archive, which is fine for moving a VM between machines and poor for incremental backup: a small change inside the guest means a new full archive. There is no documented snapshot, rollback or scheduling feature in the README, so anyone expecting VM-style point-in-time recovery should plan around that absence rather than assume it exists.

Finally, the project is young. The releases listed are v0.0.1, v0.0.2 and v0.0.3, all within August 2026, and the last push to the repository was on 2026-08-12. That is recent, but a 0.0.x line means interfaces and the export format can still move.

## vPhone Workstation versus driving vphone-cli directly

The real alternative is not another GUI. It is the CLI underneath, used on its own. The difference in approach is not cosmetic: with vphone-cli you express a VM as a command, which means it can live in a shell script, a Makefile or a CI job, and the exact invocation is the record of what you did. With vPhone Workstation you express a VM as an object in a library, which means state is visible at a glance and lifecycle actions are one click, but the configuration lives in the app rather than in a file you can diff.

That trade is worth naming. If your work is exploratory (spin up a variant, look at something, throw it away), the library view and the streamed create progress save real friction. If your work is reproducible (the same guest configuration on three machines, rebuilt on demand), the CLI is the better substrate and the GUI adds a layer you will end up documenting anyway.

There is a middle position the README supports: use the app to create and manage VMs, and use the exportable log when something goes wrong, because that log is the CLI transcript. You get the GUI for day-to-day work and the command record when you need to reproduce a failure.

## Licence and the cost of keeping it current

vPhone Workstation is MIT licensed, and the LICENSE file sits at the top level of the repository alongside Package.swift, Sources, Resources, tests and scripts. MIT is permissive: you can use, modify and redistribute it, including in commercial settings, provided the copyright notice and permission notice travel with the copies. That is a summary of the licence identifier, not legal advice; read LICENSE for the actual terms.

The licence question that actually bites here is not the app's. vphone-cli is a separate project with its own licence, and the app is useless without it. The README links to it and installs it from the zqxwce tap, but it does not restate that project's terms, so check them separately if you plan to redistribute anything.

Upgrade cost is low by construction. Both pieces come from the same Homebrew tap, so brew upgrade covers the normal path, and the source build is a single script invocation. The thing to watch is the pairing between app and CLI: the app streams progress from vphone-cli and reads its VM state, so a CLI release that changes output format is the most likely source of breakage. Since the app is at 0.0.3, pinning a known-good CLI version is a reasonable precaution on a machine you depend on.

## Conclusion

Adopt vPhone Workstation if you already run vphone-cli on an Apple Silicon Mac with macOS 15 or newer and you want a window for the library, the create wizard and the lifecycle buttons instead of typing commands. Do not adopt it if you are on Intel, if you are not willing to run csrutil allow-research-guests and an AMFI bypass on the host, or if you need a headless or scriptable workflow, because the README presents the app as a front-end and the CLI remains the thing that actually boots a VM. Before you rely on it, verify that brew install zqxwce/tap/vphone-cli resolves on your machine, that the host readiness panel reports every check as passing, and that csrutil allow-research-guests is a change you accept on that host.

## FAQ

### What is vPhone Workstation and what does it need to run?

It is a native macOS app that manages virtual iPhones, described in the README as a SwiftUI front-end for vphone-cli, the command-line tool that boots virtual iPhones on Apple's Virtualization.framework using PCC research VMs. It requires an Apple Silicon Mac, macOS 15 (Sequoia) or newer, and vphone-cli installed.

### How do I install vPhone Workstation with Homebrew?

Install vphone-cli first with brew install zqxwce/tap/vphone-cli, then install the app with brew install zqxwce/tap/vphone-ws. Both come from the same tap.

### Why does vPhone Workstation say my host is not ready?

The host readiness check covers five conditions: that vphone-cli is found, that macOS is new enough, that the host is not itself a VM, that research guests are allowed via csrutil allow-research-guests, and that AMFI is bypassed through the amfi_get_out_of_my_way boot-arg or the amfidont daemon. The README states each failing check shows an actionable message.

### Can I use vPhone Workstation if I do not want to change host security settings?

No. The host readiness check expects research guests to be allowed with csrutil allow-research-guests and AMFI to be bypassed, so a host that keeps those settings untouched will not pass the checks the README lists.

## Sources

- [Issues](https://github.com/zqxwce/vphone-ws/issues)
- [License: MIT](https://github.com/zqxwce/vphone-ws/blob/main/LICENSE)
- [README](https://github.com/zqxwce/vphone-ws/blob/main/README.md)
- [Releases](https://github.com/zqxwce/vphone-ws/releases)
- [zqxwce/vphone-ws on GitHub](https://github.com/zqxwce/vphone-ws)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zqxwce-vphone-ws