Introduction to RunAnywhere SDKs
Relevant source files
The following files were used as context for generating this wiki page:
RunAnywhere SDKs provide a cross-platform ecosystem for on-device AI inference. The project utilizes a shared C++ core, known as runanywhere-commons, which implements all AI business logic behind a pure C Application Binary Interface (ABI) using the rac_* prefix. Thin platform-specific SDKs for Swift, Kotlin, Flutter, React Native, Web, Python, and Electron bridge this core logic to their respective runtimes.
The architecture centralizes heavy lifting in the C++ layer, including model lifecycle management, engine registration, and inference routing. Platform SDKs serve as thin bridges that supply necessary system services like file I/O, HTTP networking, and secure storage to the core via an inversion-of-control (IoC) adapter.
Sources: AGENTS.md:88-100, core/README.md:1-12, CONTRIBUTING.md:43-50
Core Architecture
The system follows a multi-layered approach to ensure code reuse across all supported platforms. The logic lives at the lowest possible layer to benefit all consumers.
Architectural Layers
- C++ Commons (
core/): Contains non-I/O logic, including model registry, download orchestration, RAG session management, and inference routing. - Platform SDK Layer: Implements platform-specific I/O or runtime bridging, such as iOS Keychain, Android Keystore, or Web OPFS.
- Example Apps: Provide UI rendering and navigation, making thin calls to the SDK without containing business logic.
Sources: AGENTS.md:65-75, core/README.md:17-45
Data Flow and Bridge Mechanism
The following diagram illustrates how platform-specific SDKs interact with the shared C++ core.
The diagram shows the hierarchy from the consumer application down to the native engine plugins.
Sources: AGENTS.md:88-112, core/README.md:17-45
Supported SDKs and Platforms
RunAnywhere supports a wide range of platforms and bridge mechanisms. Each SDK uses a specific method to communicate with the native rac_commons library.
| SDK | Path | Bridge Mechanism | Platforms |
|---|---|---|---|
| Swift | bindings/swift/ | XCFramework + Module Map | iOS 17.5+, macOS 14.5+ |
| Kotlin | bindings/kotlin/ | JNI (librunanywhere_jni.so) | Android (Min API 24) |
| Flutter | bindings/flutter/ | Dart FFI | iOS, Android |
| React Native | bindings/react-native/ | NitroModules (JSI HybridObject) | iOS 17.5+, Android arm64 |
| Web | bindings/web/ | Emscripten WASM | Chrome, Safari, Firefox |
| Electron | bindings/electron/ | Node-API Addon | Windows x64, macOS |
| Python | bindings/python/ | pybind11 extension | Windows, macOS, Linux |
Sources: AGENTS.md:100-112, core/README.md:120-130
AI Primitives and Engine Plugins
The C++ core routes AI tasks to specialized engine plugins through a vtable-based registry (rac_engine_vtable_t). Engines are assigned base priorities to determine which backend handles a specific primitive by default.
Engine Priorities
| Engine | Primitives Served | Priority |
|---|---|---|
| qhexrt | LLM, VLM, STT, TTS (Qualcomm NPU) | 150 |
| mlx | LLM, VLM, Speech, Embeddings (Apple) | 110 |
| llamacpp | LLM, VLM (GGUF) | 100 |
| sherpa-onnx | STT, TTS, VAD | 90 |
| onnx / cloud | Embeddings, Segmentation, Cloud STT | 50 |
Sources: AGENTS.md:125-135, core/README.md:48-65
Primitive Support Matrix
The core supports several AI primitives, which are served by different backends based on the platform.
- Text Generation (LLM): Served by LlamaCPP, QHexRT, and MLX.
- Speech-to-Text (STT): Served by Sherpa (offline), QHexRT, and Cloud STT (HTTP).
- Text-to-Speech (TTS): Served by Sherpa/ONNX (Piper) and QHexRT.
- Computer Vision (VLM): Served by LlamaCPP and QHexRT.
- Embeddings: Served by ONNX Runtime.
Sources: core/README.md:48-65, bindings/electron/README.md:14-25
Initialization Lifecycle
Every SDK follows a standard two-phase initialization sequence to prepare the native environment and services.
- Phase 1 (Synchronous): The SDK registers the platform adapter, loads native libraries, and configures core logging and storage paths.
- Phase 2 (Asynchronous): The SDK authenticates the device, fetches model assignments, and discovers previously downloaded models.
Sources: AGENTS.md:139-145, bindings/kotlin/AGENTS.md:95-108, bindings/react-native/AGENTS.md:140-149
Initialization Sequence Diagram
The diagram outlines the transition from synchronous library loading to asynchronous service readiness.
Sources: AGENTS.md:139-145, bindings/kotlin/AGENTS.md:100-115
Development and Task Runner
The project is a monorepo managed by a unified task runner located at the root. All build, lint, and setup actions are driven through the ./run script.
./run doctor: Scans the host environment for required toolchains (Xcode, Android NDK, Flutter, Node, etc.)../run setup: Provisions build files and dependencies for all buildable targets on the current host../run codegen: Regenerates type-safe bindings for all languages from the Protobuf schemas located inidl/../run sdk <name> build: Builds a specific platform SDK or the native core.
Sources: CONTRIBUTING.md:52-78, AGENTS.md:167-175
Summary
RunAnywhere SDKs enable developers to integrate high-performance on-device AI across mobile, desktop, and web platforms. By utilizing a shared C++ core and Protobuf-defined schemas, the project ensures consistent behavior and API parity across different programming languages. The system abstracts complex native inference engines behind simple platform-specific facades, handling the intricacies of model lifecycle and hardware acceleration automatically.
Sources: README.md, core/README.md:1-15, AGENTS.md:88-100