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, Appium, Argent, or the iOS browser preview.

The remote device starts blank unless the start command receives an application source. You can ask EAS CLI to install and launch an EAS Build, an application archive, or Expo Go while the session starts. You can also start a blank device and install a local simulator- or emulator-compatible build through its controller.

Typical use case: A coding agent starts an agent-device session, opens Expo Go or a development build connected to Metro, and iterates with Fast Refresh. You can follow the same iOS session in the web preview. Ask the agent to use the EAS Simulator skill, which handles the build workflow, remote session, device control, evidence collection, and cleanup. 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 session type

Choose how you plan to control the device before starting the session. Pass the session type explicitly. On iOS, agent-device, Appium, and Argent sessions include both the selected controller and a web preview. Use web-preview-only when you only need the web preview without programmatic control.

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:

Record the build ID from the command output, or find a completed simulator build:

After the build is ready, pass its ID to simulator:start. EAS downloads, installs, and launches the build before the session becomes ready:

You can pass an application archive URL instead of a build ID:

--build-id and --application-archive-url are mutually exclusive. The iOS build must target the Simulator.

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

The Android build must produce an APK. Android sessions support controller-driven interactions and screenshots, but not the live browser preview.

If the session is already running, agent-device can still download an artifact into the active remote virtual machine (VM):

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 Expo Go

For a project that is compatible with Expo Go, start Metro with a public tunnel before creating the simulator session. The remote device must be able to reach Metro when EAS CLI opens the URL:

EAS CLI selects the Expo Go version that matches the current project's Expo SDK. Pass --sdk-version <version> with --expo-go only when you need to override the detected version. The --open-url value must be an Expo URL that the installed app understands; do not pass the browser's webPreviewUrl.

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. Start Metro first because EAS CLI opens the URL while preparing the session:

Pass the EAS Build ID and development-client URL to simulator:start. EAS installs and launches the build, then opens the URL before the session becomes ready:

Replace <scheme> with the custom scheme from the app config and URL-encode the public Metro URL when needed. Repeat --launch-arg <value> for any launch-time arguments the app requires.

Keep exactly one Metro process running. After the first bundle loads, Fast Refresh sends source edits to the remote app.

The start command can install a development build only from a remote EAS Build or an application archive. For a local development .app, start a blank agent-device session, upload it with install, and use agent-device to open the development-client URL.

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.

Control the app with Appium

Start an Appium-backed session when you want to connect an existing Appium client or test suite:

EAS CLI writes APPIUM_URL and APPIUM_CAPS to .env.eas-simulator. simulator:exec loads those values before running the Appium client command. Appium sessions do not also provision agent-device or Argent.

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.

When handing the preview to another person, add --max-duration-minutes <minutes> when starting the session so it stops automatically. You can also add --max-idle-time-minutes <minutes> to stop after a period without session activity. Tell the viewer when the session will stop, and remember that it continues consuming usage until it stops.

Stop when finished

If you started Metro, stop that process too.