# Install APKs and split bundles over an API

Upload APK bytes or install by URL, handle arm64 split bundles, and diagnose update failures.

By [Mustafa Yenler](https://mobilebox.dev/about#mustafa) [LinkedIn](https://www.linkedin.com/in/mustafa-yenler) Updated 29 October 2026

Guides2 min read

In this article

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

```
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

```
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](https://mobilebox.dev/docs/reference) and [error guide](https://mobilebox.dev/docs/errors) define the request shapes and recovery contract.

[Mustafa Yenler](https://mobilebox.dev/about#mustafa) is the founder of fifteenA and builds Mobilebox, from Berlin and San Francisco. [LinkedIn](https://www.linkedin.com/in/mustafa-yenler)

## Try it in your agent in 60 seconds

Paste this into Claude Code, Cursor, Codex or any agent that can read a web page. It asks for your email, gets its own key at once and adds the phone tools; the 6-digit code from your inbox keeps the workspace.

```
Set up Mobilebox for me: read https://mobilebox.dev/setup.md?via=install-apk-split-bundles and follow it.
```

[What your agent reads](https://mobilebox.dev/setup.md?via=install-apk-split-bundles)

In this article

[All articles](https://mobilebox.dev/blog)

## Next question

- [How do I add it to Cursor, Codex or VS Code?](https://mobilebox.dev/blog/android-mcp-cursor-codex-vscode?via=next-setup)
