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

cd app

Run setup for your platform

bash setup.sh ios

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:
flutter run --flavor dev
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:
flutter doctor -v

[✓] Flutter (Channel stable, 3.35.3, on macOS 15.4.1)
[✓] Android toolchain - develop for Android devices (Android SDK version 36.0.0)
[✓] Xcode - develop for iOS and macOS (Xcode 16.4)
[✓] Chrome - develop for the web
[✓] Android Studio (version 2025.1)
[✓] VS Code (version 1.101.0)
[✓] Connected device (4 available)
[✓] Network resources

Get Flutter Dependencies

From the app directory, install packages:
cd app
flutter pub get

Install iOS Pods

Navigate to iOS directory and install CocoaPods dependencies:
cd ios
pod install
pod repo update

Configure Environment

Create your environment file from the template:
cd ..
cat .env.template > .dev.env

Add API Keys

Edit .dev.env and add your API keys:
KeyDescription
API_BASE_URLYour backend URL (use https://api.omiapi.com/ for dev, or set up your own)
OPENAI_API_KEYOptional - for AI features
GOOGLE_MAPS_API_KEYOptional - for location features
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:
dart pub run build_runner clean
dart pub run build_runner build

Setup Firebase

Firebase is mandatory for the app to run.
  1. Follow the official Firebase Flutter Setup through Step 1
  2. For Apple login, create an identifier first
  3. Configure for production: 
flutterfire config \
  --out=lib/firebase_options_prod.dart \
  --ios-bundle-id=YOUR_IOS_BUNDLE_ID \
  --android-app-id=com.friend.ios \
  --android-out=android/app/src/prod/ \
  --ios-out=ios/Config/Prod/ \
  --macos-bundle-id=YOUR_MACOS_BUNDLE_ID \
  --macos-out=macos/Config/Prod
  1. Configure for development:
flutterfire config \
  --out=lib/firebase_options_dev.dart \
  --ios-bundle-id=com.friend-app-with-wearable.ios12.development \
  --android-app-id=com.friend.ios.dev \
  --android-out=android/app/src/dev/ \
  --ios-out=ios/Config/Dev/ \
  --macos-bundle-id=com.friend-app-with-wearable.ios12.development \
  --macos-out=macos/Config/Dev
  1. 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:
flutter run -v --flavor dev
To build an APK:
flutter build apk --flavor dev

​
Code Formatting

We use dart format with a line length of 120 characters. To automatically format code on commit, install the pre-commit hook: 
# From the root of the repository
ln -s -f ../../scripts/pre-commit .git/hooks/pre-commit

​
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

​
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