Installation

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

Package	Size	Features
`@runanywhere/core`	~2MB	Core SDK, model management, events
`@runanywhere/llamacpp`	~15-25MB	LLM text generation (GGUF models)
`@runanywhere/onnx`	~50-70MB	STT, TTS, VAD (ONNX models)

Supported Model Formats

Format	Extension	Backend	Use Case
GGUF	`.gguf`	LlamaCPP	LLM text generation
ONNX	`.onnx`	ONNX Runtime	STT, 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

Requirement	Minimum Version
Android SDK	compileSdk 36
Android NDK	28.0.13004108
JDK	17+
Min API	24 (Android 7.0+)
Kotlin	2.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

Enable Developer Options: Settings → About Phone → Tap “Build Number” 7 times
Enable USB Debugging: Settings → Developer Options → USB Debugging
Connect device: adb devices (should show your device)
Port forwarding: adb reverse tcp:8081 tcp:8081
Start Metro: npm start
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

Framework	iOS (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 →

Getting Started

Swift SDK

Kotlin SDK

React Native SDK

Flutter SDK

Web SDK

Vibe Coding

Package Installation

Full Installation (All Features)

LLM Only (Text Generation)

Voice Only (STT/TTS)

Required Peer Dependencies

Package Overview

Supported Model Formats

iOS Setup

Podfile Requirements

New Architecture (iOS)

iOS Permissions

Android Setup

Android Build Requirements

Gradle Configuration

Android Permissions

Running on Physical Device

ProGuard Rules

Troubleshooting Installation

iOS: Pod Install Fails

Android: Native Library Not Found

Android: “hermesEnabled” Property Not Found

Android: “Unable to load script” on Device

Android: Grey Screen After Launch

Metro: Module Resolution Issues

Both Platforms: Fresh Build

Native Binary Sizes

Next Steps

Quick Start

​Package Installation

​Full Installation (All Features)

​LLM Only (Text Generation)

​Voice Only (STT/TTS)

​Required Peer Dependencies

​Package Overview

​Supported Model Formats

​iOS Setup

​Podfile Requirements

​New Architecture (iOS)

​iOS Permissions

​Android Setup

​Android Build Requirements

​Gradle Configuration

​Android Permissions

​Running on Physical Device

​ProGuard Rules

​Troubleshooting Installation

​iOS: Pod Install Fails

​Android: Native Library Not Found

​Android: “hermesEnabled” Property Not Found

​Android: “Unable to load script” on Device

​Android: Grey Screen After Launch

​Metro: Module Resolution Issues

​Both Platforms: Fresh Build

​Native Binary Sizes

​Next Steps

Quick Start

Package Installation

Full Installation (All Features)

LLM Only (Text Generation)

Voice Only (STT/TTS)

Required Peer Dependencies

Package Overview

Supported Model Formats

iOS Setup

Podfile Requirements

New Architecture (iOS)

iOS Permissions

Android Setup

Android Build Requirements

Gradle Configuration

Android Permissions

Running on Physical Device

ProGuard Rules

Troubleshooting Installation

iOS: Pod Install Fails

Android: Native Library Not Found

Android: “hermesEnabled” Property Not Found

Android: “Unable to load script” on Device

Android: Grey Screen After Launch

Metro: Module Resolution Issues

Both Platforms: Fresh Build

Native Binary Sizes

Next Steps