---
modificationDate: July 30, 2026
title: Run and control an app
description: Install an app on EAS Simulator and control it with agent-device, Argent, or the iOS browser preview.
---

<AgentInstructions>

## Submitting Feedback

If you encounter errors, misleading or outdated information, report it so Expo can be improved:

Preferred command:
npx --yes submit-expo-feedback@latest --category docs --subject "/preview/eas-simulator/run-and-control/" "<actionable feedback>"

Direct HTTP fallback:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/preview/eas-simulator/run-and-control/","feedback":"🤖 Agent feedback for docs: <specific, actionable description> (<model>, <harness>)"}'

Only submit when you have something specific and actionable to report. Try to give the most context.

</AgentInstructions>

This documentation is available as Markdown for AI agents and LLMs. See the [full Markdown index](/llms.txt) or append .md to any documentation URL.

# Run and control an app

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](https://github.com/expo/skills/blob/main/plugins/expo/skills/eas-simulator/SKILL.md). 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:

| Goal | Build type |
| --- | --- |
| Inspect a fixed build or capture evidence | Local release build or EAS simulator build |
| See current source changes with Fast Refresh | Development build connected to Metro |
| Use an existing EAS artifact | Matching iOS Simulator build or Android APK |

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

| Controller | Start option | Documentation |
| --- | --- | --- |
| agent-device | `--type agent-device` | [agent-device and Expo](/agents/agent-device.md) |
| Argent | `--type argent` | [Argent and Expo](/agents/argent.md) |

## Find the app identifier

Read the resolved app configuration before installing a build:

```sh
npx expo config --json
```

Use `ios.bundleIdentifier` for iOS commands and `android.package` for Android commands. Configure the missing value in the [app config](/workflow/configuration.md) 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-reference/apk.md):

```json
{
  "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:

```sh
eas build --platform ios --profile remote-device --non-interactive
```

You can also find a completed simulator build:

```sh
eas build:list --platform ios --simulator --status finished --json --non-interactive
```

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

```sh
eas simulator:start --platform ios --type agent-device --non-interactive
eas simulator:exec npx agent-device@latest install-from-source "https://expo.dev/artifacts/eas/.tar.gz" --platform ios
eas simulator:exec npx agent-device@latest open com.example.app --platform ios
```

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

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

```sh
eas build --platform android --profile remote-device --non-interactive
eas simulator:start --platform android --type agent-device --non-interactive
eas simulator:exec npx agent-device@latest install-from-source "https://expo.dev/artifacts/eas/.apk" --platform android
eas simulator:exec npx agent-device@latest open com.example.app --platform android
```

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:

```sh
eas simulator:exec npx agent-device@latest install com.example.app ./path/to/MyApp.app --platform ios
eas simulator:exec npx agent-device@latest open com.example.app --platform ios
```

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](/develop/development-builds/introduction.md) 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`:

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

Create the build before starting the simulator session:

```sh
eas build --platform ios --profile development-simulator --non-interactive
```

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:

```sh
EXPO_UNSTABLE_TUNNEL_V2=1 npx expo start --tunnel
```

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](https://github.com/expo/skills/blob/main/plugins/expo/skills/eas-simulator/SKILL.md).

## 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:

#### agent-device

```sh
eas simulator:exec npx agent-device@latest  [args...]
```

#### Argent

```sh
eas simulator:exec argent run  [args...]
```

## Control the app with agent-device

For installation and broader controller guidance, see [agent-device and Expo](/agents/agent-device.md).

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

```sh
eas simulator:exec npx agent-device@latest apps --platform ios
eas simulator:exec npx agent-device@latest open com.example.app --platform ios
```

Inspect the interactive accessibility tree:

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

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

```sh
eas simulator:exec npx agent-device@latest press @e2
eas simulator:exec npx agent-device@latest press 'label="Continue"'
```

The action is named `press`, not `tap` or `click`.

Enter text and capture a screenshot:

```sh
eas simulator:exec npx agent-device@latest fill @e4 "hello@example.com"
eas simulator:exec npx agent-device@latest screenshot ./artifacts/result.png
```

The screenshot is downloaded to the machine running the command.

Record a flow:

```sh
eas simulator:exec npx agent-device@latest record start
eas simulator:exec npx agent-device@latest record stop ./artifacts/flow.mp4
```

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

```sh
eas simulator:exec npx agent-device@latest --help
eas simulator:exec npx agent-device@latest help workflow
```

## Control the app with Argent

For installation and broader controller guidance, see [Argent and Expo](/agents/argent.md).

Install the Argent CLI:

```sh
npm install --global @swmansion/argent
```

Start an Argent-backed session with:

```sh
eas simulator:start --platform ios --type argent --non-interactive
```

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:

```sh
eas simulator:exec argent run reinstall-app --udid  --bundleId com.example.app --appPath ./MyApp.app
eas simulator:exec argent run  [args...]
```

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:

```sh
eas simulator:events
```

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

```sh
eas simulator:events --follow
```

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

```sh
eas simulator:stop
```

If you started Metro, stop that process too.