System Miniapp APIs

Mentra Miniapp SDK betaThe SDK is in beta, so its APIs may change before general availability.There is currently no way to distribute a miniapp built with the Miniapp SDK. In a future release, developers will upload miniapps through the Mentra Developer Console, and users will download them from the Mentra Miniapp Store. Neither service supports Miniapp SDK distribution in MentraOS 3.0.Only use the Miniapp SDK if you are comfortable with these limitations.Developing on Mentra Live? We recommend using the Mentra Bluetooth SDK.The developer tools are available in the Mentra App under Settings → Miniapp Developer Settings.Share feedback with an in-app bug report, on Discord, or by email at help@mentra.glass.

These APIs are restricted to system miniapps (Mentra AI today). A regular miniapp that calls them gets NOT_PERMITTED. They’re documented here for reference. To make your own miniapp callable, expose actions instead, see Actions.

System miniapps can discover other miniapps, control their lifecycle, invoke the actions those miniapps expose, and use a small set of privileged device controls.

Discover and control miniapps

session.miniapps lists installed miniapps and starts or stops them.

// Compatible miniapps only by default; each action can carry input and output schemas.
const apps = await session.miniapps.list();
const all = await session.miniapps.list({ includeIncompatible: true });

// start() runs a miniapp in the BACKGROUND: it spawns the background context and
// reports as running, without changing phone navigation or foregrounding anything
// (the WebView mounts only if the user opens it).
await session.miniapps.start("com.mentra.todo");
await session.miniapps.open("com.mentra.todo"); // start and bring its phone UI forward
await session.miniapps.stop("com.mentra.todo");

Method	Returns	Notes
`list(options?)`	`Promise<MiniappInfo[]>`	`options.includeIncompatible` defaults to `false`. Each entry carries its declared `actions`.
`start(packageName)`	`Promise<void>`	Background-spawn; no foreground change.
`open(packageName)`	`Promise<void>`	Start and foreground the miniapp’s phone UI.
`stop(packageName)`	`Promise<void>`	Stop a running miniapp.

Each MiniappInfo also reports system (the Mentra App build ships this miniapp) and, when a bundled Store maintains the installed release, storeOwnerPackageName or systemStoreOwnerPackageName. Actions declared with "audience": "host" are not listed.

Installing miniapps

session.miniapps.install, checkInstallCompatibility, onInstallProgress and uninstall are accepted only from a Store miniapp bundled with the Mentra App. Other callers, system miniapps included, get NOT_PERMITTED. The host downloads the release, checks its SHA-256, archive, publisher signature, version and compatibility, and installs it through the same installer as every other source. An automatic update passes onlyIfStopped: true: it never stops a running miniapp by itself and answers APP_RUNNING instead. With askIfRunning: true as well, the Mentra App stages the release and asks the user whether to update now; declining, or a question the app does not show (it is in the background, another question is open, or it asked about this miniapp within the last day), still answers APP_RUNNING, and the update installs once the miniapp stops.

Invoke an action

session.actions.invoke calls an action another miniapp exposed via session.actions.handle. It headless-wakes the target if it’s stopped, runs the handler, and returns the result.

const res = await session.actions.invoke(
  "com.mentra.todo",
  "add_todo",
  { text: "milk" },
  { timeoutMs: 30000 }, // default 30s, max 120s
);

invoke() rejects with { code, message } where code is one of:

Code	Meaning
`NOT_PERMITTED`	The caller isn’t a system miniapp.
`APP_NOT_FOUND`	No miniapp with that package name.
`APP_NOT_COMPATIBLE`	The target can’t run on the connected glasses.
`ACTION_NOT_FOUND`	The target doesn’t declare that action.
`NO_ACTION_HANDLER`	The action is declared but no handler is registered.
`WAKE_FAILED`	The target couldn’t be headless-woken.
`ACTION_TIMEOUT`	The handler didn’t resolve within `timeoutMs`.
`PAYLOAD_TOO_LARGE`	Params or result exceeded 256 KB.

A thrown handler in the target surfaces its own error message to the caller. The action descriptor returned by session.miniapps.list() includes an optional outputSchema, which describes the structured result for result-aware callers.

Privileged device controls

Wi-Fi ADB (Mentra Live)

session.glasses.setWifiAdbState toggles wireless debugging on Mentra Live. The preference is persisted on the glasses and reapplied at boot (default off). Non-system callers get NOT_PERMITTED.

await session.glasses.setWifiAdbState(true);  // enable
await session.glasses.setWifiAdbState(false); // disable

Method	Returns	Notes
`setWifiAdbState(enabled)`	`Promise<void>`	Mentra Live only; other models no-op. SYSTEM-only.

Getting Started

Core Concepts

UI Layer

Display

Audio & Speech

Sensors & Input

Camera

Phone & System

Data

Reference

System Miniapp APIs

Discover and control miniapps

Installing miniapps

Invoke an action

Privileged device controls

Wi-Fi ADB (Mentra Live)

​Discover and control miniapps

​Installing miniapps

​Invoke an action

​Privileged device controls

​Wi-Fi ADB (Mentra Live)

Discover and control miniapps

Installing miniapps

Invoke an action

Privileged device controls

Wi-Fi ADB (Mentra Live)