Skip to main content

​
How It Works

​
Lifecycle Stages

​
1. Registration (One-Time Setup)

Register your app in the Developer Console:
  • 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:
  1. MentraOS Cloud sends HTTP POST to your webhook URL
  2. Webhook includes sessionId and userId
  3. Your server establishes WebSocket connection
  4. Your server sends connection init message
  5. 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

ComponentPurpose
AppServerYour server class that handles webhooks and connections
AppSessionRepresents one user’s active connection to your app
WebSocketReal-time bidirectional communication channel
EventsData streams from glasses (voice, sensors, buttons)
LayoutsWhat 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.