Does the Bitrise workflow need a macOS stack?

No. The iOS Simulator runs on EAS, and the Bitrise machine does not need macOS or a local simulator. This workflow uses the ubuntu-latest-stable Linux stack, which includes Node.js and jq. If EAS Build makes your simulator build, no step in the workflow needs macOS.

What happens to the session if a Bitrise step fails?

It keeps running until something stops it. Bitrise skips the later steps, and the end of a build does not stop the session. The stop step has is_always_run: true, so it runs after a failure and stops the session. If that step cannot run, the session stops at the time you set with --max-duration-minutes.

Where do the screenshots and recordings go in Bitrise?

To the Artifacts tab of the Bitrise build. agent-device downloads each screenshot and recording from the session to the path you pass, which is $BITRISE_DEPLOY_DIR in this workflow. Deploy to Bitrise.io uploads the files in that directory, and it runs even after a failed step.

Can pull request builds use the Expo token?

Only if you expose it. By default, Bitrise pull request builds cannot read Secrets, so they cannot use EXPO_TOKEN. You can turn on Expose for Pull Requests for that Secret. Bitrise calls this a potential security risk, depending on your repository's privacy settings. A robot user with the Developer role limits what the token can do.

Run Expo Simulators in a Bitrise workflow — Articles

Quick answer

A Bitrise workflow can start an Expo Simulators session, install your iOS Simulator build, drive the app with agent-device, and save screenshots and recordings as build artifacts. Store an Expo robot user's access token as a Bitrise Secret named EXPO_TOKEN. Run the eas simulator commands in Script steps on a Linux stack, and stop the session in a step that always runs.

With Expo Simulators, the iOS Simulator runs on EAS. The Bitrise machine does not need macOS or a local simulator, so this workflow runs on a Linux stack.

Set up the Expo token

On expo.dev, create a robot user on the account that owns the project, with the Developer role or higher. Developer is the lowest role that can start and stop sessions.
Copy its access token. Robot users cannot sign in and work only with a token.
In Bitrise, open Workflows, select Secrets, and add a project level Secret with the key EXPO_TOKEN.

EAS CLI reads EXPO_TOKEN from the environment, so the job never runs eas login. Bitrise shows [REDACTED] in the build log in place of the value.

Get a build

Create the build before the session starts. Add a profile that targets the iOS Simulator to eas.json:

{
  "build": {
    "remote-device": {
      "ios": {
        "simulator": true
      }
    }
  }
}

Run eas build --platform ios --profile remote-device --non-interactive, and put the build ID in EAS_BUILD_ID. To install the newest finished build for your native code, use --build-fingerprint with the hash that eas fingerprint:generate --platform ios --build-profile remote-device --non-interactive prints. For a build made elsewhere, such as on Bitrise, pass a URL to a .tar.gz of the .app with --application-archive-url.

Add the workflow to bitrise.yml

Replace <build-id> with your build ID, and com.example.app with the ios.bundleIdentifier that npx expo config --json prints.

format_version: '26'
default_step_lib_source: https://github.com/bitrise-io/bitrise-steplib.git

meta:
  bitrise.io:
    stack: ubuntu-latest-stable

tools:
  nodejs: 22:installed

workflows:
  simulator-check:
    envs:
    - EAS_BUILD_ID: "<build-id>"
    - APP_ID: com.example.app
    steps:
    - git-clone@8: {}
    - script@1:
        title: Start an Expo Simulators session
        inputs:
        - content: |-
            #!/usr/bin/env bash
            set -eo pipefail
            npx --yes eas-cli@latest simulator:availability --json | jq -e '.available'
            npx --yes eas-cli@latest simulator:start --platform ios --type agent-device \
              --build-id "$EAS_BUILD_ID" \
              --name "Bitrise build $BITRISE_BUILD_NUMBER" --tag ci --tag bitrise \
              --max-duration-minutes 30 --non-interactive
    - script@1:
        title: Drive the app
        inputs:
        - content: |-
            #!/usr/bin/env bash
            set -eo pipefail
            npx --yes eas-cli@latest simulator:exec npx agent-device@latest open "$APP_ID" --platform ios
            npx --yes eas-cli@latest simulator:exec npx agent-device@latest record start "$BITRISE_DEPLOY_DIR/flow.mp4"
            # Change the label to text on your first screen.
            npx --yes eas-cli@latest simulator:exec npx agent-device@latest is visible 'label="Welcome"'
            npx --yes eas-cli@latest simulator:exec npx agent-device@latest screenshot "$BITRISE_DEPLOY_DIR/home.png"
    - script@1:
        title: Stop the recording and the session
        is_always_run: true
        inputs:
        - content: |-
            #!/usr/bin/env bash
            npx --yes eas-cli@latest simulator:exec npx agent-device@latest record stop || true
            npx --yes eas-cli@latest simulator:stop
    - deploy-to-bitrise-io@2:
        is_always_run: true

What does each step do?

Git Clone checks out the repository, because the start command needs the app config with the EAS project ID.
The start step checks access first. simulator:availability exits with code 0 even without access, so jq -e fails the step when available is false.
The drive step runs agent-device through simulator:exec, which loads the connection details of the session. agent-device downloads screenshots and recordings to the path you pass.
The stop step and Deploy to Bitrise.io run even after a failed step. A build that ends does not stop the session, so the stop step needs is_always_run: true. Stopping a stopped session succeeds. Deploy uploads the files in $BITRISE_DEPLOY_DIR to the Artifacts tab of the build.

Each Script step runs in $BITRISE_SOURCE_DIR, so the later steps find the .env.eas-simulator file. The Ubuntu stack includes jq and Node.js 22, and agent-device needs Node.js 22.12 or later.

For Android, build an APK and use --platform android. Android support is still in development, so some features that work on iOS may not work on Android yet.

Keep tokens out of the build log

The start command writes controller tokens to .env.eas-simulator. These tokens are not Bitrise Secrets, so Bitrise does not redact them.

Do not print the file or the --json output of the start command. Both contain connection details.
Do not copy the file to $BITRISE_DEPLOY_DIR. Deploy to Bitrise.io uploads every file in that directory.
Leave set -x out of your scripts. The default Script content turns it on, and the Bitrise Secrets guide says to remove it.
Add .env.eas-simulator to .gitignore.

Let an agent set it up

If an agent writes the workflow or runs the session for you, have it load these Expo Skills first:

expo-overview: the entry point that routes the agent to the right Expo skill.
eas-simulator: the current eas simulator commands, session types, and cleanup steps.

Install them:

Claude Code: claude plugin install expo@claude-plugins-official
Codex: codex plugin add expo@openai-curated
Cursor and other agents: npx skills add expo/skills

The full list is at docs.expo.dev/skills.

Try it

Expo Simulators is in a limited beta release. The docs on running sessions in CI also cover the REST API and parallel sessions.

Try Expo Simulators

Verified on 20 October 2026.

Run Expo Simulators in a Bitrise workflow

Quick answer

Set up the Expo token

Get a build

Add the workflow to bitrise.yml

What does each step do?

Keep tokens out of the build log

Let an agent set it up

Try it

Keep reading

How to run an iOS Simulator in GitHub Actions with Expo Simulators

Run Expo Simulators in CircleCI

How to set up CI/CD for a mobile app

Frequently Asked Questions