# Quickstart

> Scaffold a Glassly miniapp and run it on your phone in a few minutes.

Source: https://docs.glassly.ai/app-devs/getting-started/quickstart/

This Quickstart goes from zero to a miniapp running on your glasses. You need a
phone, [Bun](https://bun.sh/docs/installation), and basic TypeScript. You can do
the whole thing without glasses: the display just won't have anywhere to draw. To
see the display without glasses, run the project in the
[Simulator](https://docs.glassly.ai/app-devs/getting-started/simulator.md).

Building a mobile app that connects directly to glasses over Bluetooth? Use the
[Bluetooth SDK Quickstart](https://docs.glassly.ai/bluetooth-sdk/quickstart.md) instead.

No phone or glasses at hand? After Step 2, run `glassly sim` to use the
[Simulator](https://docs.glassly.ai/app-devs/getting-started/simulator.md) on your computer instead.

### Step 1: Install the Glassly App

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

### Step 2: Install the CLI and scaffold a project

```bash
bun add -g @glassly/cli
bunx @glassly/create-miniapp my-miniapp
```

The scaffolder asks for a project name and your package prefix (the reverse-DNS
prefix on your developer org in the Developer Console, like `com.example`), then
generates a ready-to-run two-layer project: a small live-captions miniapp.

```bash
cd my-miniapp
bun install
```

`bun install` pulls in [`@glassly/miniapp`](https://www.npmjs.com/package/@glassly/miniapp)
(the runtime) and a project copy of [`@glassly/cli`](https://www.npmjs.com/package/@glassly/cli).
Inside the project, the global `glassly` command runs that copy, so every project
uses the tooling version its `package.json` pins.

### Step 3: Start the dev server

```bash
glassly 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 can be on any network. The QR carries an [iroh](https://www.iroh.computer)
ticket, so the Glassly App reaches your laptop directly or through a relay, and a
saved dev miniapp reconnects after you restart `glassly dev`. Older Glassly App builds
only use the LAN address in the QR, so they need the **same Wi-Fi network**.

The miniapp installs and starts. Speak and your words appear on the glasses and
on the miniapp's phone page. On the glasses, tap to pause, swipe to scroll back
through earlier lines, and hold to hear the shown line read aloud.

### Or: run it on your computer

```bash
glassly sim
```

This opens the [Simulator](https://docs.glassly.ai/app-devs/getting-started/simulator.md): the glasses
display, controls for the touch bar and head gestures, and the phone page side
by side. Type a sentence under **Speech heard by the glasses** and press **Say**:
it appears as a caption on the simulated display and the phone page. It reloads on save too, so you can build most of a
miniapp here and check it on glasses before you ship.

### Staying up to date

```bash
glassly update
```

This moves the project's `@glassly/miniapp`, `@glassly/cli`, and
`@glassly/miniapp-cli` to the newest release on the channel the project already
uses, runs `bun install`, and upgrades the global `glassly` too. The CLI checks
npm once a day and prints a notice when something is behind. Set
`GLASSLY_NO_UPDATE_CHECK=1` to turn the check off. It is already off in CI.

## Understanding the starter

```
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
    ├── background/scene.ts   # state → glasses scene, a pure function with tests
    ├── ui/App.tsx            # the phone page (React + Tailwind)
    └── shared/channels.ts    # typed messages between the two layers
```

The background owns the `session`. It subscribes to speech and gestures, keeps
the history in storage, and redraws the glasses:

```typescript src/background/index.ts
registerMiniapp<Channels>((session) => {
  session.transcription.on((data) => {
    if (data.isFinal) lines = [...lines, data.text]
    else live = data.text
    update() // redraw the glasses, push state to the phone page
  })

  session.input.onTouch("single_tap", () => setPaused(!paused))
  session.input.onTouch(["swipe_up", "swipe_down"], (data) => scroll(data.kind))
  session.input.onTouch("long_press", () => session.speaker.speak(shownLine()))

  session.on("ready", async () => {
    lines = JSON.parse((await session.storage.get("lines")) ?? "[]")
    update()
  })
})
```

`display.render()` takes the whole frame each time. Elements with stable ids
update in place, and a `transition` animates the change on glasses that can:

```typescript src/background/scene.ts
return [
  { type: "text", id: "caption", box: { x: 16, y: 56, w: 544, h: 196 }, text: caption },
  { type: "circle", id: "mic", box: { x: 16, y: 14, w: 22, h: 22, anchor: "top-right" }, style: { fill: listening } },
  { type: "rect", id: "thumb", box: { x: thumbX, y: 270, w: thumbW, h: 8 }, style: { fill: true },
    transition: { durationMs: 200 } },
]
```

The phone page is a normal React app that talks to the background through the
typed channels in `src/shared/channels.ts`. It has no direct hardware access:

```tsx src/ui/App.tsx
useEffect(() => glassly.on("state", setState), []);
<button onClick={() => glassly.send("set-paused", { paused: !state.paused })}>Pause</button>
```

## Next steps

- [Two-layer architecture](https://docs.glassly.ai/app-devs/core-concepts/two-layer-architecture.md)
How background and UI work and communicate.
- [The session](https://docs.glassly.ai/app-devs/core-concepts/session.md)
Every capability you can reach on the glasses.
- [The manifest](https://docs.glassly.ai/app-devs/core-concepts/miniapp-manifest.md)
Permissions, hardware requirements, and entry points.
- [Ship it](https://docs.glassly.ai/app-devs/getting-started/distribution.md)
Pack a release and put it in front of users.
- [Simulator](https://docs.glassly.ai/app-devs/getting-started/simulator.md)
Run and script a miniapp with no phone or glasses.
- [AI IDE integration](https://docs.glassly.ai/app-devs/getting-started/ai-ide-integration.md)
Let a coding agent build, run, and check your miniapp.
