App Setup

Overview

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

<CardGroup cols={2}> <Card title="Automatic Setup" icon="wand-magic-sparkles" href="#build-the-app-automatically"> **Recommended for most developers**

One command setup using Omi's development backend

</Card> <Card title="Manual Setup" icon="wrench" href="#build-the-app-manually"> **For custom backends**

Full control over configuration and backend

</Card> </CardGroup> <Info> Don't want to build from source? Download the official app from the [App Store](https://apps.apple.com/us/app/friend-ai-wearable/id6502156163) or [Google Play](https://play.google.com/store/apps/details?id=com.friend.ios). </Info>

Prerequisites

Before starting, make sure you have the following installed:

<CardGroup cols={2}> <Card title="Flutter SDK" icon="flutter" href="https://docs.flutter.dev/get-started/install"> Includes Dart - the core framework </Card> <Card title="Xcode" icon="apple" href="https://developer.apple.com/xcode/"> Required for iOS development </Card> <Card title="Android Studio" icon="android" href="https://developer.android.com/studio"> Required for Android development </Card> <Card title="CocoaPods" icon="gem" href="https://cocoapods.org/"> iOS dependency manager </Card> </CardGroup> <Note> You'll also need [NDK](https://developer.android.com/ndk/downloads) to build Opus for ARM devices. </Note>

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

<Steps> <Step title="Navigate to the app directory" icon="folder"> ```bash cd app ``` </Step> <Step title="Run setup for your platform" icon="terminal"> <Tabs> <Tab title="iOS"> ```bash bash setup.sh ios ``` </Tab> <Tab title="Android"> ```bash bash setup.sh android ``` </Tab> <Tab title="macOS"> ```bash bash setup.sh macos ``` </Tab> <Tab title="Windows"> ```powershell .\setup\scripts\setup.ps1 ``` </Tab> </Tabs> </Step> <Step title="Run in simulator" icon="play"> Open the app in your IDE and hit run: - **Xcode**: Open `app/ios` folder - **Android Studio**: Open `app/android` folder

Or run from terminal:
```bash
flutter run --flavor dev
```

</Step> </Steps> <Tip> The automatic setup uses Omi's development backend, making it the fastest way to start building apps and making changes. </Tip>

Build the App Manually

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

<Steps> <Step title="Verify Flutter Installation" icon="check"> Ensure Flutter is installed by following the official [Flutter Installation Guide](https://docs.flutter.dev/get-started/install).

Verify your setup:
```bash
flutter doctor -v
```

<AccordionGroup>
  <Accordion title="Example output" icon="terminal">
    ```
    [✓] 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
    ```
  </Accordion>
  <Accordion title="Recommended versions" icon="info-circle">
    This project is tested with specific tool versions. See [`app/setup.sh`](https://github.com/BasedHardware/omi/blob/main/app/setup.sh) for recommended versions:
    - Flutter 3.35.3
    - Xcode 16.4
    - Android SDK Platform 35
    - NDK 28.2.13676358
    - JDK 21

    To set a specific JDK on macOS:
    ```bash
    flutter config --jdk-dir /Library/Java/JavaVirtualMachines/jdk-21.jdk/Contents/Home
    ```
  </Accordion>
</AccordionGroup>

</Step> <Step title="Get Flutter Dependencies" icon="download"> From the `app` directory, install packages: ```bash cd app flutter pub get ``` </Step> <Step title="Install iOS Pods" icon="apple"> Navigate to iOS directory and install CocoaPods dependencies: ```bash cd ios pod install pod repo update ``` </Step> <Step title="Configure Environment" icon="gear"> Create your environment file from the template: ```bash cd .. cat .env.template > .dev.env ``` </Step> <Step title="Add API Keys" icon="key"> Edit `.dev.env` and add your API keys:

| Key | Description |
|-----|-------------|
| `API_BASE_URL` | Your backend URL (use `https://api.omiapi.com/` for dev, or [set up your own](/doc/developer/backend/Backend_Setup)) |
| `OPENAI_API_KEY` | Optional - for AI features |
| `GOOGLE_MAPS_API_KEY` | Optional - for location features |

<Warning>
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.
</Warning>

</Step> <Step title="Run Build Runner" icon="hammer"> Generate necessary files: ```bash dart pub run build_runner clean dart pub run build_runner build ``` </Step> <Step title="Setup Firebase" icon="fire"> Firebase is **mandatory** for the app to run.

1. Follow the official [Firebase Flutter Setup](https://firebase.google.com/docs/flutter/setup) through Step 1

2. For Apple login, [create an identifier](https://developer.apple.com/account/resources/identifiers/list) first

3. Configure for **production**:
```bash
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
```

4. Configure for **development**:
```bash
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
```

5. Generate SHA1/SHA256 keys for your keystore and add them to Firebase ([StackOverflow guide](https://stackoverflow.com/a/56091158) | [Official Docs](https://support.google.com/firebase/answer/9137403?hl=en))

<Tip>
If you're facing auth issues, enable Google/Apple sign-in in the Firebase Console under **Authentication → Sign-in method**.
</Tip>

</Step> <Step title="Run the App" icon="play"> Select your target device and run: ```bash flutter run -v --flavor dev ```

To build an APK:
```bash
flutter build apk --flavor dev
```

</Step> </Steps>

Code Formatting

We use dart format with a line length of 120 characters.

To automatically format code on commit, install the pre-commit hook:

bash

# From the root of the repository
ln -s -f ../../scripts/pre-commit .git/hooks/pre-commit

Troubleshooting

<AccordionGroup> <Accordion title="Flutter doctor shows issues" icon="stethoscope"> - Run `flutter doctor -v` for detailed output - Follow the suggestions to fix each issue - Make sure all required SDKs are installed </Accordion> <Accordion title="iOS build fails" icon="apple"> - Ensure CocoaPods is installed: `sudo gem install cocoapods` - Run `pod install` in the `ios` directory - Try `pod repo update` if dependencies fail </Accordion> <Accordion title="Android build fails" icon="android"> - Check NDK is installed via Android Studio SDK Manager - Verify JDK version matches requirements (JDK 21) - Accept all Android licenses: `flutter doctor --android-licenses` </Accordion> <Accordion title="Firebase auth not working" icon="fire"> - Enable Google/Apple sign-in in Firebase Console - Verify SHA1/SHA256 keys are added to Firebase - Check bundle IDs match your Firebase configuration </Accordion> <Accordion title="iOS: Unable to flip between RX and RW memory protection" icon="apple"> **Error Message:** ``` error: Unable to flip between RX and RW memory protection on pages ```

**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:
     ```bash
     flutter run --release --flavor dev
     ```
   - 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.

</Accordion> </AccordionGroup>

Need Help?

<CardGroup cols={2}> <Card title="Discord Community" icon="discord" href="http://discord.omi.me"> Search the help channel or ask questions </Card> <Card title="GitHub Issues" icon="github" href="https://github.com/BasedHardware/omi/issues"> Report bugs or browse existing issues </Card> </CardGroup>

<CardGroup cols={2}> <Card title="Backend Setup" icon="server" href="/doc/developer/backend/Backend_Setup"> Set up your own Omi backend </Card> <Card title="Build Apps" icon="puzzle-piece" href="/doc/developer/apps/Introduction"> Create Omi apps and integrations </Card> <Card title="Firmware Setup" icon="microchip" href="/doc/get_started/Flash_device"> Flash and update device firmware </Card> <Card title="Contribution Guide" icon="code-branch" href="/doc/developer/Contribution"> How to contribute to Omi </Card> </CardGroup>