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

> Use cloud development to iterate with your agent

Cloud development lets your local app run on a cloud iOS simulator or Android emulator. You keep editing code in your normal workspace while Revyl handles the device, install, stream, and network path.

Use it when a teammate, cloud agent, or worktree agent needs to inspect the app without setting up Xcode, Android Studio, Simulator, or Emulator locally.

## Agent Quick Start

Copy this into your coding agent from the root of your mobile app repo:

```text Agent prompt wrap theme={null}
Use Revyl to run this app on a cloud device.

Goal: start a development loop for this app and verify the current local changes.

Steps:
- Install Revyl if needed: `curl -fsSL https://revyl.com/install.sh | sh`.
- Run `revyl init` from the mobile app directory.
- Run `revyl dev`.
- Verify the app launched on the cloud device.
- Report the session URL, what you verified, and any blocker.
```

## How It Works

The loop has three pieces:

1. A **development-capable build** installed on the cloud device.
2. A **local dev server or build command** running in your workspace.
3. A **Revyl session** that connects the device to your local app through the CLI.

For Expo and React Native, most JavaScript and TypeScript changes hot reload through Metro. For other stacks, Revyl uses a rebuild-and-reinstall path when a change needs a new binary.

## What You Need

* A Revyl account with access to your workspace.
* The Revyl CLI installed and authenticated. See [Revyl CLI](/cli/index).
* A Revyl app with an uploaded development build.
* A project directory that Revyl can run locally.

<Note>
  For iOS, use a simulator `.app` or zipped `.app`, not an `.ipa`. For Android,
  use a debuggable APK whose native libraries include `x86_64` or `arm64-v8a`. See
  [Artifact Requirements](/builds/artifact-requirements).
</Note>

## 1. Upload a Development Build

The uploaded build is the shell Revyl installs on the cloud device. It must be able to load local code or be rebuilt quickly for local changes.

| Stack          | What to Upload                                                                                                                                        |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Expo           | A development client build. For iOS, use an EAS profile with `developmentClient: true` and `ios.simulator: true`. For Android, use a development APK. |
| React Native   | A debug simulator `.app` for iOS or debug APK for Android. Metro provides the JavaScript bundle.                                                      |
| Flutter        | A debug simulator `.app` or debug APK. Revyl rebuilds and reinstalls when code changes.                                                               |
| Native iOS     | A Debug build for the `iphonesimulator` SDK.                                                                                                          |
| Native Android | A debuggable APK, usually from `./gradlew assembleDebug`.                                                                                             |

You can upload from the dashboard in **Apps**, or from the CLI:

```bash theme={null}
revyl init
revyl build
```

For framework-specific build commands, use the [build guides](/builds/index).

## 2. Initialize Your Project

Run this from the app directory, not the monorepo root unless the app itself lives there:

```bash theme={null}
revyl init
```

`revyl init` creates `.revyl/config.yaml` and detects the local provider Revyl should use.

If detection picks the native project inside an Expo or React Native app, force the provider:

```bash theme={null}
revyl init --provider expo
revyl init --provider react-native
```

Expo projects also need a custom URL scheme in the development client so Revyl can open the app on the remote simulator and point it at Metro. See the [CLI dev setup guide](/develop/dev-loop-expo-guide) for monorepos, custom ports, schemes, and provider config.

## 3. Start the Loop

You can start from the terminal or from a live session in the UI.

### Start From the Terminal

```bash theme={null}
revyl dev
```

Revyl starts the local dev server, creates a relay, installs your development build, and opens the cloud device session.

Use platform or build flags when needed:

```bash theme={null}
revyl dev --platform ios
revyl dev --platform android
revyl dev --build-version-id <id>
```

### Start From the UI, Then Attach

If you already launched a session from the dashboard, attach your local dev loop to it:

```bash theme={null}
revyl dev attach active --context checkout
revyl dev --context checkout
```

This is useful when a teammate or agent already has the right device state open and you want to connect local code to that session instead of starting over.

## 4. Iterate

For Expo and React Native, save a JavaScript or TypeScript file and wait for Metro to update the cloud device.

For other stacks, some code changes need a new build before they appear on the cloud device. Use the rebuild flow in `revyl dev` when that happens.

Use the browser stream for visual checks, or drive the device from another terminal:

```bash theme={null}
revyl device screenshot --out before.png
revyl device tap --target "Sign In button"
revyl device screenshot --out after.png
```

Work in small observe-act-verify loops: look at the current screen, take one action, then confirm the device did what you expected.

## 5. Handle Login Early

If the app needs authentication, decide how agents should reach a useful state before they start debugging.

Good options are:

* A stable test account with seeded data.
* A staging-only demo mode.
* A test-only auth bypass deep link.

For the deep link pattern, see [Auth Bypass Deep Links](/builds/auth-bypass-deeplinks).

## Troubleshooting

| Symptom                                 | What to Check                                                                              |
| --------------------------------------- | ------------------------------------------------------------------------------------------ |
| iOS build will not install              | Confirm it is a simulator `.app`, not an `.ipa`.                                           |
| Android build will not install          | Confirm it is one standalone APK and its native libraries include `x86_64` or `arm64-v8a`. |
| Expo opens but does not load local code | Check the URL scheme, Metro output, and dev client profile.                                |
| Revyl detects the wrong framework       | Run from the app directory or re-run `revyl init --provider expo` / `react-native`.        |
| Native changes do not appear            | Rebuild and reinstall from `revyl dev`, then relaunch the session if needed.               |

<CardGroup cols={2}>
  <Card title="CLI Dev Loop Guide" href="/develop/dev-loop-expo-guide">
    Full command reference for contexts, attach, tests, and rebuilds.
  </Card>

  <Card title="Auth Bypass Deep Links" href="/builds/auth-bypass-deeplinks">
    Start sessions from authenticated app states.
  </Card>
</CardGroup>