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 app on EAS Simulator and control it with agent-device, Argent, or the iOS browser preview.

The remote device starts blank. Install a simulator- or emulator-compatible build before opening and controlling the app.

For agentic development, ask your coding agent to use the EAS Simulator skill. It can choose the appropriate build workflow, start the remote device, drive the app, collect evidence, and stop the session. The sections below document the same workflow for manual use.

Choose the build type based on what you need:

A release build contains the JavaScript from build time. Connecting it to Metro does not enable Fast Refresh. Use a development build for live iteration.

Choose a controller

Choose a controller before starting the session and pass its type explicitly. Use that controller's commands for the rest of the session.

Find the app identifier

Read the resolved app configuration before installing a build:

Use ios.bundleIdentifier for iOS commands and android.package for Android commands. Configure the missing value in the app config before creating the build.

Install an EAS Build artifact

Create an installable artifact for each platform in an EAS Build profile. iOS requires ios.simulator: true, and Android requires an APK build:

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

Build the app before starting EAS Simulator. A build can take long enough for an idle simulator session to lose its controller tunnel:

You can also find a completed simulator build:

After the build is ready, start an agent-device session and use install-from-source. The remote virtual machine (VM) downloads the artifact directly:

Replace com.example.app with the app's iOS bundle identifier.

For Android, create and install the APK from the same profile:

Replace com.example.app with the app's Android package. Android sessions support controller-driven interactions and screenshots, but not the live browser preview.

Install a local build with agent-device

For a local iOS simulator .app bundle, install uploads the build through the controller:

Large local builds take longer because the client uploads them from your machine. Prefer install-from-source when an EAS artifact URL is available.

For a local Android APK, use the same command with the Android package, APK path, and --platform android.

Use a development build for live changes

Live iteration requires a development build with expo-dev-client. The development build loads JavaScript from Metro instead of relying only on the bundle embedded at build time.

If the machine cannot create the native build locally, configure an EAS profile with both developmentClient: true and ios.simulator: true:

{
  "build": {
    "development-simulator": {
      "developmentClient": true,
      "ios": {
        "simulator": true
      }
    }
  }
}

Create the build before starting the simulator session:

For Android, the same profile produces an installable APK when you run the build command with --platform android. No additional Android configuration is required.

Start Metro with a public tunnel that the remote development client can reach:

Install and open the development build, then enter the public Metro URL in the development client's Enter URL manually flow. Keep exactly one Metro process running. After the first bundle loads, Fast Refresh sends source edits to the remote app.

For the complete tested development-client sequence, install the EAS Simulator skill.

Run controller commands with simulator:exec

simulator:exec is controller-neutral. It loads the active session's connection environment and runs the command that follows. Use the command pattern for the controller selected when the session started:

Control the app with agent-device

For installation and broader controller guidance, see agent-device and Expo.

Use these commands with a session started with --type agent-device:

Inspect the interactive accessibility tree:

The snapshot returns references such as @e1 and @e2. Use press to activate an element:

The action is named press, not tap or click.

Enter text and capture a screenshot:

The screenshot is downloaded to the machine running the command.

Record a flow:

Other useful controller commands include scroll, gesture, logs, network, and perf. Read the version-matched help through the active session:

Control the app with Argent

For installation and broader controller guidance, see Argent and Expo.

Install the Argent CLI:

Start an Argent-backed session with:

Use these commands with a session started with --type argent. simulator:exec supplies ARGENT_TOOLS_URL and ARGENT_AUTH_TOKEN from .env.eas-simulator, so argent link is not required for commands invoked this way:

Argent uses its own tools and app installation commands. An Argent session does not also provision an agent-device daemon, so do not run agent-device commands against it.

Inspect session activity

Sessions that use agent-device or Argent record controller activity. Show the activity recorded so far for the current session:

In another terminal, follow new activity while you or an agent drives the device:

The follow command exits when the session ends. Use --id <session-id> to inspect another session, or --json to return raw event records for an agent or script. --json and --follow cannot be used together.

Session activity describes controller operations and interactions. It does not replace application runtime logs.

Use the iOS browser preview

Supported iOS sessions return a webPreviewUrl. Open it in a desktop browser while the session is active.

Stop when finished

If you started Metro, stop that process too.