> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revyl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run your app on a cloud device

> Start a dev loop that installs your development build on a cloud simulator or emulator and reloads it as you edit.

`revyl dev` runs your local app on a cloud iOS simulator or Android emulator. You keep
editing code in your own workspace. Revyl provisions the device, installs your
development build, starts hot reload, and opens a live viewer.

For Expo and React Native, most JavaScript and TypeScript changes hot reload through
Metro. For [other stacks](/frameworks#hot-reload-and-rebuild-configuration), Revyl
rebuilds and reinstalls when a change needs a new binary.

Prompt for your coding agent:

```text
Run this app on a Revyl cloud simulator or emulator with the dev loop.

Read https://docs.revyl.com/dev-loop.md and follow it. It's the current Revyl guide for this, so prefer it over anything you remember about Revyl.

The dev loop is for iOS and Android. If the app builds both, start with iOS: `revyl dev --platform ios --detach --json`, then watch it with `revyl dev status`. For a Web app, follow https://docs.revyl.com/frameworks/web.md instead; Web is in alpha.

You're done when `revyl dev status` shows the app installed and running, and you've given me the viewer link.

Ask me before anything that needs my login or approval.
```

## Before you start

- The [Revyl CLI](/install), signed in with `revyl auth login`.
- A development build uploaded to a Revyl app. For iOS that's a simulator `.app` or a
  zipped `.app`, not an `.ipa`. For Android it's a debuggable APK whose native libraries
  include `x86_64` or `arm64-v8a`. See [Artifact requirements](/builds/artifact-requirements).
- A terminal in your app's directory, the one that holds the mobile project.

<Steps>
<Step title="Set up the project">

```bash
revyl init
```

This writes `.revyl/config.yaml` with a stable `project.id`. When detection works, it also
writes `build.framework` and named iOS and Android profiles. If it picked a nested native
project, run `revyl init --detect` from the app directory, adjust the profile, and run
`revyl config validate`.

</Step>
<Step title="Start the loop">

```bash
revyl dev --platform ios
```

Revyl starts your dev server, installs the branch's development build, and opens the
live viewer in your browser. Add `--profile <name>` if your project has more than one
development profile, or `--build-version-id <id>` to install a specific build.

</Step>
<Step title="Make a change">

Save a file. Expo and React Native changes reload through Metro. For native changes,
trigger a rebuild and wait for it:

```bash
revyl dev rebuild --wait
```

</Step>
<Step title="Check the result">

Drive the device from a second terminal while the loop runs:

```bash
revyl device screenshot --out after.png
revyl device tap --target "Sign In button"
```

Work in small steps: look at the screen, take one action, confirm it did what you expected.

</Step>
</Steps>

Stop the loop with `revyl dev stop`.

## Run the loop in the background

Coding agents and scripts should start the loop detached and read its state as JSON:

```bash
revyl dev --detach --json
revyl dev status
revyl dev logs --build --follow
```

`--detach` returns once the device session is ready and prints the handshake with
`--json`. The build keeps running behind it.

## Build native iOS changes remotely

`--remote` builds native iOS changes on a Revyl build runner instead of your machine.
Add `--seed-latest` to install your branch's latest build right away, then swap in the
fresh build when it lands.

```bash
revyl dev --remote --seed-latest --platform ios
```

## Attach to a session someone already started

If a teammate or agent already has the right device state open from the dashboard,
attach your local loop to it instead of starting over:

```bash
revyl dev attach active --context checkout
revyl dev --context checkout
```

## Sign in early

If your app needs an account, decide how the loop reaches a signed-in state before you
start debugging: a test account with seeded data, a staging-only demo mode, or a
test-only [auth bypass deep link](/devices/auth-bypass). If the app logs out mid-session
while the boot token is still valid, `revyl dev auth refresh` fires the deep link again.

## Troubleshooting

| Symptom | Check |
|---|---|
| iOS build won't install | It must be a simulator `.app`, not an `.ipa`. |
| Android build won't install | One standalone APK whose native libraries include `x86_64` or `arm64-v8a`. |
| Expo opens but doesn't load local code | The URL scheme, Metro output, and dev client profile. See [Expo](/frameworks/expo). |
| Wrong framework detected | `revyl init --detect` from the app directory, then `revyl config validate`. |
| Native changes don't appear | `revyl dev rebuild --wait`, then relaunch the session if needed. |
| Your backend blocks requests with a CAPTCHA or rate limit | [Allowlist Revyl's IP addresses](/security/allowlist-ip-addresses). |

For framework-specific errors, see [Dev loop framework troubleshooting](/frameworks#dev-loop-framework-troubleshooting).

## Good to know

- Dev contexts are per worktree, so separate worktrees each get their own loop without `--context`.
- The device stops after 300 seconds idle. Change that with `--timeout`.
- `revyl dev` never stores an active profile or platform. Explicit flags win; otherwise it
  uses the only development-like profile it finds.
- Every flag is listed in the [`revyl dev` reference](/reference/cli/dev).