App Lifecycle Overview

How It Works

Lifecycle Stages

1. Registration (One-Time Setup)

Package Name: Unique identifier (e.g., com.example.myapp)
Webhook URL: Where MentraOS sends session requests
API Key: Secret for authentication
Permissions: What device data your app needs

2. Session Start

When a user starts your app:

MentraOS Cloud sends HTTP POST to your webhook URL
Webhook includes sessionId and userId
Your server establishes WebSocket connection
Your server sends connection init message
Cloud confirms connection

// The SDK handles this automatically
protected async onSession(session: AppSession, sessionId: string, userId: string) {
  // Your app logic starts here
  session.logger.info('Session started!');
}

3. Active Session

While the session is active:

Subscribe to events (transcription, button presses, etc.)
Handle incoming events with callbacks
Update the display using layouts
Access device capabilities

protected async onSession(session: AppSession, sessionId: string, userId: string) {
  // Subscribe to voice transcription
  session.events.onTranscription((data) => {
    session.logger.info('User said:', data.text);
  });

  // Update display
  session.layouts.showTextWall('App is running!');
}

4. Session End

Session ends when:

User stops the app
Glasses disconnect
Network error occurs
Your server disconnects

protected async onStop(sessionId: string, userId: string, reason: string) {
  // Clean up resources
  session.logger.info('Session ended:', reason);
}

Key Components

Component	Purpose
AppServer	Your server class that handles webhooks and connections
AppSession	Represents one user’s active connection to your app
WebSocket	Real-time bidirectional communication channel
Events	Data streams from glasses (voice, sensors, buttons)
Layouts	What displays on the glasses screen

Important Notes

Sessions are isolated per user. Each user who starts your app gets their own AppSession instance with a unique userId.

Next Steps

Learn About AppServer

Understand the server class that powers your app

Learn About AppSession

Work with individual user sessions

Handle Events

Subscribe to real-time data from glasses

Set Permissions

Control what data your app can access

Quick Example

Here’s a minimal MentraOS app:

import { AppServer, AppSession } from '@mentraos/sdk';

class HelloGlasses extends AppServer {
  protected async onSession(session: AppSession, sessionId: string, userId: string) {
    // Show greeting
    session.layouts.showTextWall('Hello from MentraOS!');

    // Listen for voice input
    session.events.onTranscription((data) => {
      if (data.isFinal) {
        session.layouts.showTextWall(`You said: ${data.text}`);
      }
    });
  }

  protected async onStop(sessionId: string, userId: string, reason: string) {
    console.log(`Session ${sessionId} ended: ${reason}`);
  }
}

// Start server
const server = new HelloGlasses({
  packageName: 'com.example.helloglasses',
  apiKey: process.env.MENTRAOS_API_KEY!,
  port: 3000
});

server.start();

This app greets the user and echoes back their voice input. Simple, but it demonstrates the complete lifecycle.

Getting Started

Core Concepts

SDK Reference

App Lifecycle Overview

How It Works

Lifecycle Stages

1. Registration (One-Time Setup)

2. Session Start

3. Active Session

4. Session End

Key Components

Important Notes

Next Steps

Learn About AppServer

Learn About AppSession

Handle Events

Set Permissions

Quick Example

​How It Works

​Lifecycle Stages

​1. Registration (One-Time Setup)

​2. Session Start

​3. Active Session

​4. Session End

​Key Components

​Important Notes

​Next Steps

Learn About AppServer

Learn About AppSession

Handle Events

Set Permissions

​Quick Example

How It Works

Lifecycle Stages

1. Registration (One-Time Setup)

2. Session Start

3. Active Session

4. Session End

Key Components

Important Notes

Next Steps

Quick Example