DuskPort

How to Install Dusk on iOS — AltStore Sideload (Twilight Princess Guide)

Install Dusk on iPhone or iPad via AltStore. Full step-by-step based on the official docs. iOS 16+ Developer Mode, 7-day or 1-year cert tradeoffs.

Published 2026-05-10

iOS doesn’t allow apps from outside the App Store, so Dusk uses AltStore for sideloading. This guide is based on the official docs/ios-install-altstore.md from the Dusk repo, with extra context for things the official doc skips (controller pairing, save file location, the 7-day certificate tradeoff).

Time required: ~20 minutes for first setup Difficulty: Medium (more steps than Android, due to Apple’s sandboxing)

⚠️ Read This First

Two things to know before you start:

  1. Free Apple ID = 7-day app expiry. The free path requires you to refresh Dusk every week using AltStore. If you skip a week, the app stops launching until you refresh.
  2. iOS save file access is awkward. Currently tracked at #804 — accessing your save file outside Dusk (for backup, transfer to PC) is harder than on Android. Plan your save backups accordingly.

If you want to avoid weekly refreshes, a paid Apple Developer Program account ($99/year) gives you 1-year certificates instead of 7-day. Most users start with the free path; upgrade if it gets annoying.

Prerequisites (per official docs)

These are the exact requirements from docs/ios-install-altstore.md:

  • A Mac with Homebrew installed
  • Your iPhone connected via USB
  • Dusk IPA: Dusk-v1.0.0-ios-arm64.ipa from GitHub releases (~26 MB)
  • Game disc: GZ2E01 (GameCube USA) or GZ2PE01 (GameCube PAL)

The official doc lists GZ2PE01 for PAL. Note that the decomp internally uses GZ2P01 for PAL — these are the same thing (the extra E in the iOS doc may be a typo or refers to the disc header). Either way, your PAL disc dump will work if its SHA-1 matches 2601822a488eeb86fb89db16ca8f29c2c953e1ca.

Step 1 — Install AltServer on Your Mac

Per the official doc:

brew install altserver
open -a AltServer

After launching, AltServer’s icon appears in the menu bar (top right of your Mac’s screen). Keep this running for the rest of the setup.

If AltServer doesn’t appear in your menu bar, check System Settings → Login Items → make sure AltServer is allowed.

Step 2 — Enable Developer Mode on iOS (iOS 16+)

On your iPhone:

  1. Settings → Privacy & Security → Developer Mode
  2. Toggle on
  3. Restart the iPhone when prompted

Without this step, sideloaded apps won’t launch on iOS 16 or later.

Step 3 — Install AltStore on iPhone

With your iPhone plugged into your Mac via USB:

  1. Click the AltServer icon in your Mac’s menu bar
  2. Click Install AltStore → [Your iPhone]
  3. Enter your Apple ID and password when prompted (this Apple ID is what re-signs your sideloaded apps)
  4. Wait for AltStore to install on your phone

Then on the iPhone:

  1. Settings → General → VPN & Device Management
  2. Tap your Apple ID under “Developer App”
  3. Tap Trust

You should now have AltStore as an app on your home screen.

💡 Free Apple ID vs paid: If you used a free Apple ID, the sideloaded apps (including Dusk) expire after 7 days and need to be refreshed via AltStore. A paid Apple Developer Program account ($99/year) gives you 1-year certs and you can sign more apps simultaneously.

Step 4 — Transfer Files to iPhone

You need both the Dusk IPA and your GameCube disc image on the iPhone.

The official doc lists four transfer methods:

AirDrop

On your Mac, right-click each file → Share → AirDrop → pick your iPhone. Files arrive in the Files app.

iCloud Drive

Drop the files into iCloud Drive on your Mac. They sync to the Files app on iPhone.

USB transfer (Finder sidebar)

With iPhone connected, open Finder → click the iPhone in the sidebar → Files tab → drag files onto a compatible app’s section.

Cloud storage

Upload to Google Drive, Dropbox, OneDrive, etc. on your Mac. Download via the matching app on iPhone.

⚠️ Disc images are ~1 GB. AirDrop and USB transfer are fastest. iCloud / cloud uploads use bandwidth on both ends.

Step 5 — Install Dusk via AltStore

  1. Open AltStore on your iPhone
  2. Tap the My Apps tab
  3. Tap the + button (top left)
  4. The Files browser opens
  5. Navigate to where you put Dusk-v1.0.0-ios-arm64.ipa (Files app or wherever you saved it)
  6. Tap to select

AltStore will sign and install Dusk. This takes 30–60 seconds. Dusk appears on your home screen.

Step 6 — First Launch

  1. Tap Dusk on your home screen
  2. The prelaunch screen shows the button Select Disc Image
  3. Tap it. The iOS Files picker opens.
  4. Browse to where you put your GameCube disc image (Files → On My iPhone, or iCloud Drive, or wherever)
  5. Tap to select
  6. Dusk verifies the hash (XXH128 against built-in table)
  7. Status changes to “Disc ready.”
  8. Tap Play

Step 7 — Pair a Controller (Recommended)

iOS supports MFi-certified controllers and many Bluetooth gamepads:

ControllerNotes
Backbone OneiPhone-clip; works natively
Xbox Wireless (model 1914+)Native Bluetooth pairing
DualShock 4 / DualSenseNative pairing on iOS 13+
Switch Pro ControlleriOS 16+ via Bluetooth
8BitDo Pro 2Bluetooth, gyro support
Razer Kishi V2Phone clip, works as MFi

Pairing:

  1. iPhone Settings → Bluetooth → Pair
  2. Put controller in pairing mode (button combo varies by controller)
  3. Once paired, controller works automatically in Dusk

Within Dusk:

Settings → Input → Controller → Configure Controller

Gyro aim (DualShock 4/5, Switch Pro Controller, 8BitDo Pro 2):

Settings → Input → Gyro → Gyro Aim → toggle on

Save File Backup (Tricky on iOS)

This is currently the awkward part of running Dusk on iOS. The save file lives in Dusk’s app sandbox, and getting it out for backup or transfer requires extra steps. Issue #804 tracks improving this.

Current workaround (if app exposes documents folder via Files app):

  1. Files app → On My iPhone → look for Dusk folder
  2. Long-press the save file → Share → AirDrop to your Mac

If the Dusk folder isn’t visible there, the save is in the private sandbox and not user-accessible without iTunes / Finder backup workflows.

Until #804 is resolved, the safest backup approach is:

  1. Plug iPhone into Mac, open Finder
  2. Click iPhone in sidebar → General tab
  3. Click Back Up Now (with “Encrypt local backup” optional)
  4. Your Dusk save is included in the device backup

Common Issues

”Untrusted Developer” message on first launch

You skipped Step 3’s Trust action. Settings → General → VPN & Device Management → [Your Apple ID] → Trust.

Dusk won’t launch — “App is no longer available”

The 7-day cert expired. Open AltStore → My Apps → tap Refresh next to Dusk. Your Mac running AltServer must be on the same Wi-Fi network as your iPhone.

”Failed to install app” via AltStore

Common causes:

  • Free Apple ID has hit the 3-app limit (only 3 sideloaded apps allowed simultaneously). Remove others.
  • AltServer not running on Mac
  • iPhone not on same Wi-Fi as Mac
  • Apple ID 2FA challenge interrupted

Disc image not found in Files picker

The picker only shows cloud-aware folders. Make sure your disc image is in On My iPhone, iCloud Drive, or Documents — not in a cloud-only Photos library or app-private folder.

Performance lower than expected

Dusk doesn’t currently expose iOS-specific performance settings. Try:

  • Reduce Internal Resolution in Settings → Video
  • Disable Unlock Framerate if your device throttles thermally
  • Make sure Low Power Mode is off

Bluetooth controller works in other apps but not Dusk

Some controllers register as MFi vs HID differently. Try unpairing and re-pairing. Check Settings → Input → Controller → Configure Controller within Dusk to see if Dusk detects it.

Alternative Sideload Methods (Not Officially Supported)

The official docs only cover AltStore. Community alternatives:

  • SideStore — like AltStore but doesn’t require AltServer / your Mac to be running for refresh. Runs entirely on-device using a “VPN trick”.
  • Sideloadly — Windows-friendly Mac alternative.
  • TrollStore (jailbreak-only) — for older iOS versions; permanent install without re-signing. Only on certain iOS versions.

Use these at your own risk; they’re not validated by TwilitRealm. The AltStore path in the official doc is the safest.

What to Try Next

Last updated: 2026-05-10. Based on official docs/ios-install-altstore.md from the Dusk repo.

← All install guides · Pillar guide →