Skip to main content

Overview

The Omi backend powers all AI capabilities including transcription, conversation processing, chat, and integrations. This page is contributor setup: running the backend to develop and test the platform. It is not a guide to running your own production Omi (see Open Source & Omi Cloud). The fastest local path is the repository dev harness: make dev-init once, then make dev-up, which starts the Firestore and Auth emulators, Redis, and Typesense, and runs the API. No external cloud accounts are needed. The manual steps below are for working against your own cloud services instead. For chat retrieval development, topic search uses the configured search providers. Explicit transcript recall can also read saved text directly through the existing conversation-search tool’s optional transcript_query and transcript_cursor arguments. This path needs Firestore and the backend encryption configuration, but does not need Pinecone or a transcript backfill. Its bounded pages return source-linked excerpts and indicate when more history remains. The implementation and local verification checklist are in backend/docs/transcript-recall.md.
If you just want to build apps or test features, you can use Omi’s development backend instead. See the App Setup Guide for the automatic setup option.

Video walkthrough

Prerequisites

With the dev harness (make dev-up), Firestore, Auth, Redis, and Typesense run locally and need no keys. If you are wiring up the manual stack below, gather what your work touches. Check backend/.env.template for the current authoritative list of variables:

Services you may need (manual setup)

Optional services

New to backend development? Install Homebrew (macOS/Linux) or Chocolatey (Windows) first. They make installing tools easier.

1. Google Cloud & Firebase setup

Install Google Cloud SDK

Enable required APIs

Go to the Google Cloud Console and enable these APIs:

Cloud Resource Manager API

Required for project management

Firebase Management API

Required for Firebase integration

Authenticate with Google Cloud

Run these commands in your terminal, replacing <project-id> with your Google Cloud project ID:
This installs Application Default Credentials (ADC) for the Google client libraries. Do not copy a service-account JSON key into the repo. Long-lived keys are the #6800 anti-pattern. Prefer plain user ADC for local work.Impersonation is an advanced, time-limited option (ADC tokens from --impersonate-service-account expire in about an hour). Only use it when you already have an org-provisioned lower-privilege SA and hold roles/iam.serviceAccountTokenCreator on that account. Replace the placeholder below with a real SA email from your team; there is no default dev-readonly@… account in this repo:
Firebase Admin and Firestore discover ADC automatically when SERVICE_ACCOUNT_JSON / GOOGLE_APPLICATION_CREDENTIALS are unset.

2. OAuth authentication setup

OAuth is required for user authentication. You need to configure both Google and Apple sign-in.
1

Create OAuth 2.0 client

  1. Go to Google Cloud Console → Credentials
  2. Click Create Credentials → OAuth 2.0 Client ID
  3. Select Web application as the application type
  4. Set a name (e.g., “Omi Backend Auth”)
2

Configure authorized origins

Under Authorized JavaScript origins, add:
  • https://your-domain.com (production)
  • https://your-ngrok-domain.ngrok-free.app (local development)
3

Configure redirect URIs

Under Authorized redirect URIs, add:
  • https://your-domain.com/v1/auth/callback/google
  • https://your-ngrok-domain.ngrok-free.app/v1/auth/callback/google
4

Save credentials

Click Create and save your Client ID and Client Secret for the .env file.
5

Configure consent screen

Go to APIs & Services → OAuth consent screen:
  • Fill in required app information
  • Add your domain to Authorized domains
  • Add scopes: openid, email, profile

3. Backend installation

Clone the repository

Install system dependencies

The backend Docker images run Python 3.11, so use Python 3.11 locally as well. If your package manager installs a newer default Python, install or select Python 3.11 before creating the virtual environment.

Set up a Python virtual environment

The backend uses uv, .python-version, and pylock.toml for reproducible local and CI installs.
You should see (.venv) at the beginning of your command prompt.

Update Python dependencies

When intentionally changing backend dependencies, edit the relevant requirements*.txt input, then refresh the locks:
The refresh preserves already-locked package versions by default. Use PYLOCK_UPGRADE=1 ./scripts/update-python-lock.sh only when intentionally upgrading dependency versions.

Create an environment file

Edit .env and fill in your API keys (see Environment Variables below).Never enable LOCAL_DEVELOPMENT on an internet-accessible machine: that mode intentionally bypasses authentication for local harnesses.

4. Optional services

Skip this if you don’t need webhook functionality.
Prefer ADC from gcloud auth application-default login (leave SERVICE_ACCOUNT_JSON unset). Only use a scoped secret for Modal/CI compatibility paths that have not yet moved to Workload Identity (#6800).Start the service:
Optionally expose via Ngrok for external access.
Skip this if you don’t need search functionality.
  1. Create an account on Typesense
  2. Create a collection named conversations using the schema in typesense/conversations.schema
  3. Install the Firebase Typesense extension
Configuration for the extension:
If you have existing data, create a typesense_sync collection and add a document named backfill with {'trigger': true}.

5. Running the backend

Set up Ngrok tunnel

Ngrok exposes your local backend to the internet so the Omi app can connect.
  1. Sign up at ngrok.com and install Ngrok
  2. Authenticate with your account
  3. Start the tunnel:
Note the public URL (e.g., https://your-domain.ngrok-free.app).

Start the backend server

Connect the Omi app

In your Omi app’s .dev.env file, set:
Don’t forget the trailing / in the URL!
Your OAuth redirect URIs in Google Cloud Console and Apple Developer Console must include your Ngrok URL.

When you're done

Deactivate the virtual environment:
To resume later, just activate the virtual environment again.

Troubleshooting

Add this to utils/stt/vad.py:
  • Double-check all API keys in your .env file
  • Ensure there are no trailing spaces or quotes around values
  • Verify keys are active and not expired
  • Ensure your Ngrok tunnel is running
  • Verify the URL is correctly set in the Omi app
  • Check that OAuth redirect URIs match your Ngrok URL
Try reinstalling dependencies:
  • On Windows, you may need to enable script execution: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  • Use Python 3.11

Environment variables

Complete reference for all .env variables:
.env.template intentionally leaves ENCRYPTION_SECRET blank. Generate a unique securely managed value of at least 32 bytes for every real environment.

Code formatting

We use black for code formatting with a line length of 120 characters.
To auto-format on commit, install the pre-commit hook from the repository root:

App setup

Set up the Flutter app for development

Backend Deep Dive

Understand the backend architecture

Chat System

Learn how the chat feature works

Storing Conversations

How conversations and memories are stored

Need help?

GitHub Issues

Report bugs or request features

Discord Community

Get help from the community