Skip to main content
Status: preview (Phase 1). The Mentra OEM Integration Engine covers the full Phase-1 surface documented below. Firmware OTA and the media gallery are intentionally deferred to a later phase. The runtime is not yet packaged for external install — reach out to help@mentra.glass to integrate today.

What it is

The Mentra OEM Integration Engine is the API an OEM host app (the phone-side app that talks to your glasses) calls to run MentraOS. It ships as the @mentra/engine module and exposes a single namespaced object, engine:
The dividing line:
  • The host owns UI, navigation, and login. Your screens, your router, your auth.
  • The engine owns the runtime and the device. Connection, device state, wifi, on-device speech models, the display pipeline, the miniapp runtime.
So an OEM builds its own UI and calls engine.<domain>.<method>() for everything device- and runtime-related. The engine is device-agnostic: the same calls work across glasses models.

Lifecycle

The host hands the engine its auth + config once, then starts it.
auth.getSubjectToken() is the only must-have seam — the host owns login and returns a fresh token on demand; the engine owns everything downstream.

engine.glasses

Connection actions, a curated status/info read-model, capabilities, version, and the discrete input events.

Connection

Status & info (read-models)

status() returns a snapshot projected from the runtime’s glasses store, in a stable shape that doesn’t leak the internal store layout:

Input events

Every on*() returns an unsubscribe function.

engine.glasses.wifi

connect() propagates the bluetooth layer’s coded errors (bluetooth_powered_off, request_timeout, …) unchanged, so your UI keeps its own error mapping.

engine.glasses.settings

Keyed device settings (brightness, head-up angle, dashboard, camera/button, sensing, …). set() persists and auto-syncs to the connected glasses.
available() is the authoritative list at runtime (it varies by model/capabilities). The current keys, their types, and defaults:
Device identity (paired-device id/name/address, controller address) and internal runtime flags (e.g. STT-fallback state) are intentionally not in this surface — read the connected device via engine.glasses.info().

engine.pairing

First-time glasses discovery + pairing. (Reconnecting the already-paired default is engine.glasses.connectDefault().)

engine.speech

On-device STT/TTS model management.

engine.display.mirror

A typed read facade for a phone-side preview of the glasses screen.

engine.session

The cloud (cloud-v2) live-session surface. engine owns the cloud client — it constructs it from engine-owned transports + the auth you passed to configure() — so this reads the session it manages.
status is one of connected | connecting | reconnecting | disconnected; audioTransport is udp | ws | offline | none.

engine.settings

Typed keyed user settings over the engine-owned settings store.

engine.reports

Bug report and feedback submission. The OEM writes its own report screen, trigger labels, rating controls, and screenshot picker UX; engine owns runtime context collection, recent phone logs, Cloud V2 submission, artifact upload, dedupe, and glasses notification.

engine.dev

Developer/debug surface — backend + cloud-v2 URL overrides, reconnect, version gate.

engine.permissions

OS permissions — the raw check/request ops (your UI adds the rationale dialogs).
Feature keys: microphone · camera · calendar · location · background_location · bluetooth · phone_state · post_notifications.

engine.phoneNotifications

Forward phone notifications to the glasses, with a per-app blocklist. Android-only (getters return safe defaults on iOS).

engine.notifications

Inbound alerts engine→host — conditions engine detects, your UI renders.

engine.miniapps

Miniapp lifecycle. The miniapp WebView is a host component — engine ships the bridge primitives (buildMiniappGlobalsScript, buildMentraUiShim, the MentraJS router), exported from @mentra/engine directly; your app mounts the <WebView> and wires it to those. This facade is the lifecycle half.
install takes a miniapp URL (the HTTPS base that serves miniapp.json). It fetches miniapp.json, answering the miniapp server’s sign-in challenge with that package’s token, checks that the URL’s domain owns the package name, registers the URL in Core’s registry, then calls your confirm(preview) to show an install sheet (omit it for a headless install), checks the phone can run the miniapp (its minHostVersion and sdkVersion), and downloads, verifies and installs its ZIP. A miniapp’s hardwareRequirements describe the glasses and never stop an install or an update: the preview’s missingHardware lists the required hardware the paired glasses (or none) lack, for the sheet to show, as “Needs glasses with a camera.” opened means it was already installed from that URL. A failure throws InstallMiniappError, whose code is one of not_a_miniapp, domain_mismatch, archived, needs_newer_app, access_denied, age_restricted, network, cancelled, integrity or signature_invalid. A URL at a local-network address (localhost, a private IPv4 or IPv6 address, or a .local name), such as the one mentra dev prints, installs as a development build, over HTTP or HTTPS, where the deployment allows miniapp development. Nothing registers it or checks its package name against a domain, so it keeps its data apart from any other install of that name, its miniapp tokens are marked as a local build’s (a backend accepts them only when it allows local builds), it never gets system privileges, and it never updates from its URL; its development server reloads it instead. Only a person installs one: a system or assignment install of a local URL fails with not_a_miniapp. The preview’s local is true: show “From your local network” with the address. Every install registers its URL unless config.requireRegistry is false. The engine’s update checks also ask Core which installed URLs are archived, and never update those; installed copies keep running. Off, the engine installs any miniapp URL without registering it and asks Core nothing; the domain rule still applies. A host app that turns it off answers to the app stores’ rules itself. Pass config.isHostLink(url) to name your own app’s links: its URL schemes and the addresses it claims as app links. A miniapp’s session.system.openUrl never opens them, so no miniapp can open your install sheet, your sign-in callbacks or anything else your link handling does. Refuse the same links in the miniapp WebView you host. Set config.hostAgeRating to your app’s own App Store age rating, for example "12+". A miniapp whose ageRating is above it installs or opens only for a person whose declared age is old enough. The first time that comes up, the engine calls ui.askDeclaredAge() (resolve the whole number of years the person gives, or null when they cancel) and keeps the answer, with the date, on their Core account. It never sends it to a miniapp. When the gate stops a miniapp the person is installing or opening, the engine calls ui.showAgeRestricted(notice) so you can say why. An install with a sheet is checked before confirm; a headless install is checked when the miniapp first opens. Without hostAgeRating, nothing is gated. onUpdatePrompt is how the host renders the question before an update closes a running miniapp. The engine decides when a prompt may appear: only while the app is in the foreground, one at a time, and at most once a day per miniapp. If the update fails after the user accepts, the engine starts the installed version again and calls onUpdateFailed.

engine.stores.* — escape hatch (not the OEM contract)

The raw device-state stores are also exposed under engine.stores (glasses, display, core, connection, gallerySync, cloudClientStatus, settings) so the first-party Mentra App can keep using them directly during migration.
engine.stores.* is a Mentra-app convenience, not the OEM contract. It exposes the internal store shape, which can change. OEMs should use the typed facades above; prefer a facade wherever one exists.

What the host provides

The boundary is small and explicit: the host provides its UI, its login, and optional config — engine owns the entire runtime. The only required seam is auth.getSubjectToken (passed to configure()); engine owns token exchange, refresh, storage, the cloud client, glasses/BLE, settings, speech, display, and the miniapp runtime from there. Native peer packages. The engine declares its native dependencies as peer dependencies, so your app installs them (see peerDependencies in @mentra/engine’s package.json). expo-secure-store (~55.0.14) is required: the engine keeps Mentra Core sign-in credentials in the iOS Keychain and the Android Keystore through it.
You may see internal configureRuntime(...) wiring in the first-party Mentra App — that’s transitional scaffolding for migrating Mentra’s own screens, not part of the OEM contract. It deletes itself as each domain lands in engine. An OEM only ever calls configure({auth, config?}) + start().