# The manifest (miniapp.json)

> Declare your miniapp's identity, entry points, permissions, and hardware requirements.

Source: https://docs.glassly.ai/app-devs/core-concepts/miniapp-manifest/

Every miniapp has a `miniapp.json` at its root. It declares who the miniapp is,
where its two layers are built to, what permissions it needs, and what hardware
it requires. The CLI validates it on every `dev`, `pack`, and `release`: bad
values fail on your laptop, not on the phone. The permission and hardware values
it accepts come from the `@glassly/miniapp` version your project installs, so
upgrade the SDK to declare a newly added one; a project on an SDK too old to
provide that list gets an upgrade message.

```json miniapp.json
{
  "$schema": "./node_modules/@glassly/miniapp-cli/schema/miniapp.schema.json",
  "packageName": "com.example.notes",
  "version": "1.0.0",
  "name": "Notes",
  "description": "Hands-free note taking",
  "tagline": "Dictate notes without touching your phone",
  "tags": ["productivity"],
  "icon": "icon.png",
  "type": "standard",
  "sdkVersion": "0.3.0",
  "minHostVersion": "0.3.0",
  "entry": {
    "background": "background/index.js",
    "ui": "ui/index.html"
  },
  "permissions": [
    { "type": "MICROPHONE", "description": "Capture notes you dictate." }
  ],
  "hardwareRequirements": [
    { "type": "DISPLAY", "level": "REQUIRED", "description": "Shows your notes." },
    { "type": "MICROPHONE", "level": "REQUIRED" }
  ]
}
```

## Fields

`packageName`, `version`, `name`, and `hardwareRequirements` are required.
Everything else is optional.

| Field | Type | Notes |
|---|---|---|
| `packageName` | string | Reverse-DNS, e.g. `com.example.notes`. Must match `^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)+$`. Your miniapp's unique identity. |
| `version` | string | Semver, e.g. `1.0.0`. |
| `name` | string | Display name in the launcher and store. |
| `hardwareRequirements` | array | What the glasses must (or may) have. See below. **Required.** |
| `description` | string | Short summary. Shown on the store page unless you override it in the Developer Console. |
| `tagline` | string | One line under the name on store cards, at most 80 characters. |
| `releaseNotes` | string | What changed in this version, at most 500 characters. Shown in the store's version history, where users can go back to an earlier published release. |
| `tags` | array | Up to 5 lowercase slugs used as store filter chips. Known tags: `productivity`, `communication`, `navigation`, `ai`, `games`, `developer`, `media`. Other slugs are accepted and shown as typed. |
| `icon` | string | Path to the icon, relative to the project root (e.g. `icon.png`). Packed into the bundle and extracted as the store icon (square PNG, at least 64px, at most 512 KB). |
| `type` | string | `"standard"` (background + on-demand UI, the default), `"background"` (background-only, no UI layer), or `"dashboard"` (may hold the dashboard role; see [Display](https://docs.glassly.ai/app-devs/core-concepts/display/layouts.md#dashboard-view)). |
| `alwaysOn` | boolean | Default Always On preference, `false` when omitted. Starts at host launch and keeps its background running when its app switcher card is dismissed. The wearer can override it and stop the miniapp. |
| `sdkVersion` | string | The `@glassly/miniapp` version you built against. |
| `minHostVersion` | string | Minimum Glassly App version required to run this miniapp. Older Glassly Apps get your newest earlier release that fits them, so raising it doesn't cut off users who haven't updated. When no release fits, the Glassly Miniapp Store shows the listing as unavailable. |
| `entry` | object | `{ "background": "background/index.js", "ui": "ui/index.html" }`: built output paths for the two layers. Declaring `entry.background` is what makes a miniapp two-layer (and gives you `session.ui`). |
| `port` | number | Dev-server starting port (default `3000`). Used only by `dev`; `release` picks its own port. |
| `permissions` | array | Phone permissions you ask for. See below. |
| `actions` | array | Capabilities other miniapps / Glassly AI can invoke. See [Interop & Actions](https://docs.glassly.ai/app-devs/core-concepts/miniapp-interop.md). |
| `widgets` | array | Dashboard widgets your miniapp provides. See [Widgets](#widgets) below. |

The `$schema` line points editors at the JSON Schema shipped with the CLI, so you
get autocomplete and validation as you type. `@glassly/create-miniapp` adds it for
you; you can also print the schema with `glassly schema print`.

## Always On miniapps

Set `"alwaysOn": true` for a miniapp intended to keep running, such as an
assistant or notification listener. The host starts it at launch; dismissing
its app switcher card or closing its UI leaves the background running. Only
Always On miniapps start at launch: one that merely happened to be running when
the Glassly App closed comes back stopped. The wearer can stop it from the
switcher's Always On controls, and their per-miniapp Always On choice overrides
the manifest default. Always On does not grant system privileges or prevent
explicit stops. Use `alwaysOn`, not the earlier `persistent` or `alwaysRun`
fields.

`type: "dashboard"` makes a miniapp eligible to hold the dashboard role: one
dashboard runs at a time, and the running one holds it. Starting a dashboard
stops the one running, and only one dashboard can be Always On. It grants no
privileges by itself. A dashboard that needs to list or start miniapps or edit
platform settings declares `MANAGE_MINIAPPS` and `PLATFORM_SETTINGS` like any
other miniapp.

## Permissions

Each entry is `{ "type": "...", "required"?: boolean, "description"?: "..." }`.
The optional description is shown to the user in the OS permission prompt.

Every permission is asked when the miniapp launches, the required ones first.
The miniapp doesn't open until the user grants those. `"required": false`
makes one optional: it's asked after the required ones, the user can skip it,
and the miniapp opens either way. An optional permission stops being asked at
launch once the user has answered its OS prompt.

| `type` | Grants |
|---|---|
| `MICROPHONE` | Audio input, transcription, translation |
| `DISPLAY_MIRROR` | Query and preview the global intended glasses display via [session.mirror](https://docs.glassly.ai/app-devs/core-concepts/display/mirror.md), including other miniapps' content |
| `CAMERA` | Photos and video on camera glasses |
| `CALENDAR` | Calendar events via `session.phone.calendar` |
| `LOCATION` | GPS via `session.location` (and `session.navigation` / `session.phone.heading`) |
| `BACKGROUND_LOCATION` | Location while the user isn't in your miniapp |
| `READ_NOTIFICATIONS` | Phone notifications and the notification app list via `session.phone.notifications` |
| `POST_NOTIFICATIONS` | Posting notifications into the notification feed via `session.phone.notifications.post` |
| `API_KEYS` | [User-supplied provider API keys](https://docs.glassly.ai/app-devs/core-concepts/keys.md) via `session.keys.get()` (anthropic, gemini, openai, deepseek, elevenlabs, mapbox) |
| `MEMORY` | [The user's shared memory timeline](https://docs.glassly.ai/app-devs/core-concepts/memory.md) via `session.memory` |
| `AI` | [LLM completions through the platform](https://docs.glassly.ai/app-devs/core-concepts/ai.md) via `session.ai.complete()` |
| `SPEAKERS` | Resolving enrolled-speaker ids to display names via `session.speakers` |
| `MANAGE_MINIAPPS` | Listing, starting, and stopping other miniapps via `session.miniapps`. No OS prompt; shown in the Store listing. See [System Miniapp APIs](https://docs.glassly.ai/app-devs/reference/system-apis.md) |
| `PLATFORM_SETTINGS` | Reading and writing allowlisted host settings via `session.settings`. No OS prompt; shown in the Store listing. See [System Miniapp APIs](https://docs.glassly.ai/app-devs/reference/system-apis.md#platform-settings) |
| `HOST_WIDGETS` | Listing, placing and driving other miniapps' dashboard widgets via `session.widgets`. No OS prompt; shown in the Store listing. See [Provide a dashboard widget](https://docs.glassly.ai/app-devs/core-concepts/widgets.md#host-widgets) |

Declaring a permission is not the same as the user granting it.
`session.permissions.has(type)` reports what you **declared** in the manifest, not
the live OS grant. If the user denied the OS prompt, your subscriptions
receive nothing. See [Permissions](https://docs.glassly.ai/app-devs/core-concepts/permissions.md).

## Hardware requirements

Each entry is `{ "type": "...", "level": "...", "description"?: "..." }`.

| `type` | `LEVEL` |
|---|---|
| `CAMERA`, `DISPLAY`, `MICROPHONE`, `SPEAKER`, `IMU`, `BUTTON`, `LIGHT`, `WIFI` | `REQUIRED` or `OPTIONAL` |

- `REQUIRED`: glasses without this hardware can't install the miniapp (it's
  hidden in the Glassly Miniapp Store and launcher on incompatible devices).
- `OPTIONAL`: incompatible glasses still run the miniapp, in a degraded state.

`MICROPHONE` means that the miniapp needs audio input. Glassly satisfies this
requirement with the connected glasses microphone when one is available and
falls back to the phone microphone otherwise. A miniapp that requires audio is
therefore compatible with glasses such as the Vuzix Z100 that do not have an
onboard microphone.

## Actions

Each entry is `{ "id": "...", "description": "...", "visibility"?: "...",
"parameters"?: {...}, "outputSchema"?: {...} }`. `visibility` is `"public"` by
default, meaning any installed miniapp can invoke the action; `"system"`
restricts it to system miniapps such as Glassly AI, which also hides it from
`session.actions.list()` for everyone else.

```json
"actions": [
  { "id": "add_todo", "description": "Add an item to the user's todo list." },
  { "id": "wipe_all", "description": "Delete every item.", "visibility": "system" }
]
```

See [Interop & Actions](https://docs.glassly.ai/app-devs/core-concepts/miniapp-interop.md) for the full
field rules and how to handle a call.

## Widgets

Each entry is `{ "id": "...", "name": "...", "sizes": [...], "defaultSize"?: "..." }`.
It declares a card your miniapp can put on the glasses dashboard.

```json
"widgets": [
  { "id": "now_playing", "name": "Now Playing", "sizes": ["SM", "MD", "LG", "EX"], "defaultSize": "MD" }
]
```

`id` is unique within the miniapp (`^[a-z][a-z0-9_]*$`, at most 64 characters),
`sizes` is a list without repeats from `XS`, `XSM`, `SM`, `MD`, `LG` and `EX`
with at least one card size, `defaultSize` must be one of its card sizes, the
first when omitted, and `EX` lets a tap open the widget full screen (the wearer
can turn that off per widget). Declaring a widget
needs no permission. Serving one is covered in
[Provide a dashboard widget](https://docs.glassly.ai/app-devs/core-concepts/widgets.md). Hosting other
miniapps' widgets needs `HOST_WIDGETS`.

## Editing the manifest

You can edit `miniapp.json` by hand, or use the CLI's guided commands:

```bash
glassly manifest                  # interactive wizard
glassly permission add MICROPHONE
glassly hardware add DISPLAY REQUIRED
```

See the [CLI reference](https://docs.glassly.ai/app-devs/reference/cli.md) for all of them.
