Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Sideloading

Easy. Install pre-built releases (or pre-releases).

Prebuilt .ipa releases can be sideloaded onto your devices and must be re-signed using your own developer profile(s).

Download Provenance

  1. First, download a Release or Prerelease of Provenance (unless using AltStore, direct source download link in AltStore instructions).

  2. Choose a sideloading method:

Sideloading Options:

Requirements

  • Free Apple Developer account (at a minimum) or a paid account.

    🛑 DO NOT enroll to join the full Developer Program or you will be locked into a Pending payment state, unable to code-sign unless you pay or contact Apple to cancel the enrollment.

  • Connections:

    • iPhone / iPad: Lightning → USB-A / USB-C cable¹

    • Apple TV 4: USB-C → USB-A / USB-C cable¹

    • Apple TV 4K: WiFi² (Instructions)³

¹ Depends on which ports you have. WiFi can be setup after. ² USB ports have been discontinued on Apple TV 4K+. ³ If using a virtual machine, you may need to configure your network settings.

Sideloading from 3rd party sources is not supported.

💢 If you get stuck, check out Troubleshooting.

AltStore source is available at this link — click in Mobile Safari once you have AltStore installed.

  1. Download and launch AltStore.

  2. Connect your device (you may need to open Finder and choose Trust… when it pops up).

  3. Follow instructions via altstore.io and the app as it guides you.

  4. Put the Provenance .ipa in your iCloud Drive somewhere and install via AltStore app by using the + button in the upper left of the My Apps screen.

Free Apple developer provisioning expires every 7 days, but AltStore can keep track of and handle renewal for you. Re-sideloading will not cause you to lose any data.

Windows AltStore has not been tested by the Provenance team. Support may be limited.

💢 Troubleshooting

Cannot authenticate

If using 2-Factor Authentication, you will need to go to Apple ID settings and generate an App-Specific Password. Enter it verbatim in your sideloading tool.

Unable to code-sign / install

  • If you are using a free Apple developer account, you can only install a total of 3 apps per Apple ID at a time. Delete some apps you are signing, or install with a different Apple ID and Bundle IDs.

  • If you used to have a free Safari Developer Account (no longer supported by Apple):

    1. Upgrade to a paid Apple Developer account, or

    2. Use a different Apple ID that is not an expired and deprecated Safari Developer account.

—application-identifier entitlement does not match…

This means you need to match the Bundle IDs with the ones from your previous sideload or build on your device. If you don't know it, or used a 3rd party web-sign (unsupported), we recommend you backup your files, delete the app and try to clean-install.

Your maximum App ID limit has been reached…

You have made too many Bundle IDs (App IDs) in one week on a free Apple developer account. Stop making new Bundle IDs and revert to one you already made. If all else fails, use a different Apple ID, and make only one new, unique Bundle ID with it (and save it for later when you need to re-sign in 7 days).

Duplicate app

If app installs or updates as a duplicate instead of updating existing installation, you need to delete it and use the same Bundle ID as your original build or you'll end up with a double installation.

App installs but crashes immediately on launch

This is the most common issue with Sideloadly, LiveContainer, ATVLoadly, and Raspberry Pi-based signing tools. The app appears to install fine but quits to the home screen within 1–2 seconds of opening.

Most likely cause: entitlement stripping

When third-party tools re-sign the IPA, they sometimes strip or fail to re-inject entitlements that Provenance requires (Metal GPU access, game controller support, background audio, JIT, etc.). iOS and tvOS silently kill the app the moment it tries to use a capability it's not entitled to.

What to try, in order:

  1. Check the crash log first — see the Reading Crash Logs section below. The crash reason tells you exactly what failed.

  2. Try a different signing tool — if ATVLoadly or Sideloadly crashed it, try AltStore instead (or vice versa). Different tools handle entitlement injection differently.

  3. Use a paid Apple Developer account ($99/year) — free accounts have restrictions on which entitlements can be granted. Some capabilities (like certain background modes) are blocked entirely on free accounts.

  4. Re-download the IPA — a partially downloaded or corrupt IPA can produce a valid-looking install that crashes. Delete and re-download from GitHub Releases.

  5. Delete the app fully and reinstall — stale data from a previous install with a different bundle ID can cause conflicts.

Tool-specific notes:

Tool
Common cause
Workaround

Sideloadly

May strip some entitlements by default

Enable "Advanced Options → Remove Support Files" = OFF; try "Normal" signing mode

LiveContainer

No JIT support; Metal access restricted in container sandbox

LiveContainer is not officially supported — use AltStore instead

ATVLoadly / Raspberry Pi

Community tool; entitlement handling is inconsistent

Update to latest ATVLoadly; check the ATVLoadly GitHub for known issues

AltStore (free)

Free account entitlement limits

Works best; use the official Provenance AltStore source

LiveContainer runs apps in a sandboxed container without installing them. Provenance uses Metal for rendering and requires real GPU access. LiveContainer's sandboxing actively interferes with this and is not supported. Install Provenance normally via AltStore instead.

📋 Reading Crash Logs

When Provenance crashes on launch, the device records exactly why. Finding that log tells you (and us) precisely what went wrong — this is far more useful than "it just crashes."

macOS — Console.app (easiest)

  1. Connect your iPhone/iPad or Apple TV via USB (or WiFi for Apple TV 4K)

  2. Open Console.app (in /Applications/Utilities/)

  3. Select your device in the left sidebar under Devices

  4. In the search bar, type Provenance and press Enter

  5. Launch Provenance on the device — watch the log fill in real time

  6. Look for lines marked fault or error, especially around process termination

To save the log: File → Export or select all and copy.

For crash reports specifically: in Console.app, go to Crash Reports in the left sidebar, find Provenance entries, and open them. They contain the full stack trace.

macOS — Xcode

  1. Connect your device

  2. Open Xcode → Window → Devices and Simulators

  3. Select your device → click View Device Logs

  4. Filter by Provenance in the search box

  5. The most recent crash will be at the top

You can also stream live logs: in Terminal, run:

(Replace My iPhone with your device name as shown in Finder.)

Windows — Apple Devices App + libimobiledevice

There is no Windows equivalent of Console.app, but you can get logs via:

Option A — iMazing (paid, easiest on Windows)

  • Install iMazing and connect your device

  • Go to Manage Apps → Provenance → Logs

Option B — libimobiledevice (free, command line)

  1. Install libimobiledevice for Windows or use the binaries at libimobiledevice.org

  2. Connect device, trust the computer when prompted

  3. Run in Command Prompt:

  4. Launch Provenance and watch the output

Option C — 3uTools (free GUI)

  • Install 3uTools, connect device

  • Go to Toolbox → Real-time Log and filter by Provenance

Linux — libimobiledevice

Connect your device via USB and trust the computer first (idevicepair pair).

On-Device — Settings Analytics (no computer needed)

iOS saves crash reports locally:

  1. Settings → Privacy & Security → Analytics & Improvements

  2. Tap Analytics Data

  3. Look for files starting with Provenance- — sort by date, the most recent crash is at the top

  4. Tap to open — scroll to the Exception Type and Termination Reason lines near the top

The key fields to share when asking for help:

  • Exception Type (e.g., EXC_CRASH, EXC_BAD_ACCESS)

  • Termination Reason (e.g., Namespace CODESIGNING, Code 0x1 = entitlement issue)

  • Application Specific Information

Apple TV — Reading Logs 🍎📺

Apple TV has no touchscreen and no USB port on the 4K models, so this is trickier.

Method 1: Mac Console.app over WiFi (recommended)

  1. On Apple TV: Settings → Remotes and Devices → Remote App and Devices — make sure your Mac appears

  2. On Mac: Open Xcode → Window → Devices and Simulators, wait for your Apple TV to appear (may take a moment on WiFi)

  3. Once it appears in Xcode, it will also show up in Console.app under Devices

  4. In Console.app, select the Apple TV and filter by Provenance

  5. Launch Provenance on the Apple TV — the crash reason appears in real time

Method 2: Xcode Device Logs over WiFi

  1. Xcode → Window → Devices and Simulators → select Apple TV

  2. Click View Device Logs

  3. Recent crashes appear here within a few seconds of happening

Method 3: Apple TV 4 (USB-C only) — direct cable

The original Apple TV 4 has a USB-C port. Connect it to your Mac and it shows up in Console.app and Xcode the same as an iPhone.

Method 4: Pair via ideviceinstaller (ATVLoadly users)

If you set up ATVLoadly, your Raspberry Pi is already paired. You can stream logs from the Pi:

Apple TV 4K (2nd gen+) has no physical port. You must use WiFi pairing via Xcode or Console.app. If Xcode hasn't paired with your Apple TV before, go to Xcode → Preferences → Accounts and add your Apple ID first.

🔗 External Resources

If you're still stuck, these guides cover sideloading in depth:

Sideloading tools:

Crash log reading:

Community help:

🗯 If you are still stuck ask for help on our Discord.

PreviousAlternative Installation MethodsNextBuilding from Source

Last updated