Skip to main content

​
Package Installation

Choose the packages based on your feature requirements:

​
Full Installation (All Features)

npm install @runanywhere/core @runanywhere/llamacpp @runanywhere/onnx
# or
yarn add @runanywhere/core @runanywhere/llamacpp @runanywhere/onnx

​
LLM Only (Text Generation)

npm install @runanywhere/core @runanywhere/llamacpp
# or
yarn add @runanywhere/core @runanywhere/llamacpp

​
Voice Only (STT/TTS)

npm install @runanywhere/core @runanywhere/onnx
# or
yarn add @runanywhere/core @runanywhere/onnx

​
Required Peer Dependencies

The SDK uses Nitro Modules for its native bridge and requires file system access for model downloads: 
# Required: Native bridge layer
npm install react-native-nitro-modules

# Required: File system access for model downloads
npm install react-native-fs@^2.20.0
react-native-fs is required for model downloads. react-native-nitro-modules is required for the native bridge between JavaScript and the SDK’s native inference engines.
Include only the SDK modules you need. Each native module adds to your app size: - @runanywhere/core: ~2MB (required) - @runanywhere/llamacpp: ~15-25MB (for LLM text generation) - @runanywhere/onnx: ~50-70MB (for STT, TTS, and VAD)

​
Package Overview

PackageSizeFeatures
@runanywhere/core~2MBCore SDK, model management, events
@runanywhere/llamacpp~15-25MBLLM text generation (GGUF models)
@runanywhere/onnx~50-70MBSTT, TTS, VAD (ONNX models)

​
Supported Model Formats

FormatExtensionBackendUse Case
GGUF.ggufLlamaCPPLLM text generation
ONNX.onnxONNX RuntimeSTT, TTS, VAD

​
iOS Setup

automaticPodsInstallation must be set to false in react-native.config.js because @runanywhere packages use podspecPath which is not compatible with RN 0.83+ CLI auto-install. Pods must be installed manually.
cd ios && pod install && cd ..

​
Podfile Requirements

The NitroModules pod must be manually added in your Podfile:
Podfile
pod 'NitroModules', :path => '../node_modules/react-native-nitro-modules'

​
New Architecture (iOS)

If you encounter crashes with react-native-screens or native stack navigator on iOS with New Architecture, disable it:
Podfile
:fabric_enabled => false,
:new_arch_enabled => false,
Use @react-navigation/stack (JS-based) instead of @react-navigation/native-stack on iOS, and mock react-native-screens via Metro config if needed.

​
iOS Permissions

Add required permissions to your Info.plist:
Info.plist
<!-- Required for STT/VAD with microphone -->
<key>NSMicrophoneUsageDescription</key>
<string>This app needs microphone access for speech recognition and voice agent features.</string>

<!-- Required for on-device speech recognition -->
<key>NSSpeechRecognitionUsageDescription</key>
<string>This app uses on-device speech recognition to transcribe your voice.</string>
NSMicrophoneUsageDescription is only required if you’re using STT or VAD with microphone input. The app does NOT need NSAllowsArbitraryLoads — configure specific exceptions as needed.

​
Android Setup

Native libraries are automatically downloaded during the Gradle build.

​
Android Build Requirements

RequirementMinimum Version
Android SDKcompileSdk 36
Android NDK28.0.13004108
JDK17+
Min API24 (Android 7.0+)
Kotlin2.1.20

​
Gradle Configuration

In android/settings.gradle, explicitly include react-native-nitro-modules:
settings.gradle
include ':react-native-nitro-modules'
project(':react-native-nitro-modules').projectDir =
    new File(rootProject.projectDir, '../node_modules/react-native-nitro-modules/android')
In android/app/build.gradle, add pickFirsts to resolve duplicate native library conflicts:
app/build.gradle
android {
    packagingOptions {
        pickFirsts += ['**/libc++_shared.so', '**/libjsi.so', '**/libfbjni.so',
                       '**/libfolly_runtime.so', '**/libreactnative.so']
    }
}

​
Android Permissions

Add required permissions to your AndroidManifest.xml:
AndroidManifest.xml
<!-- Required for model downloads -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- Required for STT/VAD with microphone -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />
Runtime permission for RECORD_AUDIO must be requested via PermissionsAndroid.request() before using STT or Voice Pipeline features.

​
Running on Physical Device

  1. Enable Developer Options: Settings → About Phone → Tap “Build Number” 7 times
  2. Enable USB Debugging: Settings → Developer Options → USB Debugging
  3. Connect device: adb devices (should show your device)
  4. Port forwarding: adb reverse tcp:8081 tcp:8081
  5. Start Metro: npm start
  6. Run app: npx react-native run-android

​
ProGuard Rules

If using ProGuard/R8 minification, add these rules to proguard-rules.pro:
proguard-rules.pro
-keep class com.runanywhere.** { *; }
-keepclassmembers class com.runanywhere.** { *; }
-keep class ai.runanywhere.** { *; }

​
Troubleshooting Installation

​
iOS: Pod Install Fails

# Clean and reinstall pods
cd ios
rm -rf Pods Podfile.lock
pod cache clean --all
pod install
cd ..

​
Android: Native Library Not Found

This error typically occurs when running on an emulator: 
dlopen failed: library "librunanywherecore.so" not found
Solution: Use a physical ARM64 Android device. Emulators are not supported. If using a physical device: 
# Clean and rebuild
cd android
./gradlew clean
cd ..
npx react-native run-android

​
Android: “hermesEnabled” Property Not Found

Solution: Copy the gradle.properties example file: 
cp android/gradle.properties.example android/gradle.properties

​
Android: “Unable to load script” on Device

Solution: Set up port forwarding for Metro bundler: 
adb reverse tcp:8081 tcp:8081

​
Android: Grey Screen After Launch

Solution: Metro bundler may have stopped. Restart it: 
npm start

​
Metro: Module Resolution Issues

# Reset Metro bundler cache
npx react-native start --reset-cache

​
Both Platforms: Fresh Build

# Complete clean build
rm -rf node_modules
npm install
cd ios && pod install && cd ..
npx react-native run-ios  # or run-android

​
Native Binary Sizes

FrameworkiOS (xcframework)Android (so)
RACommons~2MB~2MB
RABackendLLAMACPP~15-25MB~15-25MB
RABackendONNX~50-70MB~50-70MB
The ONNX backend is significantly larger due to the ONNX Runtime library. If you only need LLM text generation, consider installing just @runanywhere/llamacpp to reduce app size.

​
Next Steps

Quick Start

Initialize the SDK and run your first inference →