An app download is not always one universal APK. Split bundles may contain a base package, features, CPU-specific libraries, screen-density assets, and language assets. Installing the wrong subset can fail before your agent reaches a screen.

Mobilebox phones run Android 14 on arm64-v8a. The install endpoint accepts an APK or a split bundle in .apks or .xapk form. It selects the base, feature, and matching architecture, density, and language splits.

Install local bytes

bash
curl --fail-with-body -X POST "$MSB/v1/phones/$ID/apps" \
  -H "Authorization: Bearer $MOBILESANDBOX_API_KEY" \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @app.apks

Use --data-binary so curl preserves the file bytes. The phone must be ready. The API returns the installed package and version information; use that package name for open_app rather than guessing from the app’s display name.

Or let the service download it

bash
curl --fail-with-body -X POST "$MSB/v1/phones/$ID/apps" \
  -H "Authorization: Bearer $MOBILESANDBOX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://your-download-host.example/app.apk"}'

Replace the example URL with a direct download that the service can reach. A web page with a Download button is not the APK. Keep private download credentials out of source code and published examples.

Permissions are part of the test

New installs may show Android runtime permission dialogs. By default, handle them through the screen as a user would. The optional grant_permissions flag grants runtime permissions up front; use it only when skipping those dialogs is intentional. If permission behavior is what you are testing, leave it off.

Updates and failure recovery

Updating a compatible app keeps its data. A different signing key is refused with signature_mismatch. Uninstalling to bypass that error deletes the app’s data; do it only when a fresh install is the intended outcome.

Before blaming the agent, verify the package architecture, build, download response, and signature. Then launch the installed package and observe the foreground app. Installation success is not proof of app compatibility or of a completed user workflow. The API reference and error guide define the request shapes and recovery contract.

Put it to work.

Open the quickstartRead the API reference