Android Builds

Build a signed Android app (.apk and .aab) from your repository, download it, and install it. The platform provides the build environment and keeps the signing key.

For a mobile microapp this is the Mobile app tab of the microapp. For the project mobile app it is Mobile in the project sidebar. The page and the steps below are the same for both.

Before you start

The feature is on for your project and you have the Admin role on the project. See What you need.
Your repository contains the app, committed and pushed to main.
- A mobile microapp needs the Expo starter: a package.json with expo and expo-router, and an app.json with expo.android.package. The starter you downloaded already has all of this.
- A project mobile app needs the Capacitor Android project in the repository. Run the add-mobile-app skill in your AI IDE (the project’s AI IDE starter includes it), then commit and push to main.

Check the repository

Click Check repository. The platform reads your repository on main and shows a checklist:

A failed check marked as an error blocks enabling, and tells you what to change.
A warning is shown but never blocks.

Fix anything blocking, push to main, and check again. You can run the check at any time, including after mobile builds are enabled.

Enable mobile builds

Click Enable Android builds (Enable mobile app on the project mobile app page). The platform checks the repository once more, then sets up the build environment and generates the signing key. This takes about a minute and the page shows Provisioning until it is done.

When it finishes the status reads Active, with your app identifier. If setup fails the status reads Failed with the reason; click Retry.

🔐

You do this once per app. The signing key stays with the app, so every future build can update the same Play Store listing.

Build the app

Optionally enter a Version name, then click Build Android app.

Leave the version name empty to get 1.0.<build number>, for example 1.0.4. The field’s placeholder shows what the next one will be.
A version name may contain letters, digits and . _ + -, must start with a letter or digit, and can be up to 50 characters.

The build appears in the Builds table and moves through Queued, Running, then Succeeded or Failed. The page refreshes itself every few seconds while a build is in flight.

The first build of a mobile microapp takes about 15 minutes; later ones are faster. A project mobile app build takes about 3 minutes.
Only one Android build runs at a time. The build button is disabled until the current one finishes.
A build that never reports back is marked Failed after 45 minutes, and a setup that never finishes after 15 minutes, so a stuck job never blocks you.

Download

When a build succeeds, the Download column offers:

APK: install directly on a device or emulator.
AAB: upload to Google Play.

Click a button and the browser downloads the file. The download link is short-lived (a few minutes), so click again if it times out.

Install the APK

On a phone, open the downloaded .apk and allow installing from your browser or file manager when Android asks. On an emulator or a phone connected with USB debugging, you can also use:


adb install path/to/app-build-4.apk

Publish to Google Play

Upload the .aab in the Google Play Console. Google Play requires the Android package of your app to stay the same forever, which is why the app identifier is permanent.

Build files expire

Built files are kept for a limited time. After that the download shows File expired. Start a new build if you still need the file.

Disable mobile builds

Click Disable on the app’s card. This removes the build environment and all built files for the app, Android and iOS. The build history is kept, but no build offers its files for download any more. The Android Builds table is hidden until you enable builds again. The iOS builds table stays on the page. The signing key is kept, so you can enable builds again later and keep updating the same app.

You cannot disable while an Android or iOS build runs. Wait for the build to finish.
The removal takes a few minutes. Until it completes, Enable and iOS builds are refused with “Mobile was just disabled and its resources are still being removed. Try again in a few minutes.”

Troubleshooting

Problem	What to do
Buttons are disabled, with a tooltip about a missing permission	You are not an Admin on the project. Ask a project Admin to give you the Admin role on the project’s Access page.
Enable is refused with a checklist	Fix each item marked as an error, push to `main`, then click Check repository again.
The repository check says the app is not in the repository	Commit and push to `main`. The platform reads `main`, not your local files or other branches.
Setup shows Failed	Click Retry. If it keeps failing, contact support with the message shown.
A build shows Failed	Read the reason under the status. Common causes are changes to `android/` (never commit it), a dependency added with `npm install` instead of `npx expo install`, and an app configuration error in `app.json`. Fix it, push to `main`, and build again.
Build Android app is greyed out	A build is still running. Wait for it to finish.
Download says File expired	The file is past its retention time. Build again.
Disable is refused with “Build … is in progress”	Wait for the Android or iOS build to finish, then disable.
Enable is refused with “Mobile was just disabled and its resources are still being removed”	Wait a few minutes, then click Enable again.
The app installs but cannot sign in	The APK talks to your deployed API. Open `<your-api-origin>/api/health` and check it reports healthy.