Skip to main content
This guide will walk you through deploying your MentraOS app to Railway, a cloud hosting platform that makes deployment simple and reliable. Instead of running your app locally, you’ll have a production-ready hosted solution.

​
Why Use Railway?

Benefits of Railway hosting:
  • Always Online: Your app runs 24/7 without needing your computer
  • Easy to Deploy: Push code changes to GitHub and Railway deploys automatically
  • Better Performance: Dedicated cloud infrastructure with better uptime than local development

​
Prerequisites

Make sure you have:
  • GitHub Account: For code repository hosting
  • Railway Account: Free account at railway.com
  • MentraOS Account: For the developer console at console.mentra.glass
  • Basic Git Knowledge: For pushing code changes

​
Part 1: Set Up Your Repository

​
1. Create Your App Repository

Create a new repository from the MentraOS example app template:
  1. Go to the MentraOS Cloud Example App repository. Click the green “Use this template” dropdown in the upper right. Select “Create a new repository”
  2. Choose a repository name (e.g., my-mentraos-app).
  3. Click “Create repository”
Create repo from template

​
2. Clone Your Repository

Clone your new repository locally: 
git clone https://github.com/YOUR_USERNAME/my-mentraos-app
cd my-mentraos-app

​
Part 2: Deploy to Railway

​
3. Create Railway Project

  1. Go to railway.com.
  2. Sign in with your GitHub account. Click “Deploy a new project”.
  3. Select “Deploy from GitHub repo”.

​
4. Connect Your Repository

  1. Select your new repository from the list.
  2. If you don’t see it, click “Configure GitHub App” to give Railway access to your repositories.
  3. Once selected, Railway will start setting up your project.

​
5. Get Your Public URL

  1. Go to the “Settings” tab in your Railway project.
  2. Under “Networking” > “Public Networking”, click “Generate Domain”.
  3. You’ll get a URL like: yourapp-production-fa42.up.railway.app. Copy this URL - you’ll need it for the next step.

​
Part 3: Register Your App with MentraOS

​
6. Register in Developer Console

  1. Navigate to console.mentra.glass
  2. Sign in with the same account you use for MentraOS
  3. Click “Create App” and fill in the details:
    • Package Name: Use the same package name from your environment variables
    • Server URL: Enter your Railway URL (e.g., https://yourapp-production-fa42.up.railway.app)
    • Webview URL: Enter https://yourapp-production-fa42.up.railway.app/webview
    • Permissions: Add the microphone permission. See the Permissions guide for details.
  4. Click “Create App”
  5. Take note of the API key, as you will need it later and it won’t be shown again.

​
7. Import App Configuration

You can now add permissions, settings, and tools to your app via the MentraOS Developer Console. Instead of doing it manually, let’s upload this example’s app_config.json file by clicking the “Import app_config.json” button under Configuration Management: Import app config
  1. In the developer console, scroll to the “Configuration Management” section
  2. Click “Import app_config.json”
  3. Upload the app_config.json file from your cloned repository
  4. This will automatically configure:
    • Permissions: Microphone access for speech recognition
    • Settings: Adds a toggle for show_live_transcription
    • Tools: Adds an example tool called my_tool_name
  5. Click “Save Changes” to apply the configuration

​
8. Configure Environment Variables

  1. In your Railway project dashboard, click on the “Variables” tab
  2. Under “Suggested Variables”, you’ll see template variables from the .env.example file
  3. Replace the placeholder values
  4. Click “Add All” to save the variables

​
9. Deploy Your App

  1. On the left side of the Railway dashboard, you’ll see “Apply 3 changes”
  2. Click the purple “Deploy” button
  3. Railway will build and deploy your app (this takes 1-2 minutes)

​
Part 4: Test Your Deployed App

​
10. Install MentraOS

  1. Download the MentraOS app from MentraGlass.com/os
  2. Set up your smart glasses following the setup guide

​
11. Test Your App

  1. Open Mentra on your phone
  2. Find your app in the app list and tap to start it
  3. Spoken text will appear on your smart glasses display

​
12. Test the Webview

  1. In the MentraOS phone app, open the currently running app.
  2. This opens the webview interface.
  3. You will see your username displayed.

​
Part 5: Continuous Deployment

​
13. Make Changes and Deploy

Railway automatically deploys when you push changes to GitHub:
  1. Make a change to your app locally (e.g., modify the welcome message in src/index.ts)
  2. Commit and push your changes: 
    git add .
git commit -m "Update welcome message"
git push origin main
  3. Railway will automatically detect the changes and deploy within 1-2 minutes
  4. To see the changes, restart your app in MentraOS:
    • Tap your app in the list to stop it
    • Tap again to restart it

​
14. Success!

Congratulations! Your MentraOS app is now running in the cloud.

​
Troubleshooting

App not responding after deployment?
  • Check the Railway logs for errors
  • Verify your environment variables are set correctly
  • Ensure your API key is valid in the developer console
Changes not appearing?
  • Confirm your GitHub push was successful
  • Check Railway deployment status
  • Restart your app in MentraOS after deployment completes
Webview not loading?
  • Verify the webview URL is set correctly in the developer console
  • Check that your Railway deployment is accessible at the public URL
  • Load the webview URL directly in your browser to ensure it’s accessible