# Provenance: a multi-system emulator frontend for iPhone, iPad and Apple TV

> Provenance bundles dozens of emulator cores behind one iOS and tvOS app, installable from the App Store, AltStore or a released IPA. The README states the scope; the wiki holds the setup detail, and the repository is where the build cost lives.

**Provenance-Emu/Provenance** — iOS & tvOS multi-emulator frontend, supporting various Atari, Bandai, NEC, Nintendo, Sega, SNK and Sony console systems… Get Started:  https://wiki.provenance-emu.com  | 

- Repository: https://github.com/Provenance-Emu/Provenance
- Website: https://provenance-emu.com
- Stars: 6,383 · Forks: 707
- Language: C
- License: NOASSERTION
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/provenance-emu-provenance

## The problem Provenance solves for Apple device owners

Running a single console emulator on iOS or tvOS is a solved problem. Running a dozen of them is not, because each one arrives as its own app with its own library, its own save handling and its own controller mapping. Provenance takes the other route: one frontend that loads multiple emulator cores, so the ROM library, the box art, the save states and the controller configuration live in one place. The README describes it as an "iOS & tvOS multi-emulator frontend" and lists the supported families as Atari, Bandai, NEC, Nintendo, Sega, SNK and Sony console systems.

The audience is narrower than "retro gaming". It is people who already own Apple hardware and want emulation on it without jailbreaking. The README states the app requires no jailbreak, and the App Store badge is the first install option shown. A second audience is Apple TV owners: the project ships a native tvOS app with its own interface, and the README notes that iCloud sync is free on Apple TV while it sits behind Provenance Plus elsewhere. If you game on a desktop and never touch an iPhone or an Apple TV, this project is not aimed at you.

## How the frontend, cores and library fit together

The repository layout makes the architecture legible. There is a frontend layer (PVLibrary, PVUI-adjacent targets, PVAppIntents, PVHelp), a core abstraction layer (PVEmulatorCore, PVCoreBridge, PVCoreObjCBridge, PVCoreLoader, PVCoreAudio), and two directories of actual cores: Cores/ and CoresRetro/. That split matters. Cores under CoresRetro/ are RetroArch-derived cores, and the README treats them as a distinct population: cheat codes are described as working on "12+ native cores and all RetroArch cores", and the v3.3.0 notes mention "Unified Video Filters" applying Metal shaders "across native and RetroArch cores". So the two core families are not interchangeable in feature coverage, even though the user sees one library.

Around that sit supporting modules with self-explanatory names: PVCheevos for RetroAchievements, PVHashing for ROM identification, PVJIT for just-in-time compilation, PVArchiving for archive handling, PVAudio and PVCoreAudio for sound. Metadata comes from OpenVGDB, which the README credits for automatic box art, descriptions and genre data. The data flow is therefore: import a ROM, hash it, look it up in the local metadata database, attach artwork, then hand execution to whichever core claims the file type. The README also mentions "Flexible Importing" with WebDAV among the options, though the quoted text is cut off at that point, so the full import surface is not documented in the README body.

## Installing Provenance on iPhone and running a first game

The README offers three install paths and no build instructions for end users. The App Store badge points at apps.apple.com/us/app/provenance-app/id1596862805. The AltStore badge is a deep link, and the third badge downloads the latest IPA from GitHub releases. If you already use AltStore, adding the source URL is the least manual option:

```bash
altstore://source?url=https://provenance-emu.com/apps.json
```

That link registers the Provenance source with AltStore, after which the app appears as an installable entry. If you prefer the IPA route, the badge targets the latest GitHub release, and the releases list shows tags such as 3.3.1 and an alpha build; the alpha is dated later than the stable tag, so treat it as a separate channel rather than an update to 3.3.1.

For a first run, the README does not walk through importing a ROM. What it does state is that importing is flexible and that metadata arrives automatically via OpenVGDB. The practical sequence implied by the feature list is: install the app, add a ROM through the importer, let the hashing and metadata step attach artwork, then start the game from the library. BIOS files are mentioned only in the iCloud sync context ("ROMs, saves, BIOS, and artwork sync across all devices via CloudKit"), which means the README acknowledges BIOS files exist without explaining which cores need them. The project's own pointer for that is the wiki at wiki.provenance-emu.com, linked under Get Started.

Building from source is a different undertaking. The repository carries Build.xcconfig plus Build-iOS.xcconfig, Build-tvOS.xcconfig and Build-watchOS.xcconfig, a Makefile, a Gemfile, a CodeSigning.xcconfig.sample, and a .env.sample that documents App Store Connect keys, signing certificate material and GitHub tokens. The Makefile's own comment explains the secret handling: .env is gitignored, .env.sample documents every key, and when .env holds op:// references the release path runs under op run so values resolve into the child process only. None of that is needed to install the app, but it is the shape of the work if you want to ship your own build.

## Where Provenance is the wrong tool

The README's own claim is platform-bound: iOS, tvOS and macOS. If your emulation happens on Windows or Linux, nothing here applies, and the install instructions are Apple-specific by construction. Even inside Apple hardware there is a floor: the badges specify iOS 16+, tvOS 16+ and macOS 13+, so older devices are out.

The second limitation is documentation depth. The README is a feature showcase, not a manual. It lists capabilities (cheat codes, save states, fast forward, video filters, RetroAchievements) without stating per-core support beyond the "12+ native cores" figure for cheats. It mentions BIOS files only in passing. It does not document rollback, and it does not document what happens to your library when iCloud sync is enabled versus disabled. The wiki is where that detail is supposed to live, and the README links to it rather than reproducing it.

The third is the licence. The repository's licence field reads NOASSERTION, and the top-level tree contains both LICENSE.md and LICENSES.md. That second file is a strong hint that bundled components carry their own terms, which is typical for an emulator that vendors third-party cores. Anyone redistributing a build, or shipping it inside another product, needs to read both files rather than assume a single licence covers the tree. Nothing in the README resolves this.

## How Provenance differs from RetroArch and from single-system apps

The obvious comparison is RetroArch, and the repository itself points at the relationship: CoresRetro/ holds RetroArch cores, and the README lists "RetroArch shader support" alongside the native Metal filters. So Provenance is not a RetroArch competitor at the core level; it consumes RetroArch cores where it does not have a native one. The difference is the shell. RetroArch is a cross-platform frontend that runs on many operating systems with a configuration-file-driven interface. Provenance is an Apple-only frontend with a native iOS and tvOS UI, an App Store listing, and Apple-specific plumbing such as PVAppIntents, PVLiveActivities and CloudKit sync. If you want one setup that moves between a Windows desktop and an iPhone, RetroArch is the closer fit. If you want the iPhone experience to feel like an iPhone app, Provenance is built for exactly that.

The second comparison is against single-system emulators. A dedicated app for one console usually ships with everything that console needs, including BIOS handling and per-game quirks, and its documentation is about one machine. Provenance trades that depth for breadth: one library, one controller setup, one place for saves, across the systems listed in the README. The cost is that per-system edge cases are now the frontend's problem, and the README's per-core notes (Mupen64Plus, Dolphin, DuckStation, PicoDrive, FCEUmm, Mednafen fixes in v3.3.0) show that this is where ongoing work goes.

## Maintenance, release cadence and what upgrades cost you

The repository is not archived, and the last push was on 2026-09-21, one day before this writing, so the develop branch is moving. The release list shows a stable 3.3.0 tagged 2026-03-14 with iCloud Sync, a new tvOS UI and video filters, a 3.3.1 alpha on 2026-03-30, and a separate alpha build dated 2026-09-16. That pattern says two things. First, the project ships. Second, the alpha channel is genuinely separate from the stable tag, and the README's own install badges do not distinguish between them, so a badge click can land you on an alpha IPA if that is what the latest release is.

Upgrade cost for a user is low: the App Store path updates like any app, and AltStore re-signs on its own schedule. The interesting cost is on the contributor side. The Makefile exposes a large surface (generate-all, generate-licenses, generate-uti, test-spm, test-cheatdb, test-scripts, lint, audit-localization, spm-validate, testflight targets), which tells you the project expects changes to be validated through generated artifacts, not just compiled. The .env.sample documents the secrets needed for a signed release, and the Makefile notes that GitHub secrets are write-only, with .env as the local source of truth and 1Password as the backup. Forking and shipping your own signed build therefore means owning an App Store Connect key, a distribution certificate and the corresponding passwords.

On licensing, the honest statement is that the repository does not present a single clear licence in the metadata. LICENSE.md and LICENSES.md both exist. If you plan to redistribute, read both, and treat the NOASSERTION field as a signal that the answer is not in the repository header.

## Conclusion

Adopt Provenance if you want one Apple-platform app covering many console systems and you are willing to read the wiki rather than the README for setup and BIOS requirements. Do not adopt it if you need a self-contained desktop emulator, a documented license you can quote from the repository alone, or a build you can reproduce without an Apple toolchain. Before installing, verify that the systems you care about are listed under Systems supported, and check the release notes for the version you intend to run.

## FAQ

### How do I install Provenance on an iPhone?

The README lists three routes: the App Store listing at apps.apple.com/us/app/provenance-app/id1596862805, an AltStore source URL, or the latest IPA from GitHub releases. The AltStore source link registers Provenance as a source you can install from.

### How do I set up the Provenance emulator?

The README does not give a setup walkthrough; it points to the wiki at wiki.provenance-emu.com under Get Started. What the README does state is that importing is flexible and that box art, descriptions and genre data arrive automatically via OpenVGDB.

### How do I use the Provenance emulator on iOS?

Install it from the App Store, AltStore or an IPA, then import a ROM into the library and launch it from there. The README mentions WebDAV among the import options, but the quoted feature text is truncated, so the full import surface is not documented in the README body.

### Does the Provenance emulator support 3DS games?

The README's system list includes 3DS alongside NES, SNES, N64, GameCube, Game Boy, GBA, DS, PlayStation, PSP, Saturn, Dreamcast, Atari and Neo Geo. It does not state per-system core requirements or performance expectations.

### How do I use the Provenance emulator?

Install it on an Apple device, add a ROM through the importer, and start it from the library; the README says metadata such as box art and genre data is fetched automatically via OpenVGDB. Detailed setup lives on the project wiki rather than in the README.

## Sources

- [Issues](https://github.com/Provenance-Emu/Provenance/issues)
- [Project website](https://provenance-emu.com)
- [Provenance-Emu/Provenance on GitHub](https://github.com/Provenance-Emu/Provenance)
- [README](https://github.com/Provenance-Emu/Provenance/blob/develop/README.md)
- [Releases](https://github.com/Provenance-Emu/Provenance/releases)

---

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