This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Get started with Expo Simulators
Edit page
Check whether Expo Simulators is available, start a remote device session, and connect to it.
Start an Expo Simulators session with an AI agent
Paste this into Claude, Cursor, Codex, or another agent.
Start an Expo Simulators session for my Expo project. Use https://docs.expo.dev/eas/simulators/get-started.md as the source for each command. 1. Check that EAS CLI is installed and up to date. If it is not, run `npm install -g eas-cli`. 2. Check that I am logged in with `eas whoami`. If I am not, stop and ask me to run `eas login` or to set `EXPO_TOKEN`. Do not print a token. 3. If the project does not have an Expo Services project ID, ask me before you run `eas init`. 4. Run `eas simulator:availability --json`. If `available` is `false`, stop and tell me. Do not start a session. 5. Add .env.eas-simulator to .gitignore. Do not print, commit, or share this file. 6. Ask me for the platform (`ios` or `android`) and the session type (`agent-device`, `argent`, `appium`, or `web-preview-only`). Then run `eas simulator:start --platform <platform> --type <type> --name "<short purpose>" --non-interactive`. 7. Run `eas simulator:get --json --non-interactive`. Continue only when `status` is `IN_PROGRESS` and `remoteConfig` is present. 8. Give me the session page link and the browser preview link. Tell me which commands you ran. 9. The session counts toward my account's usage until it stops. When I say that I am done, run `eas simulator:stop`.
3 requirements
3 requirements
1.
Expo Simulators is available on paid plans. Check the current project's account before starting a session.
2.
Run these commands from the project directory. If the project does not have an Expo Services
project ID, run eas init first.
3.
The simulator:* commands are experimental. Install or update EAS CLI before using
them. Since the commands change quickly, use eas simulator:start --help to check the flags
supported by your installed version.
Expo Skills for AI agents
If you use an AI agent, install Expo Skills and ask it to use the Expo Simulators skill. The skill can perform the session workflow below, drive the app, and collect evidence for you. Use this page when you want to understand or run the commands manually.
Run and control a user's app on a remote iOS/Android simulator with Expo Simulators (also called EAS Simulator).
Start a session manually
The steps below use EAS CLI. To manage sessions directly from your own HTTP client, see the REST API reference. To start a browser-preview-only session when someone opens an authenticated expo.dev URL, see Start a session from a link.
1
Authenticate and verify the project
On an interactive machine, log in and confirm the current user:
In CI or a headless agent environment, provide an Expo access token in EXPO_TOKEN instead of starting an interactive login.
If the project is not linked to Expo Services, initialize it:
2
Check account availability
The availability check is read-only. It does not start a device or consume simulator usage. The --json flag is optional, but it makes the result easy for an agent or script to inspect:
An enabled account returns:
{ "available": true, "accountName": "my-account" }
If available is false, do not call simulator:start. Use a local simulator or emulator, or upgrade the account to a paid plan. See Expo Simulators access.
3
4
Choose a session type and start a remote device
Choose the controller you plan to use for installation and device actions. Each controller-backed session also includes a browser preview. If you only need the browser preview, use web-preview-only without a controller. Pass the session type explicitly when you start the session.
See agent-device and Expo for controller setup and commands.
See Argent and Expo for controller setup and commands.
Use an Appium client when you already have Appium tests or automation. EAS CLI writes the remote server URL and capabilities to the session configuration.
Use the browser preview without provisioning a programmatic controller.
Give each session a short name that describes its purpose. The name appears in simulator:list, simulator:get, and on expo.dev, which makes parallel and historical sessions easier to identify.
Use --platform android for an Android Emulator. The session page on expo.dev shows an Open preview button that opens the browser preview in a new tab.
Use --device to select an Android virtual device hardware profile, or a specific iOS Simulator name or unique device identifier (UDID). If you omit the flag, the remote runner uses medium_phone on Android and iPhone 17 on iOS. See Expo Simulators devices.
For an unattended or shareable session, use --max-duration-minutes to set an automatic stop time. The value can be up to 115 minutes. A larger value returns an error. Without the flag, the maximum duration is 115 minutes. You can also use --max-idle-time-minutes to stop after a period without session activity.
When --platform is omitted in an interactive terminal, EAS CLI asks which platform to use. Non-interactive runs require the flag.
The start command waits for the session to become ready, then writes .env.eas-simulator. It also prints:
- A direct simulator session page on expo.dev
- A browser preview link that requires an Expo login with access to the project. With
--public-link, EAS CLI prints a public link instead. See Browser preview links. - The command pattern for controlling the device
To install and launch an app before the session becomes ready, pass exactly one of --build-id, --build-fingerprint, --application-archive-url, or --expo-go. You can also pass launch arguments and an Expo or development-client URL. See Install an app on a remote Android Emulator or iOS Simulator for complete examples.
--non-interactivedoes not automatically stop the session. The command returns when the session is ready, and the remote device remains active.
5
6
Open the web surfaces
The start command links to a session page with this shape:
https://expo.dev/accounts/<account>/projects/<project>/simulator-sessions/<session-id>
The project-level session list is:
https://expo.dev/accounts/<account>/projects/<project>/simulator-sessions
Open the browser preview link in a desktop browser to view the live device. On iOS, you can also interact with it. By default, the link has this shape, and it requires an Expo login with access to the project:
https://expo.dev/accounts/<account>/projects/<project>/simulator-sessions/<session-id>/preview
In --json output, the link is remoteConfig.webPreviewUrl, or remoteConfig.previewUrl for a web-preview-only session. The preview link is not an application deep link. Do not pass it to a controller command that opens apps or URLs.