eas-simulator

EAS Simulator

EAS service - costs apply. EAS Simulator runs on Expo Application Services cloud infrastructure, a paid product with free-tier limits; remote simulator sessions use your plan's compute allowance. See https://expo.dev/pricing.

EAS Simulator runs a remote iOS simulator or Android emulator on EAS infrastructure that you drive from your machine — from the CLI, from an AI agent (via agent-device), and from a browser preview. It's the unlock for environments that can't run a simulator locally (Linux boxes, cloud/background agents like Cursor Cloud), and for letting an agent verify a change on a real device instead of only reasoning about code.

The simulator:* commands are experimental and hidden, and need a recent eas-cli (≥ 20.3.0 as of writing) — which is why this skill runs everything via npx --yes eas-cli@latest. Flags and verbs may change; if a command fails, <cmd> --help is authoritative.

When to use

The frontmatter description carries the trigger phrases. In short: use this to get a user's app onto a cloud simulator and interact with it — especially from a Mac-less or cloud/sandbox agent. Not for local sims (expo run:ios, Xcode, Android Studio), store builds/signing (that's EAS Build), or physical devices. For the macOS case, see Cloud vs local next.

Cloud vs local: decide this first

• Non-macOS (Linux / CI / cloud sandbox like Cursor Cloud, detect via uname -s ≠ Darwin): the only way to get a sim — proceed, once you've confirmed access (see Check availability first below).
• macOS: local sims exist and a cloud session costs money + latency, so ask first ("a remote cloud sim — to share a live preview, offload, or test an iOS version you lack — or just run locally?") unless the user explicitly said cloud/remote/shareable.
• Always honor an explicit choice; for "run it locally" hand off to expo run:ios / Xcode.

# Programmatic detection — run this to decide before doing anything else:
if [ "$(uname -s)" != "Darwin" ] || ! xcrun --find simctl &>/dev/null 2>&1; then
  echo "no local sim — proceed with EAS Simulator"
else
  echo "local sim available — ask the user (cloud or local?)"
fi

Prerequisites

• Run every eas command via npx --yes eas-cli@latest … — guarantees a CLI new enough to have simulator:* (a global eas is often too old), and --yes skips npx's prompt. (Bare eas is fine if eas --version is current.)
• Authenticated. Interactive machine → npx --yes eas-cli@latest login. Cloud sandbox / CI / headless agent has no browser login — set EXPO_TOKEN (expo.dev → Account → Access Tokens) in the env instead. Verify either way with npx --yes eas-cli@latest whoami.
• Run from an Expo project directory. A fresh app needs one-time setup: npx --yes eas-cli@latest init to create/link the project (when there's no projectId), and set ios.bundleIdentifier in app config if it's missing — a fresh create-expo-app often has none, and prebuild/eas build need it (they prompt or fail without it; e.g. dev.<owner>.<slug>). Read current config with npx expo config --json (it may live in app.config.js). The first Mode-C run is slow (native build); later runs reuse it.
• A controller to drive the device. This skill uses agent-device (open source, MIT), run on demand via npx agent-device@latest — nothing globally installed. argent is an alternative (--type argent in simulator:start); see references/controllers.md.
• .env.eas-simulator is written/managed by eas-cli (not this skill): it holds the session id (EAS_SIMULATOR_SESSION_ID) + the daemon URL/token, so get/stop/exec default to that session (usually omit --id; pass --id <id> to target another). It carries a token → keep it gitignored (eas-cli marks it "do not commit" but may not add the ignore rule, and a fresh app's .gitignore won't cover it — add .env.eas-simulator if missing).
• --max-duration-minutes is paid-plan only; otherwise a default applies.
• The command blocks assume a POSIX shell (bash/zsh) — printf, lsof, $(seq …) loops won't run in cmd/PowerShell. On Windows, run them in WSL or Git Bash, or translate as you go (the eas-cli/agent-device invocations themselves are cross-platform).

Check availability first

EAS Simulator is a limited-access EAS feature that is still rolling out, so it isn't enabled on every account. Confirm access before starting a session — this is a read-only check: no session, no billing.

npx --yes eas-cli@latest simulator:availability --json
# → {"available": true, ...}  enabled → continue to the core loop
# → {"available": false, ...} not enabled → do NOT start a session

If it's not available, don't call simulator:start (it will fail). Instead, hand off gracefully so you keep making progress without this skill:

• Tell the user EAS Simulator isn't available on their account yet — it's coming soon.
• Fall back to their normal local path for the actual goal — expo run:ios / Xcode / Android Studio for a local sim/emulator, an EAS Build, or whatever else fits. Don't dead-end on the cloud sim; the request was almost never "use EAS Simulator specifically."

(If simulator:availability isn't recognized, the CLI is too old — upgrade, or treat a not enabled for this account error from simulator:start the same way: stop and fall back.)

The core loop (always the same)

A session is: start → (install your app) → drive → stop. eas-cli owns the session; the device verbs (open/tap/screenshot) come from the controller, which npx --yes eas-cli@latest simulator:exec runs for you with the session's connection env loaded.

# 1. Start a session (boots the remote sim + agent-device daemon; writes .env.eas-simulator).
printf '# managed by eas-cli\n' > .env.eas-simulator   # clear any stale session first
npx --yes eas-cli@latest simulator:start --platform ios --type agent-device --non-interactive \
  --name "Checkout flow screenshots"   # always name it — see 'Always name the session'
#    Then confirm it's live: simulator:get --json → status IN_PROGRESS (bounded poll in run-your-app.md).

# 2. Drive it through `exec` (loads the session env, then runs the command you give it).
#    agent-device runs on demand via npx — nothing installed globally.
npx --yes eas-cli@latest simulator:exec npx agent-device@latest open <app-or-url> --platform ios
npx --yes eas-cli@latest simulator:exec npx agent-device@latest snapshot -i          # interactive UI tree → @e1, @e2 refs
npx --yes eas-cli@latest simulator:exec npx agent-device@latest press @e2            # tap a ref (NOTE: 'press', not 'tap')
npx --yes eas-cli@latest simulator:exec npx agent-device@latest screenshot ./shot.png

# 3. Stop (ends billing; tears down the VM) and reset the dotenv. Omit --id to target the dotenv session.
npx --yes eas-cli@latest simulator:stop
printf '# managed by eas-cli\n' > .env.eas-simulator

To watch it live, hand the user the webPreviewUrl that start prints (an --type agent-device iOS session runs serve-sim alongside the daemon, so it emits one — agent control and a browser preview in one session; Android has no preview, and --type serve-sim is preview-only). This URL is for the user's browser — you cannot open it for them, and it must never touch the sim:

• "Open it here" (Cursor/VS Code) → print the URL on its own line and tell the user to open Simple Browser (Cmd/Ctrl+Shift+P → "Simple Browser: Show") and paste it. Then stop: do not shell out to a system browser or a Cursor/VS Code URL handler, and do not ask "did a tab appear?" — you can't confirm it, the handoff is done.
• Never open the webPreviewUrl on the sim. It's a browser preview, not a deep link and not an agent-device open argument; routing it to the device renders a browser-in-a-browser (a real past failure).
• Headless agent (no display) → just return the URL as the deliverable.
• Keeping it alive for the user to drive → bound it: start with --max-duration-minutes N so it auto-stops; tell them it bills until stopped and when it auto-stops; offer to reopen/extend when it ends. (This is the one case where "stop right away" doesn't apply; one-shot screenshot/get runs still stop immediately.)

start also prints a job-run URL.

Always name the session

Pass --name "<description>" on every simulator:start. The name appears in simulator:list, simulator:get, and on the Simulator sessions page on expo.dev, where it replaces the generic title on each row. Unnamed, every row reads "Simulator session" over a random id — a wall of identical entries nobody can navigate. Write the name for a human scanning that list days later, not for yourself during this run.

Write what the session is for, in a few plain words:

--name "Checkout flow screenshots"     # what you did
--name "Dev build — dark mode fix"     # what you were testing
--name "Login repro for issue 412"     # why it exists

Rules:

• Derive it from the user's request, not from the mode or the tooling. Mode C session, agent-device ios, and test say nothing.
• Length: aim for 3–6 words, ~40 characters, and treat 50 as the practical limit. It renders as a single-line title in a narrow table column, so a long name clips. The API accepts up to 255 characters and rejects an empty/whitespace-only name, but 255 is a ceiling you never approach, not a target. One noun phrase, no sentences.
• Be specific within that budget. Include a ticket or PR number when there is one.
• Sentence case: capitalize the first word only, and leave identifiers in their real casing (Dev build for expo-router v4, Repro for EXPO-1234). It's a row title, so no Title Case, no all-lowercase, and no trailing period.
• Don't repeat what the table already shows. Every row already displays the session id, platform, start time, duration, and who created it — so no ids, no iOS, no dates, no your-own-name. Spend the whole budget on what those columns can't say: the purpose.
• If the user names it, use their name as-is.
• Sessions are per-run, so name each new one for that run. Don't reuse an old name for different work.

--name is newer than simulator:start itself, so an older installed eas-cli can reject it. If that happens, run via npx --yes eas-cli@latest or upgrade; as a last resort, retry once without --name (the session starts unnamed). See references/troubleshooting.md.

Commands at a glance

Running the user's app — pick a mode

The remote sim boots blank — no Expo Go, no apps. Install a build, then drive it — but match the build type to the goal first (the box below); that's where live-session runs derail. Full sequences: references/run-your-app.md — read before running a mode.

Match the build to the goal before installing anything — this is where live-session runs derail. Two traps, same root (grabbing a build that doesn't fit the request):

1. Wrong type. Live edits (Mode C) require a dev build. A static build — a local Release (A), the default EAS sim build (B), or any build left on the sim from an earlier screenshot run — freezes its JS at build time and can never hot-reload. For a live request, ignore existing builds entirely and install a dev build (local Debug, or an EAS build with developmentClient: true). Never reconnect Metro to a static build hoping it'll reload — it won't.
2. Stale. A static look must match current source — reuse only a fingerprint-matched build, else build fresh; reuse is explicit-only.

So a leftover EAS/release build is not a shortcut for "iterate live" — it's the wrong binary. The fact that a build exists never makes it the right one.

Quick decision — default to C; A and B are explicit-only:

• C (almost everything): iterate, interact, poke the app, live edits — and most "show me my app" (current code needs a build anyway, so live+current wins). Mac → dev client builds locally; no Mac → build it on EAS (developmentClient: true). Unsure → C.
• A: only an explicit one-shot static screenshot on a Mac.
• B: only when the user names an existing/EAS build or wants a static EAS artifact (CI/sharing) — see the box above for why a static build is the wrong tool for "iterate."

Driving the device (agent-device)

agent-device is the controller. Common verbs (run each as npx --yes eas-cli@latest simulator:exec npx agent-device@latest <verb>):

Screenshots vs. video. Default to screenshot for static state, but for anything that moves — an animation, a transition, a gesture, a timing/jank question — record a video and inspect the frames instead; a still can't prove motion. Both controllers record (agent-device record start/stop, argent screen-recording-start/stop). Recordings sample at ~30fps — enough to see visible jank, not to prove sub-frame 60/120Hz hitches. For timing specifically, argent drops static frames by default (turn trimStatic off) — that plus other per-controller gotchas are in references/controllers.md.

For the full verb set and the argent controller alternative, see references/controllers.md.

Operating principles

The non-obvious mental model worth internalizing. Specific error→fix lookups (hung verbs, tap→press, --platform, --json, pod install locale, orphaned sessions, boot variability) live in references/troubleshooting.md.

1. Establish ground truth, then reset — don't patch-loop. Never assume an existing session or Metro is yours or healthy. Before driving, confirm:

   • cwd — you're in the intended Expo project dir (a misdirected start/exec sessions the wrong app + drops a stray .env.eas-simulator; pwd / check app.json).
   • session live — IN_PROGRESS via simulator:get --json (a stopped session keeps its id + remoteConfig, so the dotenv alone isn't proof).
   • Metro on its own port — reuse only if you started it this session; else start one on a free port (--port <N>, e.g. 8082), don't kill another server to reclaim :8081 (run-your-app.md).
   • build fits intent — a release build can't live-reload; if live edits are wanted and a release build is installed, install the dev build, don't reconnect.

   If current code isn't rendering after your first connect, stop poking live state: reset to baseline (stop session → clear dotenv → kill your Metro) and redo the mode once; a second failure → stop and report. Never restart Metro in place, reconnect more than once, rebuild the native client to fix a JS/connection problem, or surface a preview URL while state is unknown. (A daemon drop — ERR_NGROK_3200 / Remote daemon is unavailable — is the same: reset, don't retry.)

2. exec is a wrapper, not a driver. simulator:exec loads .env.eas-simulator and spawns the command you pass; the device verbs come from the controller (npx agent-device@latest). There is no simulator:tap.

3. Act immediately; don't park an idle session. Sessions are short-lived — install and drive right after start. Leaving one idle drops the tunnel/daemon (→ reset, per #1).

4. Stop on every exit path (billing) and reset the dotenv. --non-interactive doesn't auto-stop, and a forgotten session bills until stopped. Don't start again to "retry" a slow boot — that orphans a second billed session.

5. Screenshot only the correct, fresh build. Mode C only after the dev client connects to Metro; A/B only from a build matching current source — reusing a pre-existing build is the #1 "my edits don't show" cause (see the build caveat above). (9:41 in the status bar is the sim default, not staleness.)

Stop and clean up

Stop the session (ends billing) and reset the dotenv so a later run doesn't try to reuse the dead session:

npx --yes eas-cli@latest simulator:stop          # omit --id → stops the dotenv session (or pass --id <id>)
printf '# managed by eas-cli\n' > .env.eas-simulator   # clear the stale session id so it isn't reused
# if you started Metro for Mode C, stop it too (Ctrl+C in its terminal, or kill the expo process)

References

• references/run-your-app.md — full command sequences for modes A, B, and C (read before running a mode).
• references/controllers.md — agent-device verb reference and the argent alternative.
• references/troubleshooting.md — concrete errors and fixes.

Source of truth: Expo docs and the eas / agent-device CLIs (npx --yes eas-cli@latest simulator:* --help, agent-device --help). This skill teaches how to apply them; it doesn't replace them.

Submitting Feedback

If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:

npx --yes submit-expo-feedback@latest --category skills --subject "eas-simulator" "<actionable feedback>"

Only submit when you have something specific and actionable to report. Include as much relevant context as possible. If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.