System Miniapp APIs

Glassly Miniapp SDK betaThe SDK is in beta, so its APIs may change before general availability.Developing on Mentra Live? We recommend using the Glassly Bluetooth SDK.The developer tools are available in the Glassly App under Settings → Miniapp Developer Settings.Share feedback with an in-app bug report, on Discord, or by email at [email protected].

session.miniapps (listing, starting, and stopping other miniapps by package) needs the MANAGE_MINIAPPS manifest permission, and session.settings needs PLATFORM_SETTINGS. Neither shows an OS prompt; both appear in the Store listing. Without the permission, requests reject with {code: "PERMISSION_NOT_DECLARED", message, permission}, and a session.settings.onChange subscription is rejected at subscribe time with the same code. System miniapps pass without declaring. Only the Wi-Fi ADB control and actions declared visibility: "system" are reserved for system miniapps and reject other callers with NOT_PERMITTED. Setting type: "dashboard" or alwaysOn: true does not grant any of these. session.actions.invoke and session.actions.list are not gated: see Actions.

Miniapps that declare MANAGE_MINIAPPS can discover other miniapps and control their lifecycle, miniapps that declare PLATFORM_SETTINGS can read and write host settings, and system miniapps can use a small set of privileged device controls. Invoking the actions other miniapps expose is open to every miniapp and documented here because the error surface is shared.

Discover and control miniapps

session.miniapps lists installed miniapps and starts or stops them. It needs MANAGE_MINIAPPS. session.miniapps.hasPermission is true when the manifest declares it.

// 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.glassly.todo");
await session.miniapps.stop("com.glassly.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.
`stop(packageName)`	`Promise<void>`	Stop a running miniapp.

session.miniapps.stopSelf() is not permission-gated. Any miniapp can call it to stop itself; the host tears the background context down shortly after. It’s fire-and-forget with no reply, so flush any pending work first. Each list entry can include hidden?: boolean and system?: boolean. Leave out entries with either set when building a glasses menu: hidden means the wearer took the miniapp off the home grid, and system marks the host’s built-in phone pages (Store, Settings, Glasses Mirror and the like) and dashboards. Older hosts omit both.

Platform settings

session.settings reads and writes an allowlisted subset of the host’s settings. It needs PLATFORM_SETTINGS; session.settings.hasPermission is true when the manifest declares it. Writes go through the same persistence, server sync, and applicable Bluetooth sync as the Glassly App’s settings screens. For your own miniapp’s preferences, use storage.

const values = await session.settings.getAll(["notifications_enabled", "menu_apps"]);
const off = session.settings.onChange(({key, value}) => {
  console.log(key, value);
});
await session.settings.set("notifications_popups", true);
// later
off();

Method	Returns	Notes
`get<T>(key)`	`Promise<T \| undefined>`	Unknown keys return `undefined`.
`getAll(keys?)`	`Promise<Record<string, unknown>>`	Omit `keys` for all available keys. Unknown keys are omitted.
`set(key, value)`	`Promise<void>`	Writable keys only; values use the host’s JSON shapes.
`onChange(handler)`	Unsubscribe function	Replays every available key’s current value, then sends `{key, value}` changes.

Writable keys are contextual_dashboard, twelve_hour_time, menu_apps, and the notification enable/popup/filter settings. custom_dashboard_enabled and notification_seen_apps are read-only. A dashboard keeps its own look settings in session.storage. The bridge also supplies read-only derived values: phone_active and foreground_app_on_screen (booleans), ring_battery ({connected: boolean, level: number}, with -1 for an unknown level), and active_dashboard (the package name that holds the dashboard role, or null). set rejects unknown keys or missing values with INVALID_ARGUMENT, read-only keys with NOT_PERMITTED, and failed store writes with INTERNAL. Handle missing keys on older hosts; the generic on get<T> does not validate the value at runtime.

Notification app discovery

session.phone.notifications.installedApps() returns Promise<NotificationAppInfo[]> for building a notification filter UI. Each entry is {packageName: string, appName: string, icon: string | null}. Android lists installed apps with base64 PNG icons. iOS cannot enumerate installed apps, so it returns a seeded catalog plus apps the glasses reported posting notifications, without icons. This request needs READ_NOTIFICATIONS.

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. Any miniapp can call it; only actions the target declared with visibility: "system" are restricted to system callers.

const res = await session.actions.invoke(
  "com.glassly.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 action is declared `visibility: "system"` and 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

Platform settings

Notification app discovery

Invoke an action

Privileged device controls

Wi-Fi ADB (Mentra Live)

​Discover and control miniapps

​Platform settings

​Notification app discovery

​Invoke an action

​Privileged device controls

​Wi-Fi ADB (Mentra Live)

Discover and control miniapps

Platform settings

Notification app discovery

Invoke an action

Privileged device controls

Wi-Fi ADB (Mentra Live)