Quickstart

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.

The Glassly Miniapp SDK is in beta. It has not been thoroughly tested yet, so it ships behind a developer toggle in the Glassly App rather than on by default. Open Settings → Debug Settings, enable Miniapp Developer Settings, then return to Settings and open Miniapp Developer Settings. If Debug Settings is hidden, tap the version number at the bottom of Settings ten times to reveal it.These docs describe the SDK as it stands today. Both the SDK and the docs are subject to change, and some of it will change based on what beta testers run into.Please tell us what you hit. File a bug report from inside the Glassly App, post on Discord, or email help@glassly.ai.

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

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 create-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 @glassly/miniapp (the runtime) and @glassly/miniapp-cli (the glassly-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 Glassly 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 "@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 });
  });
});

UI: 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>;
}

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.

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