darwin-vm: booting Darwin to a root shell in Qemu

What darwin-vm actually boots, and who it is for

The README describes darwin-vm as a way to run a lightweight, debuggable iOS or macOS Darwin system with a custom filesystem. The kernel comes up, launchd starts, and you land in a root shell as user root within a few seconds according to the project's own sample log. That log shows a Darwin 27.0.0 kernel banner, TXM and libignition messages, and a bash-3.2 prompt running uname -v and whoami.

The audience is narrow and specific. If you have compiled a Linux kernel plus busybox and booted it with qemu -kernel and -initrd to work on kernel internals, the README says this is the same idea applied to Darwin. The listed capabilities are kernel, SPTM, TXM, dyld, launchd and userspace debugging and patching, plus compiling and running your own programs as root without a jailbreak or kernel patches.

What it is not matters just as much. The README states plainly that the screen, wifi, bluetooth, graphics, GUI apps and the full SpringBoard do not work. There is no full iPhone or Mac emulator here. Anyone hoping to test an app's UI or network behavior against a virtual device is looking at the wrong project.

The Qemu, SPTM and MIE machinery underneath

The repository layout tells most of the story. run.sh is the entry point, get_files.sh and fix_perms.sh prepare firmware, and there is a qemu-sptm entry alongside dt_fixup.py, build_tc.py and silence_logs.py. The names suggest a pipeline: fetch Apple firmware artifacts, repair permissions on the ramdisk image, patch the device tree, and boot a Qemu build that understands SPTM.

The tested configurations table maps devices to devname strings and CPU names. An iPhone 17 is iPhone18,3 with CPU t8150; an M5 Macbook Air is Mac17,4 with t8142. The README notes that SPTM-based kernels and CPUs with MIE are supported, and warns that emulating MIE can be slow, so choosing a configuration without it is a reasonable default when you do not need that feature.

The one failure in the table is informative. The M6 Mac Mini (Mac18,5, t8152) fails to boot because qemu lacks FEAT_CPA support, tracked in issue #8. That is a host-toolchain limitation, not a configuration mistake on your side, and it is the kind of detail worth checking before you pick a target.

Installing darwin-vm and getting a first root shell

Setup is split across two machines. The README requires access to a Mac with python, jq and ipsw for the firmware step, and a separate machine to build and run qemu on, which can be a different host. You do not download the IPSW yourself; you only need its URL, and the project provides a default if you do not care which version boots.

Start by installing the two command line tools the firmware step depends on:

brew install jq ipsw

Then clone the repository and run the two preparation scripts. The README warns that get_files.sh must run on a Mac, and fix_perms.sh takes the ramdisk image as its argument:

git clone https://github.com/jprx/darwin-vm.git
cd darwin-vm
./get_files.sh
./fix_perms.sh firmware/ramdisk.dmg

Once the firmware is in place, run.sh boots the VM. The README's sample output shows the kernel banner followed by a root shell, and the commands run there are ordinary Unix ones:

./run.sh
uname -v
whoami

You should see the Darwin kernel version string printed by uname -v and root printed by whoami. The README's log also shows a directory listing containing System, bin, dev, etc, private, sbin, tmp, usr, var and a series of mnt1 through mnt12 mount points, which reflects the custom filesystem the project assembles rather than a stock macOS install.

Where darwin-vm stops being the right tool

The most important limitation is stated by the project itself: no screen, no wifi, no bluetooth, no graphics, no GUI apps, no full SpringBoard. If your work depends on any of those, this project cannot help you, and no amount of configuration will change that because it is a deliberate scope decision.

The second limitation is environmental. The firmware preparation step needs a Mac with python, jq and ipsw. That is an odd requirement for a tool whose whole point is running Darwin on non-Apple hardware, and it means a pure Linux or Windows user cannot complete setup without borrowing a Mac. The README acknowledges the split by saying the qemu host can be a different machine, but it does not remove the Mac dependency for the first step.

The third is performance. The README notes that emulating MIE can be slow and suggests using a configuration without it when MIE is not needed. Combined with the M6 failure due to missing FEAT_CPA support in qemu, this means the practical envelope is smaller than the device list suggests. Check the table before assuming your target works.

How darwin-vm differs from a full iOS emulator

The obvious comparison is a full iOS simulator or emulator, and the difference is architectural rather than a matter of maturity. A simulator runs your app against Apple's frameworks on a host operating system; it gives you a window, a touch surface and a filesystem sandbox, but it does not run the Darwin kernel you are inspecting. darwin-vm does the opposite: it boots the actual kernel and drops you at a root shell, and in exchange you give up the screen entirely.

That places it closer to Qemu-based kernel development workflows than to app testing tools. The README makes this comparison directly, likening the experience to compiling Linux plus busybox and booting with -kernel and -initrd. If you have done that, the mental model transfers: you are debugging an operating system, not an application.

A second difference is the custom filesystem. The README describes a lightweight system with a custom filesystem and a root shell that comes up in seconds, and the sample listing shows mnt1 through mnt12 alongside the usual Unix directories. That is an environment built for inspection and modification, not one that mirrors a shipping device.

Maintenance, licensing and what to check before adopting

The repository is not archived and the last push was on 2026-09-15, two days before this writing, so the codebase is being touched recently. There are no releases retrieved, which means there is no tagged version to pin against; you are tracking the main branch and whatever state it is in. For a research tool that may be acceptable, but it does mean an upgrade is a git pull rather than a version bump, and you should expect the working tree to move under you.

The license is MIT, which is permissive and imposes few obligations on how you reuse or redistribute the code. That said, darwin-vm downloads and boots Apple firmware, and the README's setup section points at the ipsw tool for locating IPSW URLs. The MIT license covers this repository's code, not the Apple artifacts you fetch with it, and nothing in the README addresses the terms attached to those images. That is a question for your own legal review, not something the project resolves.

Upgrade cost is mostly the firmware step. Because get_files.sh and fix_perms.sh run on a Mac and depend on jq and ipsw, a version change means re-running that pipeline, and the tested configurations table is your guide to which device and iOS or macOS combinations are known to reach a root shell.

Editorial conclusion

Adopt darwin-vm if you want a fast-booting Darwin root shell for kernel, SPTM, TXM, dyld or launchd work and you have a Mac available for the firmware step. Do not adopt it if you need a GUI, SpringBoard, networking or anything resembling a usable iPhone or Mac desktop; the README rules that out. Before committing, verify that your target device and CPU combination appears as a checkmark in the tested configurations table, and confirm your host can build qemu with the SPTM and MIE support the project's qemu-sptm entry implies.

Frequently asked questions

Official sources

1. Issues
2. jprx/darwin-vm on GitHub
3. License: MIT
4. README