backend/README.md
This README provides a quick setup guide for the Omi backend. For a comprehensive step-by-step guide with detailed explanations, please refer to the Backend Setup Documentation.
Install the google-cloud-sdk
brew install google-cloud-sdkchoco install gcloudsdkYou will need to have your own Google Cloud Project with Firebase enabled. If you've already set up Firebase for the Omi app, you're good to go. If not, please refer to the Firebase Setup Guide.
IMPORTANT: Make sure you have the Cloud Resource Manager API, Firebase Management API, and Cloud Firestore API enabled in the Google Cloud API Console before proceeding to the next steps. Failure to enable these APIs will result in authentication errors.
Firestore Composite Indexes: You must create composite indexes for API key queries. Go to Firebase Console → Firestore Database → Indexes, and create the following composite indexes:
| Collection | Fields |
|---|---|
dev_api_keys | user_id (Ascending) + created_at (Descending) |
mcp_api_keys | user_id (Ascending) + created_at (Descending) |
Without these indexes, the Developer Settings page will show "Failed to load API keys: Internal Server Error".
Run the following commands one by one to authenticate with Google Cloud:
gcloud auth login
gcloud config set project <project-id>
gcloud auth application-default login --project <project-id>
Replace <project-id> with your Google Cloud Project ID.
This should generate the application_default_credentials.json file in the ~/.config/gcloud directory. This file is read automatically by gcloud in Python.
Install Python
brew install pythonchoco install pythonInstall pip if it doesn't exist (follow instructions on pip installation page)
Install git and ffmpeg
brew install git ffmpegchoco install git.install ffmpegInstall opus (required for audio processing)
brew install opusMove to the backend directory: cd backend
Create your environment file: cp .env.template .env
Set up Redis
Add the necessary API keys in the .env file:
ADMIN_KEY to a temporary value (e.g., 123) for local developmentPINECONE_INDEX_NAME to the name of your Pinecone indexInstall Python dependencies (choose one of the following approaches):
Option A: Using a virtual environment (recommended)
# Create a virtual environment
python -m venv venv
# Activate the virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate
# Install dependencies within the virtual environment
pip install -r requirements.txt
You should see (venv) at the beginning of your command prompt when the virtual environment is active.
Option B: Direct installation
# Install dependencies globally
pip install -r requirements.txt
Sign up on ngrok and follow the steps to configure it
ngrok config add-authtoken <your-token>During the onboarding flow, under the Static Domain section, Ngrok should provide you with a static domain and a command to point your localhost to that static domain. Replace the port from 80 to 8000 in that command and run it in your terminal:
ngrok http --domain=example.ngrok-free.app 8000
Start the backend server:
uvicorn main:app --reload --env-file .env
Troubleshooting: If you get any error mentioning "no internet connection" while downloading models, add the following lines in the utils/stt/vad.py file after the import statements:
import ssl
ssl._create_default_https_context = ssl._create_unverified_context
Now try running the server again: uvicorn main:app --reload --env-file .env
In your Omi app's environment, set BASE_API_URL to the URL provided by ngrok (e.g., https://example.ngrok-free.app)
Your app should now be using your local backend
If you used a virtual environment, when you're done, deactivate it by running:
deactivate