/iblai-build
Build and run your ibl.ai app on desktop and mobile using Tauri v2. Covers iOS, Android, macOS/Linux desktop, and Surface tablet builds.
Before adding build support or running a dev build, stop all running dev servers (pnpm dev, next dev, etc.) to avoid port conflicts. Kill any process on port 3000 before proceeding.
When the user asks to add iOS or Android build support, automatically start the emulator/simulator after initialization -- just like you would start pnpm dev after adding auth. Run iblai builds device to find the available device name, then start the dev build with that device.
Do NOT guess device names. Always run iblai builds device first and use a device name from the output.
Prerequisites (All Platforms)
- Tauri support added to your project:
iblai add builds pnpm install - Rust toolchain installed via rustup
How Dev Builds Work
All platforms (desktop and mobile) use a static next build export. The CLI runs the frontend build automatically before starting the Tauri dev server -- there is no separate devUrl or beforeDevCommand. The Tauri WebView loads the static files from ../out on all platforms.
For dev builds, you can optionally deploy to Vercel using iblai deploy vercel (see /iblai-deploy). This deploys out/ and automatically updates devUrl in tauri.conf.json.
Mobile Safe Area
The generated CSS includes padding: env(safe-area-inset-*) on <body> and the layout sets viewport-fit=cover. This prevents content from overlapping with the iOS status bar / notch and Android status bar. If you see content behind the status bar, verify:
globals.css(oriblai-styles.css) haspadding-top: env(safe-area-inset-top)on bodyapp/layout.tsxmetadata includesviewport: "width=device-width, initial-scale=1, viewport-fit=cover"
Mobile SSO
For mobile builds (iOS/Android), the auth redirect must use a custom URI scheme instead of https://. Set TAURI_CUSTOM_SCHEME in iblai.env:
TAURI_CUSTOM_SCHEME=myappThis configures:
NEXT_PUBLIC_TAURI_CUSTOM_SCHEMEin.env.local— the frontend uses this to passredirect-to=myapp://to the auth SPA- The Tauri deep-link handler to listen for
myapp://callbacks
Without this, mobile SSO will redirect to an HTTPS URL that stays inside the system browser session and never returns to the app.
App Icons
Generate platform-ready icons from your logo (works for all platforms):
iblai builds iconography path/to/logo.pngThis creates all required sizes in src-tauri/icons/.
List Available Devices
iblai builds deviceiOS
Build and run on iOS Simulator and real devices.
iOS Prerequisites
- macOS (iOS builds require Xcode)
- Xcode installed from the Mac App Store (includes iOS SDK + Simulator)
- Xcode Command Line Tools:
xcode-select --install - Rust iOS targets:
rustup target add aarch64-apple-ios aarch64-apple-ios-sim
Initialize iOS Project
Run this once after adding Tauri support:
iblai builds ios initThis generates src-tauri/gen/apple/ with the Xcode project, Swift bridge code, and iOS configuration.
If you get a Rust target error, make sure both targets are installed: rustup target add aarch64-apple-ios aarch64-apple-ios-simRun on iOS Simulator
First, list available simulators:
iblai builds deviceAlways pick a device from the list. Choose the most mainstream iPhone (e.g., the newest Pro Max available). Do NOT run without a device name.
If VERCEL_TOKEN is set in iblai.env, deploy the frontend first:
iblai deploy vercelThen start the dev build:
iblai builds ios dev "iPhone 16 Pro Max"The first build takes several minutes; subsequent builds are fast.
Troubleshooting Simulator
- "No available iOS simulators": Open Xcode > Settings > Platforms > download an iOS runtime
- Build fails with "linking" errors: Verify Xcode path with
xcode-select -p. If incorrect, the user should runsudo xcode-select -s /Applications/Xcode.app/Contents/Developerthemselves (requires elevated privileges -- confirm with the user before suggesting this) - Simulator won't launch: Try
xcrun simctl shutdown allthen retry
Run on Physical iOS Device
Connect your iPhone via USB, then:
iblai builds ios dev --deviceRequirements for Physical Devices
- Apple Developer account (free or paid)
- Device registered in your Apple Developer portal
- Development provisioning profile configured in Xcode
To set up signing:
- Open
src-tauri/gen/apple/<app>.xcodeprojin Xcode - Select the target > Signing & Capabilities
- Set your Team and Bundle Identifier
- Xcode auto-manages provisioning profiles
Free developer accounts can run on up to 3 devices for 7 days. A paid Apple Developer Program ($99/year) removes this restriction.
Build Release.ipa
Local Build
iblai builds ios buildOr:
pnpm tauri:build:iosThe.ipa file is generated at src-tauri/gen/apple/build/ (or use find src-tauri/gen/apple -name "*.ipa" to locate it).
App Store Build (CI)
Generate the GitHub Actions workflow:
iblai builds ci-workflow --iosThis creates .github/workflows/tauri-build-ios.yml which sets up the full pipeline and uploads the.ipa as a build artifact.
Required GitHub Secrets for iOS CI
| Secret | Description |
|---|---|
APPLE_API_KEY_BASE64 | Base64-encoded App Store Connect API key (.p8 file) |
APPLE_API_KEY_ID | Key ID from App Store Connect > Users and Access > Keys |
APPLE_API_ISSUER | Issuer ID from App Store Connect > Users and Access > Keys |
To encode your.p8 key:
base64 -i AuthKey_XXXXXXXXXX.p8 | pbcopyAndroid
Build and run on Android emulators and real devices.
Android Prerequisites
- Android Studio with SDK and NDK installed
- Android SDK (API level 24+)
- Rust Android targets:
rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android
Initialize Android Project
iblai builds android initThis generates src-tauri/gen/android/ with the Gradle project.
Run on Android Emulator
First, list available emulators:
iblai builds deviceAlways pick a device from the list. Choose the most mainstream Pixel (e.g., "Pixel_9", "Pixel_8" — whichever is the newest in the list). Do NOT run without a device name.
If VERCEL_TOKEN is set in iblai.env, deploy the frontend first:
iblai deploy vercelThen start the dev build:
iblai builds android dev "Pixel_9"Run on Physical Android Device
Connect your device via USB with USB debugging enabled, then:
iblai builds android dev --deviceBuild Release APK
iblai builds android buildOr:
pnpm tauri:build:androidAndroid CI
iblai builds ci-workflow --androidmacOS (Desktop)
macOS Prerequisites
- Xcode Command Line Tools:
xcode-select --install
Run in Dev Mode
If VERCEL_TOKEN is set in iblai.env, deploy the frontend first:
iblai deploy vercelThen start the dev build:
iblai builds devBuild Release.dmg /.app
iblai builds buildOr:
pnpm tauri:buildmacOS CI
iblai builds ci-workflow --macSurface
Build for Microsoft Surface tablets running Windows.
Surface Prerequisites
- Visual Studio Build Tools with C++ workload
- WebView2 runtime (included on Windows 11, downloadable for Windows 10)
Run in Dev Mode
If VERCEL_TOKEN is set in iblai.env, deploy the frontend first:
iblai deploy vercelThen start the dev build:
iblai builds devBuild Release.msi /.exe
iblai builds buildThe installer targets are configured in src-tauri/tauri.conf.json under bundle.targets (includes nsis and msi by default).
Surface CI
iblai builds ci-workflow --windowsLinux (Desktop)
Linux Prerequisites
- System dependencies (Debian/Ubuntu):
sudo apt install libwebkit2gtk-4.1-dev build-essential libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev
Run in Dev Mode
iblai builds devBuild Release.deb /.AppImage
iblai builds buildLinux CI
iblai builds ci-workflow --linuxAll Platforms CI
Generate CI workflows for all platforms at once:
iblai builds ci-workflow --allSummary of Commands
| Task | Command |
|---|---|
| Add Tauri support | iblai add builds |
| Generate app icons | iblai builds iconography logo.png |
| List available devices | iblai builds device |
| iOS | |
| Initialize iOS project | iblai builds ios init |
| Run on iOS Simulator | iblai builds ios dev "iPhone 16 Pro Max" |
| Run on physical iPhone | iblai builds ios dev --device |
| Build release.ipa | iblai builds ios build |
| iOS CI workflow | iblai builds ci-workflow --ios |
| Android | |
| Initialize Android project | iblai builds android init |
| Run on Android emulator | iblai builds android dev "Pixel_9" |
| Run on physical Android | iblai builds android dev --device |
| Build release APK | iblai builds android build |
| Android CI workflow | iblai builds ci-workflow --android |
| Desktop | |
| Run desktop dev mode | iblai builds dev |
| Build desktop release | iblai builds build |
| macOS CI workflow | iblai builds ci-workflow --mac |
| Surface CI workflow | iblai builds ci-workflow --windows |
| Linux CI workflow | iblai builds ci-workflow --linux |
| All CI workflows | iblai builds ci-workflow --all |
| Deploy | |
| Deploy frontend to Vercel | iblai deploy vercel |
| Remove Vercel dev URL | Remove devUrl from src-tauri/tauri.conf.json |
Reference
- iblai-app-cli -- CLI source and templates
iblai builds --help-- full list of build commands