Skip to main content

​
Installation

Install the MentraOS SDK using Bun: 
bun add @mentraos/sdk

​
Basic Concepts

The MentraOS SDK provides two main classes:

AppServer

Base class you extend to create your app server. Handles webhook registration and session lifecycle.

AppSession

Manages the connection to a specific user session. Created automatically when users start your app.
Important: Apps should extend AppServer and override the onSession method. The sessionId parameter follows the format "userId-packageName" (e.g., "[email protected]").

​
Creating an App Server

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

// Extend AppServer to create your app
class MyAppServer extends AppServer {
  // Override onSession to handle new user sessions
  protected async onSession(
    session: AppSession,
    sessionId: string,  // Format: "userId-packageName" 
    userId: string      // User's email address
  ): Promise<void> {
    // Your app logic goes here
    console.log(`New session ${sessionId} for user ${userId}`);
  }
}

// Create instance with configuration
const server = new MyAppServer({
  packageName: 'com.yourcompany.yourapp',  // Your app's unique identifier
  apiKey: process.env.MENTRAOS_API_KEY!,    // Your API key from dev portal
  port: 3000,                               // Port to listen on (default: 7010)
  publicDir: './public'                     // Optional: static files directory
});

​
Handling Sessions

When a user starts your app, your onSession method is called: 
protected async onSession(
  session: AppSession,    // Session instance for this user
  sessionId: string,      // Session ID (format: "userId-packageName")
  userId: string          // User's email address
): Promise<void> {
  console.log(`New session ${sessionId} for user ${userId}`);
  
  // Set up event handlers
  session.events.onTranscription((data) => {
    // Handle speech-to-text
  });
  
  session.events.onButtonPress((data) => {
    // Handle button presses
  });
  
  // Show initial UI
  await session.layouts.showTextWall('Welcome!');
}

​
Session Lifecycle

1

User starts app

User says “Start [app name]” or taps in the mobile app
2

Cloud sends webhook

MentraOS Cloud sends a webhook to your server
3

Session created

Your onSession handler is called with an AppSession
4

Real-time connection

AppSession connects via WebSocket for real-time data
5

Session ends

User stops app or connection is lost

​
TypeScript Support

The SDK is written in TypeScript and provides full type definitions: 
import { 
  AppServer,
  AppSession,
  TranscriptionData,
  ButtonPress,
  PhotoData,
  LocationUpdate
} from '@mentraos/sdk';

// All types are available for your use

​
Environment Variables

Recommended environment variables: 
# Required
MENTRAOS_API_KEY=your_api_key_here

# Optional
PORT=3000
LOG_LEVEL=info

​
Project Structure

A typical MentraOS app project: 
my-mentraos-app/
├── src/
│   ├── index.ts        # Main server file
│   ├── server.ts       # Your AppServer class
│   ├── handlers/       # Event handlers
│   └── utils/          # Helper functions
├── public/             # Static assets
├── .env                # Environment variables
├── package.json
├── tsconfig.json       # TypeScript config
└── bun.lockb           # Bun lock file

​
TypeScript Configuration

Use strict TypeScript for better type safety: 
// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "lib": ["ES2022"],
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "allowJs": false,
    "types": ["bun-types"]
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

​
Next Steps

AppSession Reference

Learn about the AppSession class and its methods

Event Handlers

Handle transcriptions, button presses, and more

Display Layouts

Show content on the glasses display

Hardware Modules

Access camera, audio, location, and sensors