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.
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
1. Google Cloud & Firebase setup
Install Google Cloud SDK
- macOS
- Windows
- Linux/Nix
Enable required APIs
Cloud Resource Manager API
Firebase Management API
Authenticate with Google Cloud
<project-id> with your Google Cloud project ID:--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: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.- Google OAuth
- Apple OAuth
Create OAuth 2.0 client
- Go to Google Cloud Console → Credentials
- Click Create Credentials → OAuth 2.0 Client ID
- Select Web application as the application type
- Set a name (e.g., “Omi Backend Auth”)
Configure authorized origins
https://your-domain.com(production)https://your-ngrok-domain.ngrok-free.app(local development)
Configure redirect URIs
https://your-domain.com/v1/auth/callback/googlehttps://your-ngrok-domain.ngrok-free.app/v1/auth/callback/google
Save credentials
.env file.Configure 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
- macOS
- Windows
- Linux/Nix
Set up a Python virtual environment
- macOS/Linux
- Windows PowerShell
(.venv) at the beginning of your command prompt.Update Python dependencies
requirements*.txt input, then refresh the locks:PYLOCK_UPGRADE=1 ./scripts/update-python-lock.sh only when intentionally upgrading dependency versions.Create an environment file
.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
Pusher service (for webhooks)
Pusher service (for webhooks)
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:Typesense (for search)
Typesense (for search)
- Create an account on Typesense
- Create a collection named
conversationsusing the schema intypesense/conversations.schema - Install the Firebase Typesense extension
typesense_sync collection and add a document named backfill with {'trigger': true}.5. Running the backend
Set up Ngrok tunnel
- Sign up at ngrok.com and install Ngrok
- Authenticate with your account
- Start the tunnel:
https://your-domain.ngrok-free.app).Start the backend server
Connect the Omi app
.dev.env file, set:When you're done
Troubleshooting
SSL certificate errors during model downloads
SSL certificate errors during model downloads
utils/stt/vad.py:API key issues
API key issues
- Double-check all API keys in your
.envfile - Ensure there are no trailing spaces or quotes around values
- Verify keys are active and not expired
Ngrok connection issues
Ngrok connection issues
- 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
Module not found errors
Module not found errors
Virtual environment not activating
Virtual environment not activating
- 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:
- Required
- OAuth
- Firebase projects
- Storage
- Optional
Code formatting
We useblack for code formatting with a line length of 120 characters.