Quickstart

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].

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.

Step 1: Install the Glassly App

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

Step 2: Scaffold a project

bunx @glassly/create-miniapp my-miniapp

The scaffolder asks for a project name, your package prefix (the reverse-DNS prefix on your developer org in the Developer Console, like com.example), 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 @glassly/miniapp (the runtime) and @glassly/cli (the glassly command) 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 Glassly App, go to Settings → Miniapp Developer Settings → Scan Miniapp QR Code and scan the QR from your terminal.

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

The background layer owns the session and all glasses logic:

src/background/index.ts

import { registerMiniapp } from "@glassly/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 Glassly" },
    ]);
  });

  // 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 });
  });
});

The UI layer is a normal React app that talks to the background over glassly. It has no direct hardware access:

src/ui/App.tsx

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

The shared channels file is 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.

Ship it

Pack a release and put it in front of users.

Getting Started

Core Concepts

UI Layer

Display

Audio & Speech

Sensors & Input

Camera

Phone & System

Data

Reference

Step 1: Install the Glassly 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

Ship it

​Step 1: Install the Glassly 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

Ship it

Step 1: Install the Glassly App

Step 2: Scaffold a project

Step 3: Start the dev server

Step 4: Load it on your phone

Understanding the starter

Next steps