The manifest (miniapp.json)

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.The developer tools are available in the Mentra App under Settings → Miniapp Developer Settings.Share feedback with an in-app bug report, on Discord, or by email at help@mentra.glass.

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.

miniapp.json

{
  "$schema": "./node_modules/@mentra/miniapp-cli/schema/miniapp.schema.json",
  "packageName": "com.example.notes",
  "version": "1.0.0",
  "name": "Notes",
  "description": "Hands-free note taking",
  "icon": "icon.png",
  "type": "standard",
  "sdkVersion": "0.3.0",
  "minHostVersion": "1.42.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

Required: packageName, version, name, hardwareRequirements. 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.
`icon`	string	Path to the icon, relative to the project root (e.g. `icon.png`). Packed into the bundle.
`type`	string	`"standard"`.
`sdkVersion`	string	The `@mentra/miniapp` version you built against.
`minHostVersion`	string	Minimum Mentra App version required to run this miniapp.
`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	Runtime permissions you request. See below.
`actions`	array	Capabilities other miniapps / Mentra AI can invoke. See Interop & Actions.

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

Permissions

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

`type`	Grants
`MICROPHONE`	Audio input, transcription, translation
`CAMERA`	Photos and video on camera glasses
`CALENDAR`	Calendar events via `session.phone.calendar`
`LOCATION`	GPS via `session.location` (and `session.navigation` / `session.heading`)
`BACKGROUND_LOCATION`	Location while the user isn’t in your miniapp
`READ_NOTIFICATIONS`	Phone notifications via `session.phone.notifications`
`POST_NOTIFICATIONS`	Posting notifications

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 simply receive nothing. See Permissions.

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 (when Store distribution becomes available, it will be hidden in the Mentra 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. MentraOS 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.

Editing the manifest

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

mentra-miniapp manifest                  # interactive wizard
mentra-miniapp permission add MICROPHONE
mentra-miniapp hardware add DISPLAY REQUIRED

See the CLI reference for all of them.

Getting Started

Core Concepts

UI Layer

Display

Audio & Speech

Sensors & Input

Camera

Phone & System

Data

Reference

The manifest (miniapp.json)

Fields

Permissions

Hardware requirements

Editing the manifest

​Fields

​Permissions

​Hardware requirements

​Editing the manifest

Fields

Permissions

Hardware requirements

Editing the manifest