This page documents the v2 API. In v3, these managers are accessed directly on the MentraSession object (e.g. session.speaker, session.camera, session.led). See the MentraSession page for the current documentation, or the Migration Guide for all v2 → v3 changes.

​
SettingsManager API Reference

The SettingsManager class provides a type-safe interface for accessing and monitoring App settings. It automatically synchronizes with MentraOS Cloud and provides real-time change notifications.

​
Import

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

export class MyAppServer extends AppServer {
  protected async onSession(session: AppSession, sessionId: string, userId: string): Promise<void> {
    // get the settings manager object
    const settingsManager = session.settings;

    // Get a specific setting value
    const language = settingsManager.get<string>('transcribe_language', 'English');

    // Listen for setting changes
    settingsManager.onValueChange('line_width', (newValue, oldValue) => {
      console.log(`Line width changed from ${oldValue} to ${newValue}`);
      this.updateDisplay(newValue);
    });
  }
}

​
Class: SettingsManager

​
Constructor

The SettingsManager is automatically instantiated by the AppSession. You should not create instances directly. 
class SettingsManager {
  constructor(
    initialSettings: AppSettings = [],
    packageName?: string,
    wsUrl?: string,
    userId?: string,
    subscribeFn?: (streams: string[]) => Promise<void>
  )
}

​
Methods

​
get

Get a setting value. 
get<T = any>(key: string, defaultValue?: T): T
Parameters:
  • key: Setting key to retrieve
  • defaultValue: Default value if setting doesn’t exist or is undefined
Returns: Setting value or default value Example: 
// Get with default value
const fontSize = session.settings.get<number>('font_size', 16);

// Get without default (returns undefined if not found)
const theme = session.settings.get<string>('theme');

​
has

Check if a setting exists. 
has(key: string): boolean
Parameters:
  • key: Setting key to check
Returns: True if the setting exists Example: 
if (session.settings.has('advanced_mode')) {
  // Setting exists
  const enabled = session.settings.get<boolean>('advanced_mode');
}

​
getAll

Get all settings. 
getAll(): AppSettings
Returns: Copy of all settings Example: 
const allSettings = session.settings.getAll();
console.log(`Total settings: ${allSettings.length}`);

// Filter specific types
const toggles = allSettings.filter(s => s.type === 'toggle');

​
getSetting

Find a setting by key and get the full setting object. 
getSetting(key: string): AppSetting | undefined
Parameters:
  • key: Setting key to find
Returns: Setting object or undefined Example: 
const setting = session.settings.getSetting('font_size');
if (setting && setting.type === 'slider') {
  console.log(`Font size: ${setting.value} (${setting.min}-${setting.max})`);
}

​
onChange

Listen for changes to any setting. 
onChange(handler: SettingsChangeHandler): () => void
Parameters:
  • handler: Function called when any setting changes
Returns: Cleanup function to remove the listener Example: 
const cleanup = session.settings.onChange((changes) => {
  console.log('Settings changed:');
  for (const [key, change] of Object.entries(changes)) {
    console.log(`  ${key}: ${change.oldValue} → ${change.newValue}`);
  }
});

// Later: remove listener
cleanup();

​
onValueChange

Listen for changes to a specific setting. 
onValueChange<T = any>(
  key: string,
  handler: SettingValueChangeHandler<T>
): () => void
Parameters:
  • key: Setting key to monitor
  • handler: Function called when the setting changes
Returns: Cleanup function to remove the listener Example: 
// Type-safe value change handler
const cleanup = session.settings.onValueChange<number>(
  'font_size',
  (newSize, oldSize) => {
    console.log(`Font size changed from ${oldSize} to ${newSize}`);
    updateFontSize(newSize);
  }
);

// Multiple listeners
const cleanups = [
  session.settings.onValueChange('theme', handleThemeChange),
  session.settings.onValueChange('language', handleLanguageChange),
  session.settings.onValueChange('enable_sound', handleSoundToggle)
];

// Clean up all listeners
cleanups.forEach(cleanup => cleanup());

​
fetch

Manually fetch settings from the cloud. This is generally not needed since settings are automatically kept in sync. 
fetch(): Promise<AppSettings>
Returns: Promise that resolves to the updated settings Throws: Error if the API client is not configured or the request fails Example: 
try {
  const settings = await session.settings.fetch();
  console.log('Settings refreshed:', settings);
} catch (error) {
  console.error('Failed to fetch settings:', error);
}

​
MentraOS Settings

The SettingsManager also provides access to system-wide MentraOS settings.

​
onMentraosSettingChange

Listen for changes to specific MentraOS settings. 
onMentraosSettingChange<T = any>(
  key: string,
  handler: (newValue: T, oldValue: T) => void
): () => void
Parameters:
  • key: MentraOS setting key (e.g., ‘metricSystemEnabled’)
  • handler: Function called when the value changes
Returns: Cleanup function to remove the listener Example: 
// Listen for metric system changes
const cleanup = session.settings.onMentraosSettingChange<boolean>(
  'metricSystemEnabled',
  (enabled, wasEnabled) => {
    if (enabled) {
      console.log('Metric system enabled');
      switchToMetricUnits();
    } else {
      console.log('Metric system disabled');
      switchToImperialUnits();
    }
  }
);

​
getMentraosSetting

Get the current value of an MentraOS setting. 
getMentraosSetting<T = any>(key: string, defaultValue?: T): T
Parameters:
  • key: MentraOS setting key
  • defaultValue: Default value if setting doesn’t exist
Returns: Setting value or default value Example: 
const metricEnabled = session.settings.getMentraosSetting<boolean>(
  'metricSystemEnabled',
  false
);

const userLocale = session.settings.getMentraosSetting<string>(
  'locale',
  'en-US'
);

​
Best Practices

​
1. Provide Defaults

// Good: Always provide a default
const lineWidth = session.settings.get<number>('line_width', 30);

// Avoid: No default can cause undefined errors
const lineWidth = session.settings.get<number>('line_width'); // Could be undefined!

​
2. Type Your Settings

// Good: Use generics for type safety
const enabled = session.settings.get<boolean>('feature_enabled', false);
const theme = session.settings.get<'light' | 'dark'>('theme', 'light');

// Avoid: Using 'any' loses type safety
const value = session.settings.get('some_setting');

​
3. Clean Up Listeners

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

export class MyAppServer extends AppServer {
  private cleanupFunctions: Array<() => void> = [];

  protected async onSession(session: AppSession, sessionId: string, userId: string): Promise<void> {
    // Store cleanup functions
    this.cleanupFunctions.push(
      session.settings.onValueChange('setting1', this.handler1),
      session.settings.onValueChange('setting2', this.handler2),
      session.settings.onChange(this.handleAnyChange)
    );
  }

  protected async onStop(sessionId: string, userId: string, reason: string): Promise<void> {
    // Clean up all listeners
    this.cleanupFunctions.forEach(cleanup => cleanup());
    this.cleanupFunctions = [];
  }
}