Getting Started

Generate short on-device text responses in a Capacitor app—no API keys, and prompts/responses stay on the device. iOS uses Apple Intelligence (Foundation Models), Android uses Gemini Nano, and supported desktop Chrome uses the built-in Prompt API. On Android, downloading the Gemini Nano model via downloadModel() may use the network.

Note: On-device LLMs require physical hardware. Android emulators are not supported. iOS simulators are supported so long as the host Mac supports Apple Intelligence and has it enabled.

Install

npm install @rdlabo/capacitor-local-llm
npx cap sync

Requires Capacitor 8 or later. Text generation also works in supported desktop Chrome browsers through the built-in Prompt API. See Web setup for requirements and limitations.

Platform summary

Native project setup (SPM deployment target, minSdkVersion, and model download) is in Setup.

Quick start

After Install and Setup (or Web setup in Chrome), check availability, create a chat, and generate text. If status is not available (for example downloadable), follow Setup or the Chrome download flow in Web before retrying—do not treat a throw here as a finished quickstart.

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

const { status } = await LocalLLM.getAvailability();
if (status !== 'available') {
  throw new Error(`Model not ready: ${status}`);
}

const { id: chatId } = await LocalLLM.createChat({
  instructions: 'You are a helpful assistant.',
});

try {
  const { text } = await LocalLLM.generateText({
    chatId,
    prompt: 'What is the capital of France?',
  });
  console.log(text);
} finally {
  await LocalLLM.deleteChat({ id: chatId });
}

Success means a response string is logged and deleteChat completes. Exact wording is model-dependent. Streaming, cancellation, and warmup: Chat. Image input and generation: Images.

Documentation

• Setup — platform requirements, iOS SPM target, Android minSdkVersion, and Gemini Nano download.
• Android fallback model — LiteRT-LM when Gemini Nano is unavailable.
• Availability — status values and platform behavior.
• Chat — chat lifecycle, streaming, cancellation, and warmup.
• Images — image analysis (iOS / Android) and image generation (iOS).
• Events — availability, download, chunk, and generation lifecycle events.
• Migration — deprecated v1 APIs and upstream migration.
• Error Handling — stable LocalLLMErrorCode values.

Method signatures are in the API section below. For API Since notes when upgrading between releases, see Migration and the API section.

Provenance

This project is an independently maintained fork of Ionic's @capacitor/local-llm, based on upstream version 1.0.0 at commit 5bceb55. It is not an official Ionic or Capacitor package and is not affiliated with or supported by Ionic.