Run a native Android or iOS app on Expo Simulators

Edit page

Install a Kotlin, Java, Swift, or Objective-C app built with Gradle or Xcode on a remote Android Emulator or iOS Simulator from an archive URL.

Expo Simulators is a limited-access preview. It is not included with paid or free plans and is currently available only to select partners. Join the waitlist if you are interested in trying it.

Expo Simulators runs native Android and iOS apps. It starts a stock Android Emulator or iOS Simulator, so the app does not need Expo or React Native. Build the app for the emulator or simulator, publish it to a URL, and pass the URL when you start the session.

Prerequisites

3 requirements

An Expo account with Expo Simulators access

Expo grants access directly to select partners. Check the account before you start a session.

An EAS project

A session belongs to an EAS project. Create one at expo.dev. The project does not need Expo source code. Copy its project ID.

A download URL for the app

The remote device downloads the app from the URL. Use storage that serves a direct HTTP or HTTPS URL.

Install and run the app

Build for the emulator or simulator

The remote device is an emulator or a simulator, not a physical phone:

Platform	Required artifact	Constraint
Android	An .apk	If the app has native libraries, include an emulator application binary interface (ABI), such as `x86_64`. An .aab fails to install.
iOS	A .tar.gz of the .app	Build against the `iphonesimulator` SDK. A device .ipa fails to install.

Terminal

- ./gradlew assembleDebug

- xcodebuild -project MyApp.xcodeproj -scheme MyApp -configuration Debug -sdk iphonesimulator -derivedDataPath ./build

- tar -czf MyApp.app.tar.gz -C ./build/Build/Products/Debug-iphonesimulator MyApp.app

For a project that uses CocoaPods, replace -project MyApp.xcodeproj with -workspace MyApp.xcworkspace. For iOS, compress the .app directory into a .tar.gz or .tgz archive, as the tar command does. The output folder matches the configuration: Debug-iphonesimulator for -configuration Debug, or Release-iphonesimulator for -configuration Release. A .zip archive does not install.

Publish the artifact to a URL

Upload the file to storage that returns the file directly. A signed URL works while it is valid. The remote device downloads the file one time, when the session starts.

Start a session with the archive

EAS CLI finds the project from the current directory. It needs package.json and an app config. Add both to the repository root if they do not exist:

package.json

{
  "name": "my-app",
  "version": "1.0.0"
}

app.json

{
  "expo": {
    "name": "my-app",
    "slug": "my-app",
    "extra": {
      "eas": {
        "projectId": "<project-id>"
      }
    }
  }
}

Start the session and pass the archive URL:

Terminal

-

eas simulator:start --platform ios --type agent-device --application-archive-url "https://example.com/MyApp.app.tar.gz" --name "Native build review" --non-interactive

Use the REST API when you do not want an app config in the repository. Authenticate with an Expo access token:

Terminal

- curl -X POST https://api.expo.dev/v2/device-run-sessions \

-H "Authorization: Bearer $EXPO_TOKEN" \ -H "Content-Type: application/json" \

  -d '{"appId":"<project-id>","platform":"ios","type":"agent-device","name":"Native build review","applicationArchiveUrl":"https://example.com/MyApp.app.tar.gz"}'

The response contains the session id, its status, and a url for the session page on expo.dev.

The session downloads the archive, installs the app, and launches it before the controller becomes ready. For Android, use --platform android and the URL of the .apk.

Control the device

Use device-level commands. They act through the operating system:

Terminal

- eas simulator:exec npx agent-device@latest open <application-id> --platform ios

- eas simulator:exec npx agent-device@latest snapshot -i

- eas simulator:exec npx agent-device@latest screenshot ./artifacts/home.png

Replace <application-id> with the Android package name or the iOS bundle identifier from your build settings. See Control a remote simulator with agent-device, Argent, or Appium.

Stop the session

Terminal

- eas simulator:stop

The session also stops at its maximum duration. It does not stop when your terminal closes.

Limitations

Feature	Available for a native app
Boot a remote device	Yes
Install and launch an app archive	Yes
Screenshots, video, and accessibility actions	Yes
Browser preview	Yes
Install by `--build-id`	Only for EAS Build artifacts
Install by `--expo-go` or build fingerprint	No
Fast Refresh and Metro	No
React DevTools and component inspection	No
React render profiling	No

Common questions

Can I install a local build without a URL?

Yes. Start a blank session, then upload the build with agent-device install. See Install a local build.

Why does the install fail?

Check the artifact format first. An .aab, a device .ipa, or a .zip of an iOS app does not install. An Android APK with native libraries but no emulator ABI does not run. See Troubleshoot Expo Simulators.