Storage & Download Orchestration
Relevant source files
The following files were used as context for generating this wiki page:
Storage & Download Orchestration manages the lifecycle of AI models and persistent data across multiple platforms. This system coordinates the retrieval of model artifacts from remote registries and their secure placement within platform-specific file systems, such as Android Keystore, iOS Keychain, or Web OPFS.
The orchestration logic resides primarily in the C++ commons core to ensure cross-platform parity. Each SDK (Swift, Kotlin, React Native, Web, Flutter) acts as a thin bridge, implementing platform-specific I/O and HTTP transport while delegating model lifecycle, registry management, and download sequencing to the core. Sources: AGENTS.md:38-51, bindings/kotlin/AGENTS.md:78-83
Architecture Overview
The system operates through an Inversion of Control (IoC) pattern. The C++ core manages the business logic for downloads and storage but relies on a platform adapter to perform actual I/O and network requests.
The diagram shows how the Core Layer invokes platform-specific implementations in the SDK Layer via C vtables and adapter structs. Sources: AGENTS.md:99-105, bindings/react-native/AGENTS.md:164-169
Download Orchestration
The Download Orchestrator manages the transfer of models from remote servers to local storage. It handles concurrency, progress reporting, and error recovery.
Download Process
- Authentication: The SDK authenticates with the backend during Phase 2 initialization.
- Assignment: The core fetches model assignments relevant to the authenticated user or device.
- Transfer: The orchestrator triggers downloads using the platform-registered HTTP transport.
- Verification: Downloaded artifacts are validated against expected digests.
Sources: bindings/kotlin/AGENTS.md:88-95, bindings/react-native/AGENTS.md:195-204
HTTP Transport Registration
Each SDK must register a rac_http_transport_ops_t struct during initialization. This allows the C++ core to perform network operations without a direct dependency on libraries like libcurl.
| Platform | Implementation Mechanism |
|---|---|
| Android | OkHttpTransport.kt registered into C++ vtable via JNI. |
| iOS | URLSessionHttpTransport.mm using native URLSession. |
| Web | emscripten_fetch or custom Fetch-based transport. |
| React Native | NitroModules-backed transport delegating to native URLSession/OkHttp. |
Sources: bindings/kotlin/AGENTS.md:108-109, bindings/react-native/AGENTS.md:175-180
Storage Management
The Storage Manager organizes files into logical directories and handles secure data persistence for credentials and sensitive configuration.
Platform Storage Locations
The SDK utilizes the most appropriate persistent storage for each runtime environment:
- Android: Internal storage for models; Android Keystore for sensitive data.
- iOS: Internal storage for models; Keychain for auth tokens.
- Web: Origin Private File System (OPFS) or IndexedDB for model persistence.
- Desktop: Standard application data directories (e.g.,
~/.runanywhere).
Sources: AGENTS.md:46-48, bindings/web/AGENTS.md:15-18, bindings/electron/example/README.md:36-38
Web OPFS and Local Folder Access
On Web platforms, the SDK supports both browser-managed storage (OPFS) and user-selected local directories via the File System Access API.
Model Lifecycle and Registry
The Model Registry maintains the state of all available, downloading, and loaded models. It prevents redundant downloads and ensures models are staged correctly before inference.
Registry States
| State | Description |
|---|---|
| Registered | Model metadata is known to the SDK but files may not be present. |
| Downloading | The model is currently being transferred to local storage. |
| Downloaded | All artifacts are present on disk and verified. |
| Loading | The model is being read into memory/GPU by an inference engine. |
| Loaded | The model is ready for active inference turns. |
Sources: bindings/web/tests/browser/release-app.e2e.spec.ts:98-105, bindings/react-native/example/AGENTS.md:92-95
Registry Configuration
Models are registered via RunAnywhere.models.register(). Developers specify the model architecture, framework (e.g., LlamaCPP, ONNX), and artifact URLs. The registry handles the mapping between these logical definitions and physical file paths on the device. Sources: bindings/react-native/example/AGENTS.md:204-208
Secure Storage
Secure storage is used for API keys and environment configurations. The C++ core defines a rac_secure_storage_ops_t interface that each SDK implements using platform-native security features.
- Android implementation:
SecureStorageManager.ktutilizes the Android Keystore system. - iOS implementation:
KeychainManager.swiftutilizes the Apple Keychain. - Web implementation: Uses encrypted browser storage or session-only memory for sensitive tokens to prevent logging or persistence of raw secrets.
Sources: bindings/react-native/AGENTS.md:157-162, bindings/web/AGENTS.md:90-95
Summary
The Storage & Download Orchestration system centralizes complex model management logic in C++ while leveraging platform-native I/O. This ensures that features like RAG indexing, large model downloads, and secure credential storage behave consistently across iOS, Android, and Web applications. By strictly separating platform transport from orchestration logic, the system maintains a high degree of reliability and security for on-device AI operations.