This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

Install an EAS Build, a build fingerprint, an application archive, Expo Go, or a local build on an Expo Simulators session.

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.

A new Expo Simulators session starts with a blank device. To put your app on it, give eas simulator:start an application source. EAS then downloads, installs, and launches the app before the session becomes ready. You can also start a blank session and install a local build through the controller.

Choose an application source

The four start flags are mutually exclusive. Pass at most one of them. A session without an application source starts with a blank device.

Build a simulator-compatible app

A remote device is a simulator or an emulator, not a physical phone. Build for that target:

This EAS Build profile creates an installable build for both platforms:

{
  "build": {
    "remote-device": {
      "ios": {
        "simulator": true
      },
      "android": {
        "buildType": "apk"
      }
    }
  }
}

iOS Simulator builds are not signed, so EAS Build does not ask for credentials. For more information, see Which build to install on Expo Simulators.

Install an EAS Build

Create the build before you start the session. A build can take longer than the maximum duration or idle limit of a session:

Record the build ID from the output. To find an existing iOS Simulator build, list the finished builds:

For Android, leave out --simulator, because the flag works only with --platform ios. Pick an APK build from the list:

Then pass the build ID to the start command:

For Android, use --platform android in the eas build and eas simulator:start commands. The Android build must be an APK.

Install the build that matches a fingerprint

A fingerprint is a hash of the native parts of your project. eas simulator:start does not calculate the fingerprint for you. To get the hash for your current project, run eas fingerprint:generate with the build profile that you use for remote device builds:

The command prints Fingerprint generated: <hash>. Pass the hash to install the most recent finished, non-expired build with that fingerprint. On iOS, the build must target the iOS Simulator:

Use a fingerprint when any build with that fingerprint hash is acceptable, and --build-id when you need one specific build. On Android, EAS can select a build of any distribution type, so use a build profile that creates an APK.

Install from an application archive URL

Pass an HTTP or HTTPS URL that returns the file directly. The remote device downloads the file one time, when the session starts:

For iOS, use a gzip tarball (.tar.gz or .tgz) that contains the .app directory, or the contents of the .app bundle at its root. A .zip or .app.zip archive does not install. For Android, use the URL of an .apk. An .aab does not install. A signed URL works while it is valid.

Pass launch arguments and open a URL

When you use an application source, you can also pass launch arguments and a URL to open after the app launches:

Repeat --launch-arg for each argument. EAS passes the arguments in the same order. --launch-arg and --open-url require an application source. Without one, the command fails with Launch options require an application source.

In an iOS agent-device or Argent session, EAS tries to approve the custom URL scheme first. Then the system Open in dialog does not appear. In other session types, or if the approval fails, the dialog can appear. Accept it in the browser preview or with the controller.

Install a local build

To install a build that is on your computer, start a blank session. Then upload the build through the controller:

A local upload takes longer for a large build. When the build is at a URL, the remote device can download it instead:

Find the app identifier

Controller commands use the app identifier. For an Expo project, read it from the resolved app config:

Use android.package for Android and ios.bundleIdentifier for iOS. For other toolchains, use the package name or bundle identifier that your build system assigns.

Common questions