Quickstart

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.To enable miniapp development, open Settings in the Mentra App and tap the version number at the bottom ten times. Then open Debug Settings, turn on Miniapp Developer Settings, return to Settings, and open Miniapp Developer Settings.Share feedback with an in-app bug report, on Discord, or by email at help@mentra.glass.

This Quickstart goes from zero to a miniapp running on your glasses. You need a phone, Bun, and basic TypeScript. You can do the whole thing without glasses: the display just won’t have anywhere to draw.

Building a mobile app that connects directly to glasses over Bluetooth? Use the Bluetooth SDK Quickstart instead.

Looking for the @mentra/sdk cloud SDK? Apps used to be cloud-hosted servers built with @mentra/sdk. They’re now built on-device with the Mentra Miniapp SDK (@mentra/miniapp), which these docs cover. The older cloud SDK docs live at mentraglass.com/legacy.

Step 1: Install the Mentra App

Install the Mentra App on your Android or iPhone from MentraGlass.com/OS, sign in, and connect your glasses (if you have them).

Step 2: Scaffold a project

bunx create-mentra-miniapp my-miniapp

The scaffolder asks for a project name and the kind of glasses you’re targeting (display glasses like Even Realities G1/G2 and Vuzix Z100, or camera glasses like Mentra Live), then generates a ready-to-run two-layer project.

cd my-miniapp
bun install

bun install pulls in @mentra/miniapp (the runtime) and @mentra/miniapp-cli (the mentra-miniapp tooling) automatically.

Step 3: Start the dev server

bun dev

This validates your miniapp.json, builds both layers, serves them over your LAN, and prints a QR code plus a miniapp://dev?... URL. It hot-reloads on save and forwards the miniapp’s console logs back to your terminal.

Step 4: Load it on your phone

In the Mentra App, go to Settings → Miniapp Developer Settings → Scan Miniapp QR Code and scan the QR from your terminal. If Miniapp Developer Settings is hidden, open Settings → Debug Settings, enable Miniapp Developer Settings, then return to Settings. If Debug Settings is hidden, tap the version number at the bottom of Settings ten times to reveal it.

Your phone and your laptop must be on the same Wi-Fi network. bun dev watches for Wi-Fi changes and reprints the QR if your LAN IP moves.

The miniapp installs and starts. In the starter project, pressing a glasses button shows text on the display, and opening the miniapp’s UI tile shows a round-trip latency demo between the UI and background layers.

Understanding the starter

A scaffolded miniapp has two entry points wired together by a shared, typed channel registry:

my-miniapp/
├── miniapp.json              # manifest: package name, permissions, hardware, entries
├── build.ts                  # bundles both layers
└── src/
    ├── background/index.ts   # always-on glasses logic: owns the session
    ├── ui/                   # the on-demand WebView (React)
    └── shared/channels.ts    # typed messages between the two layers

Background: owns the session and all glasses logic:

src/background/index.ts

import { registerMiniapp } from "@mentra/miniapp/background";
import "../shared/channels";

registerMiniapp((session) => {
  session.input.onButtonPress(() => {
    // render() replaces the whole frame — a full-canvas text element here.
    // Box coordinates are raw device px from session.capabilities.display.
    const d = session.capabilities?.display;
    session.display.render([
      { type: "text", id: "hello", box: { x: 0, y: 0, w: d?.width ?? 576, h: d?.height ?? 288 }, text: "Hello from MentraOS" },
    ]);
  });

  // Reply to a "ping" from the UI with a "pong".
  session.ui.on("ping", ({ at }) => {
    session.ui.send("pong", { at: Date.now(), roundtripMs: Date.now() - at });
  });
});

UI: a normal React app that talks to the background over mentra. It has no direct hardware access:

src/ui/App.tsx

export function App() {
  useEffect(() => mentra.on("pong", ({ roundtripMs }) => { /* update UI */ }), []);
  return <button onClick={() => mentra.send("ping", { at: Date.now() })}>Ping</button>;
}

Shared channels: the single source of truth for what flows between the two layers, enforced at compile time:

src/shared/channels.ts

export interface Channels {
  ping: { at: number };                          // UI → background
  pong: { at: number; roundtripMs: number };     // background → UI
}

Next steps

Two-layer architecture

How background and UI work and communicate.

The session

Every capability you can reach on the glasses.

The manifest

Permissions, hardware requirements, and entry points.

Test a release

Pack a release and install it on local test devices.

Getting Started

Core Concepts

UI Layer

Display

Audio & Speech

Sensors & Input

Camera

Phone & System

Data

Reference

Step 1: Install the Mentra App

Step 2: Scaffold a project

Step 3: Start the dev server

Step 4: Load it on your phone

Understanding the starter

Next steps

Two-layer architecture

The session

The manifest

Test a release

​Step 1: Install the Mentra App

​Step 2: Scaffold a project

​Step 3: Start the dev server

​Step 4: Load it on your phone

​Understanding the starter

​Next steps

Two-layer architecture

The session

The manifest

Test a release

Step 1: Install the Mentra App

Step 2: Scaffold a project

Step 3: Start the dev server

Step 4: Load it on your phone

Understanding the starter

Next steps