​
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
app.onSession((session: MentraSession) => {
  // 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
  • Access device capabilities
app.onSession((session: MentraSession) => {
  // Subscribe to voice transcription
  session.transcription.on((data) => {
    session.logger.info("User said:", data.text);
  });

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

​
4. Session End

Session ends when:
  • User stops the app
  • Glasses disconnect
  • Network error occurs
  • Your server disconnects
app.onStop((session, reason) => {
  // Clean up resources
  console.log("Session ended:", reason);
});
In v3, sessions can also reconnect after a brief transport blip without ending: 
app.onSession((session) => {
  session.onReconnected(() => {
    // Connection restored - subscriptions still active
  });

  session.onStopped((reason) => {
    // Session truly ended - clean up per-user state
  });
});

​
Key Components

ComponentPurpose
MiniAppServerYour server that handles webhooks and connections
MentraSessionOne user’s active connection to your app
Session ManagersTyped interfaces for each capability (transcription, display, camera, etc.)
WebSocketReal-time bidirectional communication between your server and MentraOS Cloud

​
Important Notes

Sessions are isolated per user. Each user who starts your app gets their own MentraSession instance with a unique userId. Nothing leaks between users.

​
Next Steps

MiniAppServer

The entry point for your app

Learn About MentraSession

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 { MiniAppServer, type MentraSession } from "@mentra/sdk";

const app = new MiniAppServer({
  packageName: "com.example.helloglasses",
  apiKey: process.env.MENTRAOS_API_KEY!,
  port: 3000,
});

app.onSession((session: MentraSession) => {
  // Show greeting
  session.display.showTextWall("Hello from MentraOS!");

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

  session.onStopped((reason) => {
    console.log(`Session ended: ${reason}`);
  });
});

await app.start();
This app greets the user and echoes back their voice input. Simple, but it demonstrates the complete lifecycle.