Who Madeira is for#
iOS developers studying Wine and FEX-Emu on Apple silicon
Madeira exposes the iOS-specific patches to Wine, FEX-Emu, and DXMT through its GPL-3.0 forks. Developers researching Windows binary compatibility on ARM64 iOS can study the single-process Mach architecture, the ARM64EC Wine integration, and the D3D11-to-Metal translation layer as a working reference implementation.
Skip if:
Skip if you need a stable API or documented integration surface. This is a research project with expected breaking changes and no formal developer documentation beyond the README.
Gamers with an A15 iPhone who want to try supported titles
If you have an iPhone 13 Pro or similar A15 device, a Mac with Xcode, and want to play Thumper or ULTRAKILL on it, Madeira provides the only known open source path. The weekly reinstall overhead is manageable if you are comfortable with command-line tools and already have a Mac development environment.
Skip if:
Skip if you want to run a broad catalog of Windows games, need turnkey installation, or cannot build from source. Confirmed compatible titles are limited to a small number as of the current README.
The problem it solves#
Running Windows PC games on an iPhone has been effectively impossible without a jailbreak. iPhones run ARM64 and have no native support for x86-64 Windows binaries or DirectX APIs. The App Store prohibits JIT-compiled code, which Wine and similar compatibility layers require to function, so no commercial product has appeared through normal distribution channels.
The practical result for iOS users who want to run PC games is a forced choice: jailbreak the device, losing warranty coverage and security update compatibility, or go without. The App Store offers no compatibility layer, no paid commercial option targets iOS for Windows gaming, and the sideloading process has historically been complex enough to block most users from attempting it.
How it solves it#
x86-64 to ARM64 Translation via FEX-Emu
Madeira uses FEX-Emu to translate x86-64 Windows instructions to ARM64 at runtime. This allows PC game binaries compiled for x86-64 processors to execute on Apple's ARM-based iOS hardware without any changes to the game itself. The project uses a fork of FEX-Emu with iOS-specific patches; the original MIT-licensed FEX-Emu code remains available under MIT, and the modifications are GPL-3.0.
Direct3D 11 to Metal via DXMT
DXMT converts Direct3D 11 API calls to Metal, Apple's native GPU API on iOS and macOS. This lets Windows games that rely on D3D11 for rendering produce actual frames on iOS hardware. Madeira uses a fork of DXMT with iOS-specific modifications under GPL-3.0; the upstream MIT-licensed DXMT code remains under MIT.
No-Jailbreak Sideload Design
Madeira runs on a stock, non-jailbroken iPhone using JIT enabled via StikDebug and sideloading with an Apple ID for signing. A free Apple ID works for this, though provisioning profiles expire every seven days, requiring a weekly rebuild and reinstall cycle. The app container survives reinstall, so prefixes and game saves are preserved between rebuilds.
Wine ARM64EC with Wineserver as a Thread
Madeira forks Wine to run in ARM64EC mode and runs wineserver as a thread within the same Mach process rather than as a separate OS process. This reduces inter-process overhead and is part of what makes the approach viable within iOS's constrained process model. The Wine fork is relicensed to GPL-3.0 under the LGPL-2.1 §3 upgrade clause.
GPL-3.0 Source with Per-Fork License Transparency
The project and its forks of Wine, FEX-Emu, DXMT, and rpmalloc each carry a LICENSE-MADEIRA.md file documenting exactly which license terms apply to the modified code versus the upstream code. Upstream MIT code in FEX-Emu and DXMT remains under MIT for anything obtained before the fork. Distributed derivatives must remain GPL-3.0.
Strengths and trade-offs#
Strengths
- Only Known Open Source iOS Path for Windows GamesMadeira is the only open source project attempting to run x86-64 Windows PC games on a non-jailbroken iPhone. No commercial product covers this use case, and no App Store distribution path exists. For anyone exploring this space, it is the only starting point currently available.
- No Jailbreak RequiredThe combination of sideloading and JIT via StikDebug achieves Windows game execution without voiding device warranties or breaking compatibility with iOS security updates. Users retain a stock, updateable iPhone while experimenting with the compatibility layer.
- Transparent GPL-3.0 Licensing with Explicit Fork TermsEvery fork carries a LICENSE-MADEIRA.md that documents exactly which terms apply to the modified code versus the upstream code. You can run it, study it, modify it, and distribute it, provided derivatives remain GPL-3.0. Upstream MIT and 0BSD code in the forks retains its original terms.
- Active Development Since March 2026The repo was created in March 2026, has 816 stars and 152 forks, and had its last push on 2026-09-25. With 25 open issues and active commit history, the project is under ongoing development rather than stalled.
Trade-offs
- -Research Project Status with Breaking Changes ExpectedThe README explicitly states this is a research project, not a product. Breaking changes are expected between versions, each game has per-title quirks, and some titles reach gameplay only at low frame rates. Users should not expect the stability of a finished tool. Thumper and ULTRAKILL are confirmed playable; most other titles are not.
- -Weekly Reinstall Required with Free Apple IDFree Apple ID provisioning profiles expire every seven days. The app must be rebuilt from source and reinstalled weekly. This requires a Mac with Xcode and the full build environment. The app container survives reinstall and preserves saves, but the rebuild cycle is an ongoing maintenance burden.
- -Complex Multi-Component Build ProcessBuilding Madeira requires cloning with --recurse-submodules, running separate build scripts for the unix-side Wine libraries, ARM64EC PE modules, FEX, and DXMT components, then building the iOS app with xcodebuild. There is no binary release. Every install starts from source.
- -Narrow Confirmed Game CompatibilityAs of the README, only Thumper and ULTRAKILL are confirmed playable. Marvel Cosmic Invasion has reached gameplay but experienced unexplained terminations and unreliable controls. Other games reach gameplay at low frame rates. This is not a general-purpose compatibility layer for a broad Windows game library.
Madeira vs alternatives#
Madeira vs CrossOver
Both Madeira and CrossOver use Wine to run Windows software, but they target different platforms and have very different maturity levels.
| Feature | Madeira | CrossOver |
|---|---|---|
| License | GPL-3.0 | Proprietary |
| Platform | iOS (non-jailbroken iPhone) | macOS, Linux |
| iOS support | Yes | No |
| Install method | Sideload from source | App installer |
| App Store distribution | No | Yes (macOS) |
| Cost | Free | Paid |
| Status | Research project | Mature commercial product |
CrossOver is the better choice when you need to run Windows software on macOS or Linux with broad application compatibility and a polished interface. CodeWeavers maintains a compatibility database covering a wide range of Windows applications, provides commercial support, and ships a standard installer. For macOS users who need Windows business software or a broader game catalog, CrossOver is a finished product.
Madeira is the better choice for iPhone users. CrossOver does not support iOS at all, so anyone who wants to run Windows x86-64 games on a non-jailbroken iPhone has no paid commercial option: Madeira is currently the only open source path. The tradeoff is a complex build process, a narrow set of confirmed playable titles, a weekly reinstall cycle, and research-project stability rather than CrossOver's polished desktop experience.
The GPL-3.0 license means Madeira's source code and its iOS-specific Wine patches are available for study and modification. CrossOver's source is proprietary. Developers building on Madeira must keep distributed derivatives under GPL-3.0.
Quick start#
Setup requires cloning with submodules, running per-component build scripts, and building the iOS app with xcodebuild.
```bash
git clone --recurse-submodules https://github.com/willfaust/Madeira
```What it's built on#
- Languages
- CObjective-CObjective-C++PythonSwift
FAQ#
Does Madeira require a jailbroken iPhone?
No. Madeira runs on a stock, non-jailbroken iPhone. It uses JIT enabled via StikDebug and sideloading to install without a jailbreak. Because JIT requires a debugger attach, it cannot be distributed through the App Store, but the device itself does not need to be jailbroken.
Can I download Madeira from the App Store?
No. Apple prohibits JIT-compiled code from App Store distribution, and Wine-style compatibility layers cannot be submitted. Madeira is installed by sideloading using an Apple ID for signing. Free accounts work but require rebuilding and reinstalling the app every seven days when the provisioning profile expires.
What games run on Madeira?
As of the current README, Thumper and ULTRAKILL are confirmed playable. Marvel Cosmic Invasion has reached gameplay but experienced unexplained terminations and unreliable controls. Other games reach gameplay at low frame rates. The project describes itself as a research project rather than a finished compatibility layer, and per-title quirks are expected.
What hardware does Madeira require?
Development has been on an iPhone 13 Pro with an A15 chip. A Mac with Xcode is required to build and sideload the app. JIT is enabled through StikDebug. The app has not been formally tested on other devices. The Microsoft Visual C++ runtime DLLs are not included and must be supplied separately.
What license does Madeira use, and can I modify and distribute it?
Madeira is licensed under GPL-3.0-or-later. You can run it, study it, modify it, and distribute modified versions, provided that distributed derivatives remain under GPL-3.0. Each fork (Wine, FEX-Emu, DXMT, rpmalloc) carries a LICENSE-MADEIRA.md documenting the exact terms for modified code. Upstream MIT and 0BSD code in the forks retains its original terms for anything obtained before the fork.
Similar open-source tools#
mobile-mcp
MCP server that gives AI agents hands on iOS and Android devices
escrcpy
Graphical Android device mirroring and control with scrcpy
Reasonix
Open-source AI coding agent you can leave running locally.
Aider
Git-native terminal coding agent for multi-file edits and clean diffs
Omnara
Open-source agent deployment API. Self-host or use Omnara Cloud.
rakazo
AI teammates you own: your keys, your model, your machine.