Local Development

When developing your MentraOS app, you’ll want to test it locally before deploying to production. This guide explains how local development works and how to set it up.

How MentraOS Apps Work

Understanding the architecture helps explain why we need tunneling for local development:

User's Glasses ←→ MentraOS Relay Server←→ Your App Server

The flow:

User interacts with glasses (voice, buttons, camera)
MentraOS Relay Server processes the interaction
Relay Server sends events to your app server via webhook
Your app responds (display text, play audio, etc.)
Response flows back through the Relay Server to the user’s phone, and then to the user’s glasses

The key requirement: MentraOS Relay Server must be able to reach your app server over the internet.

The Local Development Problem

When you run your app locally, it’s only accessible on your machine:

Your App: http://localhost:3000 ✅ (you can access it)
         http://localhost:3000 ❌ (MentraOS Relay Server cannot access it)

Why this doesn’t work:

localhost is not a public address
MentraOS Relay Server runs on the internet
Relay Server can’t reach your local machine directly
Firewalls and routers block incoming connections

The Solution: Tunneling with ngrok

ngrok creates a secure tunnel from a public URL to your local server:

MentraOS Relay Server → https://abc123.ngrok.io → localhost:3000 → Your App
                        (public internet)         (your machine)

Now MentraOS Relay Server can send events to https://abc123.ngrok.io, and they’ll be forwarded to your local app.

Quick Start

1. Install ngrok

macOS:

brew install ngrok

Linux:

curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | \
  sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null && \
  echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | \
  sudo tee /etc/apt/sources.list.d/ngrok.list && \
  sudo apt update && sudo apt install ngrok

Windows / Other: Download from ngrok.com/download

2. Start Your App

# In your app directory
bun install
bun run dev

# Your app is now running on http://localhost:3000

3. Start ngrok Tunnel

In a new terminal:

ngrok http 3000

You’ll see output like:

ngrok

Session Status                online
Account                       your-email@example.com (Plan: Free)
Version                       3.x.x
Region                        United States (us)
Latency                       -
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://abc123.ngrok.io -> http://localhost:3000

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

Copy the Forwarding URL: https://abc123.ngrok.io

4. Update Developer Console

Go to console.mentra.glass/apps
Select your app
Set App Server URL to: https://abc123.ngrok.io
Save changes

5. Test on Glasses

Open your app on MentraOS glasses
Interact with it (speak, press buttons, etc.)
Watch your terminal - you should see events coming in
Check ngrok’s web interface at http://localhost:4040 to see requests

Development Workflow

Typical workflow:

# Terminal 1: Start your app
cd my-mentra-app
bun run dev

# Terminal 2: Start ngrok
ngrok http 3000

# Copy ngrok URL and update Developer Console
# → Test on glasses
# → Make code changes
# → App auto-restarts (if using nodemon)
# → Test again

When you restart ngrok:

Free ngrok URLs change each time
You must update the Developer Console with the new URL
Paid ngrok plans provide persistent URLs

ngrok Web Interface

ngrok provides a web interface at http://localhost:4040 showing:

Request Inspector - See all incoming requests
Request/Response Details - Headers, body, timing
Replay Requests - Resend requests for debugging

This is incredibly useful for debugging webhook issues.

Common Issues

Issue: “Connection Refused”

Problem: ngrok can’t connect to your local server Solution:

# Make sure your app is running first
bun run dev

# Then start ngrok in another terminal
ngrok http 3000

Issue: “No Events Coming Through”

Problem: You don’t see any requests in your terminal Solution:

Check packageName - Must match exactly in both your code and Developer Console
Check API key - Must be correct and match your app in Developer Console
Check ngrok URL - Must be correct in Developer Console (no trailing slash)
Check ngrok is still running (free URLs expire after 2 hours)
Check your app is still running
Look at ngrok web interface (localhost:4040) to see if requests are arriving
Check your app logs for errors

Common mistakes:

// ❌ Wrong - packageName doesn't match Developer Console
packageName: 'com.example.myapp'  // Console has: 'com.mycompany.myapp'

// ❌ Wrong - incorrect API key
apiKey: 'old-api-key-here'

// ✅ Correct - matches Developer Console exactly
packageName: 'com.mycompany.myapp',
apiKey: process.env.MENTRA_API_KEY,

Issue: “ngrok URL Changed”

Problem: You restarted ngrok and URL changed Solution:

Free plan: Update Developer Console with new URL each time
Paid plan: Use reserved domains for persistent URLs
Alternative: Deploy to Railway/Ubuntu for persistent URLs

ngrok Free vs Paid

Free Plan

✅ Unlimited tunnels
✅ Web interface
❌ URL changes each restart
❌ 40 connections/minute limit
❌ Random subdomain

Paid Plans (starting $8/month)

✅ Everything in Free
✅ Reserved domains - URL never changes
✅ Custom domains
✅ Higher limits
✅ More regions

For serious development, paid ngrok or deployment to Railway/Ubuntu is recommended.

Alternatives to ngrok

CloudFlare Tunnel

cloudflared tunnel --url http://localhost:3000

Free persistent URLs
More complex setup
Good for long-term development

localtunnel

npx localtunnel --port 3000

Simpler than ngrok
Less reliable
Good for quick tests

VS Code Port Forwarding

If using GitHub Codespaces or VS Code Remote:

Built-in port forwarding
No extra tools needed
Limited to VS Code environment

Next Steps

Railway Deployment

Deploy to production

Ubuntu Deployment

Self-hosted deployment

Quickstart Guide

Build your first app

Example Apps

See working examples

Getting Started

Core Concepts

SDK Reference

Local Development

How MentraOS Apps Work

The Local Development Problem

The Solution: Tunneling with ngrok

Quick Start

1. Install ngrok

2. Start Your App

3. Start ngrok Tunnel

4. Update Developer Console

5. Test on Glasses

Development Workflow

ngrok Web Interface

Common Issues

Issue: “Connection Refused”

Issue: “No Events Coming Through”

Issue: “ngrok URL Changed”

ngrok Free vs Paid

Free Plan

Paid Plans (starting $8/month)

Alternatives to ngrok

CloudFlare Tunnel

localtunnel

VS Code Port Forwarding

Next Steps

Railway Deployment

Ubuntu Deployment

Quickstart Guide

Example Apps

​How MentraOS Apps Work

​The Local Development Problem

​The Solution: Tunneling with ngrok

​Quick Start

​1. Install ngrok

​2. Start Your App

​3. Start ngrok Tunnel

​4. Update Developer Console

​5. Test on Glasses

​Development Workflow

​ngrok Web Interface

​Common Issues

​Issue: “Connection Refused”

​Issue: “No Events Coming Through”

​Issue: “ngrok URL Changed”

​ngrok Free vs Paid

​Free Plan

​Paid Plans (starting $8/month)

​Alternatives to ngrok

​CloudFlare Tunnel

​localtunnel

​VS Code Port Forwarding

​Next Steps

Railway Deployment

Ubuntu Deployment

Quickstart Guide

Example Apps

How MentraOS Apps Work

The Local Development Problem

The Solution: Tunneling with ngrok

Quick Start

1. Install ngrok

2. Start Your App

3. Start ngrok Tunnel

4. Update Developer Console

5. Test on Glasses

Development Workflow

ngrok Web Interface

Common Issues

Issue: “Connection Refused”

Issue: “No Events Coming Through”

Issue: “ngrok URL Changed”

ngrok Free vs Paid

Free Plan

Paid Plans (starting $8/month)

Alternatives to ngrok

CloudFlare Tunnel

localtunnel

VS Code Port Forwarding

Next Steps