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

# Artifact Requirements

> What your .app or .apk must look like before it can run on Revyl

Revyl runs tests on cloud **simulators (iOS)** and **emulators (Android)**, not physical devices. That single fact drives every requirement below.

## iOS

| Required | Recommended |
| - | - |
| Simulator-slice `.app` (or zipped `.app`). Built against the `iphonesimulator` SDK, not `iphoneos`. | Debug configuration. |

Standalone App Clips carrying `NSAppClip` are supported as iOS builds. Upload
the simulator-built Clip's `.app` bundle or its ZIP archive to register the
Clip's bundle identifier for test runs. If an archive includes a host app and
its embedded Clip, Revyl selects the host; upload the Clip separately to test it.

CLI file and URL uploads also accept gzip-compressed tar archives named `.gz`,
`.tar.gz`, or `.tgz`, including EAS artifacts that contain ZIP data despite those
suffixes. URL ingestion additionally accepts uncompressed `.tar` archives.
These archives must contain a supported `.app` bundle; arbitrary gzip-compressed
files are not supported.

### Why

Cloud simulators run a different CPU slice than physical iPhones. An `.ipa` produced for device distribution will not install on a simulator — `simctl install` rejects it with an arch mismatch. You need the `.app` bundle that Xcode/EAS produces when targeting the simulator.

### How to satisfy it

| Framework | Knob |
| - | - |
| Xcode / Swift | `xcodebuild -sdk iphonesimulator -configuration Debug` |
| Expo (EAS) | `ios.simulator: true` on your build profile in `eas.json` |
| React Native (bare) | `xcodebuild -sdk iphonesimulator` (Pods + workspace) |
| Flutter | `flutter build ios --simulator --debug` |

<Note>
  `.ipa` archives are not supported. If your CI produces an `.ipa`, you'll need
  a parallel simulator-slice job to upload to Revyl.
</Note>

## Android

Three requirements:

1. **Upload one installable `.apk` artifact.** `.aab`, `.apks`, APK Set archives, and split APK archives are not supported.
2. **Native libraries must include a supported 64-bit ABI.** Revyl accepts `x86_64` and `arm64-v8a`. APKs without native libraries are also supported.
3. **APK must be debuggable** (`android:debuggable="true"` in the merged manifest).

### Why a supported 64-bit ABI

Cloud emulators run `x86_64` Android images with Android's NDK translation layer enabled for `arm64-v8a` native code. APKs with either 64-bit ABI can run; APKs whose native libraries are only `x86` or `armeabi-v7a` cannot. Default debug builds from every framework usually include a compatible ABI, so this mainly matters if you've narrowed `abiFilters` or `android.ndkAbiFilters`.

### Why debuggable

Debuggable builds (`android:debuggable="true"` in the merged manifest) are what allow Revyl to walk the app sandbox via `run-as <pkg>` — the platform only permits that against debuggable apps on non-rooted (Play-image) emulators. That sandbox access powers the **State tab**: SharedPreferences, Jetpack DataStore, and your app's SQLite databases. It also keeps a number of test-execution paths fast and reliable.

The runtime *will* install a non-debuggable release APK — tests still execute, video records, logs flow. You lose the State tab, and a class of debugging-dependent features. Don't ship a release APK to Revyl by default; produce a debuggable variant for testing alongside whatever you ship to users.

### How to satisfy it

| Framework | Knob |
| - | - |
| Gradle / Kotlin / Java | `./gradlew assembleDebug` — debuggable + all ABIs by default |
| React Native (bare) | `cd android && ./gradlew assembleDebug` |
| Flutter | `flutter build apk --debug` |
| Expo (EAS) | The `development` profile (`developmentClient: true`, `android.buildType: "apk"`) is debuggable and ships all ABIs |

<Note>
  Custom `abiFilters` is the most common reason a build fails to install on Revyl.
  If you've narrowed the ABI set for size reasons, include `x86_64` or
  `arm64-v8a`, or produce a separate Revyl-targeted APK variant with at least
  one of them. Do not upload `.apks` files or ZIPs containing multiple split
  APKs; Revyl does not install APK sets.
</Note>

## Artifact size

Build artifacts may be up to 5 GiB. Revyl enforces this limit from the bytes it
receives or reads from storage, regardless of any size reported by the upload
client or source server.

Validation uses a bounded 8 GiB temporary workspace for the artifact and any
files extracted or repackaged from it. A compressed archive below 5 GiB can
still be rejected if processing it would exceed that workspace.

The CLI also limits each local conversion to 8 GiB of temporary files and
8 GiB of uncompressed data during repacking. These limits apply separately to
each CLI process. See [upload existing builds](https://github.com/RevylAI/revyl-cli/blob/main/docs/build-uploads.md)
for local conversion behavior.

## FAQ

<AccordionGroup>
  <Accordion title="Can I use a physical-device archive (.ipa / non-debuggable release APK)?">
    No. `.ipa` won't install on simulators. Release APKs install but lose the
    State tab and other debugging-dependent paths. Use a debug build for Revyl.
  </Accordion>

  <Accordion title="Why does Revyl insist on a simulator slice / supported Android ABI?">
    Cloud test infra runs on shared hosts. Simulators (iOS) and emulators
    (Android) give us isolation and snapshot-restore. Physical-device farms
    exist but aren't what Revyl is.
  </Accordion>

  <Accordion title="What about Apple Silicon arm64 simulators?">
    Xcode produces a fat simulator `.app` (`x86_64` + `arm64`) by default.
    Both slices are accepted; Revyl picks the right one at install time.
  </Accordion>

  <Accordion title="My CI only produces release/production builds. What now?">
    Add a parallel debug job for Revyl. Most Gradle / Xcode / EAS projects
    need only a single extra task or profile.
  </Accordion>

  <Accordion title="My build uses abiFilters for size reasons.">
    Include `x86_64` or `arm64-v8a`, or produce a separate Revyl-targeted
    variant with at least one of them. You do not need both ABIs in the same APK.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Framework Build Guides" href="/builds/frameworks">
    Platform-specific build commands for Xcode, Gradle, RN, Flutter, Expo.
  </Card>

  <Card title="Apps & Builds" href="/builds/index">
    Upload, activate, and manage builds in your Revyl app.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.