FAQ
Short answers about xcross - frameworks, hosts, Apple accounts, devices, CI and limits.
Which frameworks are supported?
Flutter and Compose Multiplatform. Flutter gets hot reload and IDE debugging, Compose gets a fast rebuild loop. See Compose.
Do I need a Mac or Xcode?
No. You need an Xcode.xip file once, only as the source of the iOS SDK. Xcode is never installed or run.
Why no Flutter release / AOT builds?
Flutter’s iOS gen_snapshot only runs on macOS. Debug (JIT) doesn’t need it.
Why no hot reload for Compose?
Kotlin/Native compiles ahead of time. JetBrains’ Compose Hot Reload is JVM-only. xcross gives you --watch with cached rebuilds instead.
Which iOS versions?
iOS 17+, on a physical iPhone. flutter build --target-platform simulator can produce an arm64 Simulator .app (verified on macOS ARM64), but there is no Simulator run mode.
Does WSL work?
Yes. Attach the iPhone with usbipd-win, then use it like Linux.
Does a free Apple ID work? Is it safe?
Yes, a free account works. Use a separate one anyway, just in case. Your password is never stored.
Can I run without a network?
Yes, after the first online run of an app on that device. xcross signs from the cached certificate and profile when Apple is unreachable or the session expired. XCROSS_OFFLINE=1 skips Apple entirely. See Working offline.
Why did my bundle id get an XCR- prefix?
App IDs are global, so the prefixed id never collides with another team. On the first device run xcross asks whether you want the original id instead (needed for Sign in with Apple, push, passkeys) and saves the answer as bundle_id. See CLI reference.
Does it run on ARM64 hosts?
Yes, Windows ARM64 and Linux arm64 for Flutter. Compose needs an x64 host because Kotlin/Native doesn’t publish ARM64 Windows or Linux compilers.
Where did xcross doctor and xcross clean go?
2.0 split them per framework: flutter doctor / compose doctor, and flutter clean / compose clean / sdk clean. auth clear is now auth clean.
Can I use it in CI?
Partly. Use an App Store Connect API key and -u <UDID>, and commit the bundle_id saved by your first local run. The tunnel still needs an elevated shell and a connected phone.
CocoaPods plugins?
Skipped with a warning. Use plugins that ship Package.swift.
How do I pick one of several iPhones?
-u <UDID> or -d <name>. Without them you get a picker.
Where is my config and login stored?
%APPDATA%\xcross on Windows, ~/.config/xcross on Linux.
What do I rerun after a reboot?
Only xcross tunnel. Setup, SDK and auth are one-time.
Not here? Try Troubleshooting.