Skip to main content

​
Overview

There are two ways to set up the Omi app for development:

Automatic Setup

Recommended for most developersOne command setup using Omi’s development backend

Manual Setup

For custom backendsFull control over configuration and backend
Don’t want to build from source? Download the official app from the App Store or Google Play.

​
Prerequisites

Before starting, make sure you have the following installed:

Flutter SDK

Includes Dart - the core framework

Xcode

Required for iOS development

Android Studio

Required for Android development

CocoaPods

iOS dependency manager
You’ll also need NDK to build Opus for ARM devices.

​
Build the App Automatically

This is the recommended way to get started. It sets up your environment to use Omi’s development backend with just one command.

​
Video Walkthrough

​
Setup Steps

Navigate to the app directory

Run setup for your platform

Run in simulator

Open the app in your IDE and hit run:
  • Xcode: Open app/ios folder
  • Android Studio: Open app/android folder
Or run from terminal:
The automatic setup uses Omi’s development backend, making it the fastest way to start building apps and making changes.

​
Build the App Manually

Manual setup gives you full control, allowing you to use your own backend.

Verify Flutter Installation

Ensure Flutter is installed by following the official Flutter Installation Guide.Verify your setup:

Get Flutter Dependencies

From the app directory, install packages:

Install iOS Pods

Navigate to iOS directory and install CocoaPods dependencies:

Configure Environment

Create your environment file from the template:

Add API Keys

Edit .dev.env and add your API keys:
Be sure to include the trailing / in API_BASE_URL or you’ll get malformed URLs. If you change this later, delete the builds folder and recreate the runner.

Run Build Runner

Generate necessary files:

Setup Firebase

Firebase is mandatory for the app to run.
The repo ships prebuilt Firebase configs for both dev and prod. If you’re using Omi’s development backend (the common case), they’re already in place after setup.sh — skip to the next step.Never run flutterfire configure against Omi’s bundle IDs — it overwrites the prebuilt prod credentials in app/ios/Config/Prod/, app/lib/firebase_options_prod.dart, and app/android/app/src/prod/.
If you need your own Firebase project (custom backend):
  1. Follow the official Firebase Flutter Setup through Step 1
  2. For Apple login, create an identifier first
  3. Configure flutterfire config using your own bundle IDs and your own project — not Omi’s
  4. Generate SHA1/SHA256 keys for your keystore and add them to Firebase (StackOverflow guide | Official Docs)
If you’re facing auth issues, enable Google/Apple sign-in in the Firebase Console under Authentication → Sign-in method.

Run the App

Select your target device and run:
To build an APK:

​
Code Formatting

We use dart format with a line length of 120 characters. To automatically format code on commit, install the pre-commit hook:

​
Troubleshooting

  • Run flutter doctor -v for detailed output
  • Follow the suggestions to fix each issue
  • Make sure all required SDKs are installed
  • Ensure CocoaPods is installed: sudo gem install cocoapods
  • Run pod install in the ios directory
  • Try pod repo update if dependencies fail
  • Check NDK is installed via Android Studio SDK Manager
  • Verify JDK version matches requirements (JDK 21)
  • Accept all Android licenses: flutter doctor --android-licenses
  • Enable Google/Apple sign-in in Firebase Console
  • Verify SHA1/SHA256 keys are added to Firebase
  • Check bundle IDs match your Firebase configuration
Error Message:
Cause: This error occurs because iOS security restrictions prevent the Dart VM from changing memory protection during JIT compilation in Debug mode on physical devices.Solutions:
  1. Use iOS Simulator (Recommended for Development):
    • In Xcode, select an iOS Simulator (e.g., “iPhone 16 Pro”) instead of your physical device
    • The simulator doesn’t have this restriction, so Debug mode works normally
    • Or run: flutter run --flavor dev (it will use a simulator if available)
  2. Use Release/Profile Mode for Physical Devices:
    • If you need to test on a physical device, build in Release or Profile mode:
    • Or in Xcode, select “Release” or “Profile” scheme instead of “Debug”
Note: This is a known Flutter/iOS limitation. Debug mode with JIT compilation requires memory protection changes that iOS blocks on physical devices for security reasons.

​
Need Help?

Discord Community

Search the help channel or ask questions

GitHub Issues

Report bugs or browse existing issues

Backend Setup

Set up your own Omi backend

Build Apps

Create Omi apps and integrations

Firmware Setup

Flash and update device firmware

Contribution Guide

How to contribute to Omi