Setup

Platform requirements and native project setup for iOS and Android. Related guides: Android fallback model, Availability, Images.

Platform Requirements

iOS Setup

CocoaPods users need no additional configuration. Foundation Models and Image Playground are system frameworks available automatically on supported devices with Apple Intelligence enabled.

For Capacitor projects using Swift Package Manager, the current Capacitor CLI generates CapApp-SPM/Package.swift with an iOS 18.0 deployment target and does not preserve the required minor version. After every npx cap sync ios, change its platform declaration to platforms: [.iOS("18.4")]. The included example app automates this with npm run cap:sync; see example-app/scripts/sync-capacitor.mjs for the small, fail-fast wrapper.

Call getAvailability() at runtime to check whether the text model is ready before creating chats or generating text. Check getImageAnalysisAvailability() separately before supplying images because text and vision availability can differ. See Images for image analysis details.

On iOS versions below 26, only getAvailability() reports 'device-not-eligible' for the text LLM. Text and chat APIs such as createChat(), deleteChat(), generateText(), and streamText() reject with LOCAL_LLM_UNSUPPORTED. Image generation via generateImage() is available on iOS 18.4+.

downloadModel() is not available on iOS — the OS manages the model. Use getAvailability() or the availabilityChange event to observe readiness.

Android Setup

The plugin's minimum Android SDK is 29, higher than Capacitor's current default (24). Update android/variables.gradle in your application:

ext {
    minSdkVersion = 29
}

Gemini Nano is distributed via Google Play Services and must be downloaded to the device before use. The model is not bundled with your app.

When Gemini Nano is unavailable, apps may configure an explicit LiteRT-LM fallback. See Android fallback model.

Check availability and download

Call getAvailability() to inspect the current state. If the status is downloadable, start the download with downloadModel() and listen for downloadProgress and/or availabilityChange until the status becomes available.

import { LocalLLM } from '@rdlabo/capacitor-local-llm';

const availabilityListener = await LocalLLM.addListener('availabilityChange', ({ status }) => {
  console.log('availability:', status);
});

const progressListener = await LocalLLM.addListener('downloadProgress', (event) => {
  if (event.progress != null) {
    console.log('download progress:', event.progress);
  } else if (event.downloadedBytes != null) {
    console.log('downloaded bytes:', event.downloadedBytes);
  }
});

const { status } = await LocalLLM.getAvailability();

if (status === 'downloadable') {
  await LocalLLM.downloadModel();
}

await availabilityListener.remove();
await progressListener.remove();

Web Setup

Supported desktop Chrome browsers run text generation through the built-in Prompt API. See Web setup and limitations. Run npm run dev in example-app to test on localhost.