Required Environment Variables for the Omi Backend: Complete Configuration Guide

The Omi backend requires over 40 environment variables—ranging from Stripe API keys to Deepgram speech-to-text credentials—which are read at runtime via os.getenv() scattered across modules like backend/utils/stripe.py and backend/utils/stt/streaming.py.

The Omi backend is a FastAPI application that orchestrates speech transcription, billing, and third-party integrations. Proper configuration of environment variables is mandatory to connect external services such as Deepgram, Google Cloud Storage, and Stripe. This guide documents every required variable grouped by subsystem, with exact file references from the basedhardware/omi repository.

Stripe and Billing Configuration

Payment processing and subscription management depend on six Stripe-specific variables defined in backend/utils/stripe.py and backend/utils/subscription.py:

• STRIPE_API_KEY — Authenticates all Stripe API calls
• STRIPE_WEBHOOK_SECRET — Verifies webhook signatures for standard events
• STRIPE_CONNECT_WEBHOOK_SECRET — Verifies Stripe Connect webhook signatures
• STRIPE_UNLIMITED_MONTHLY_PRICE_ID and STRIPE_UNLIMITED_ANNUAL_PRICE_ID — Price IDs for subscription tiers (used in backend/routers/users.py)

Quota limits for the free tier require:

• BASIC_TIER_MINUTES_LIMIT_PER_MONTH
• BASIC_TIER_WORDS_TRANSCRIBED_LIMIT_PER_MONTH
• BASIC_TIER_INSIGHTS_GAINED_LIMIT_PER_MONTH
• BASIC_TIER_MEMORIES_CREATED_LIMIT_PER_MONTH

Additionally, SUBSCRIPTION_LAUNCH_DATE sets when the subscription model becomes active.

# backend/utils/stripe.py

import os
import stripe

stripe.api_key = os.getenv("STRIPE_API_KEY")
if not stripe.api_key:
    raise RuntimeError("STRIPE_API_KEY missing")
endpoint_secret = os.getenv("STRIPE_WEBHOOK_SECRET")

Speech-to-Text and Deepgram Setup

Real-time transcription relies on Deepgram credentials loaded in backend/utils/stt/streaming.py:

• DEEPGRAM_API_KEY — Primary API key for Deepgram services (required)
• DEEPGRAM_SELF_HOSTED_ENABLED — Set to true to enable self-hosted endpoints
• DEEPGRAM_SELF_HOSTED_URL — URL of the self-hosted Deepgram instance
• STT_SERVICE_MODELS — Comma-separated model list (defaults to dg-nova-3)

# backend/utils/stt/streaming.py

import os
from deepgram import DeepgramClient

DEEPGRAM_API_KEY = os.getenv("DEEPGRAM_API_KEY")
if not DEEPGRAM_API_KEY:
    raise RuntimeError("DEEPGRAM_API_KEY is required")
deepgram = DeepgramClient(DEEPGRAM_API_KEY)

Voice Activity Detection and Speaker Services

Voice processing microservices require endpoint configurations:

• HOSTED_VAD_API_URL — URL for the Voice Activity Detection service (backend/utils/stt/vad.py)
• HOSTED_SPEAKER_EMBEDDING_API_URL — Speaker embedding service endpoint (backend/utils/stt/speaker_embedding.py)
• HOSTED_SPEECH_PROFILE_API_URL — Speech profile service endpoint (backend/utils/stt/speech_profile.py)
• MIN_EMBEDDING_AUDIO_DURATION — Minimum audio length in seconds (defaults to 0.5)

Real-Time Communication (Pusher)

WebSocket functionality depends on:

• HOSTED_PUSHER_API_URL — External Pusher service URL (backend/utils/pusher.py)
• PUSHER_ENABLED — Feature flag automatically set to true when HOSTED_PUSHER_API_URL is present (backend/routers/transcribe.py)

Third-Party Integrations and APIs

Social and search integrations require credentials scattered across retrieval and conversation modules:

• RAPID_API_HOST and RAPID_API_KEY — RapidAPI credentials (backend/utils/social.py)
• PERPLEXITY_API_KEY — Perplexity AI search API (backend/utils/retrieval/tools/perplexity_tools.py)
• GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET — OAuth for Google Drive/Calendar (backend/utils/retrieval/tools/google_utils.py)
• GOOGLE_MAPS_API_KEY — Geocoding services (backend/utils/conversations/location.py)
• TYPESENSE_HOST, TYPESENSE_HOST_PORT, TYPESENSE_API_KEY — Search engine connection (backend/utils/conversations/search.py)

Google Cloud Storage Buckets

File storage requires nine distinct bucket names loaded in backend/utils/other/storage.py:

• BUCKET_SPEECH_PROFILES
• BUCKET_POSTPROCESSING
• BUCKET_MEMORIES_RECORDINGS
• BUCKET_PRIVATE_CLOUD_SYNC
• BUCKET_TEMPORAL_SYNC_LOCAL
• BUCKET_PLUGINS_LOGOS
• BUCKET_APP_THUMBNAILS
• BUCKET_CHAT_FILES
• BUCKET_DESKTOP_UPDATES

The application also expects GOOGLE_APPLICATION_CREDENTIALS to be set in the environment for GCS authentication.

# backend/utils/other/storage.py

import os

speech_profiles_bucket = os.getenv("BUCKET_SPEECH_PROFILES")
if not speech_profiles_bucket:
    raise RuntimeError("BUCKET_SPEECH_PROFILES not set")

AI and Emotion Analysis

• HUME_API_KEY and HUME_CALLBACK_URL — Hume AI emotion analysis credentials (backend/utils/other/hume.py)

Security and Admin Credentials

Critical security variables include:

• ENCRYPTION_SECRET — Payload encryption key (backend/utils/encryption.py)
• WORKFLOW_API_KEY — Protects workflow endpoints (backend/utils/routers/workflow.py)
• ADMIN_KEY — Master admin secret for privileged actions (backend/routers/updates.py)
• BASE_API_URL — Base URL for internal micro-service calls (backend/routers/task_integrations.py)
• MARKETPLACE_APP_REVIEWERS — Comma-separated list of user IDs with review privileges (backend/routers/users.py)

Task Management OAuth

Integration with task apps requires OAuth pairs:

• TODOIST_CLIENT_ID and TODOIST_CLIENT_SECRET
• ASANA_CLIENT_ID and ASANA_CLIENT_SECRET
• GOOGLE_TASKS_CLIENT_ID and GOOGLE_TASKS_CLIENT_SECRET
• CLICKUP_CLIENT_ID and CLICKUP_CLIENT_SECRET

Development and Testing Variables

Local development flags:

• LOCAL_DEVELOPMENT — Set to true to bypass certain auth checks (backend/utils/other/endpoints.py)
• TEST_BACKEND_URL, TEST_USER_ID, TEST_FCM_TOKENS — Integration test configuration (test files only)
• GROQ_API_KEY, PYANNOTE_API_KEY — Experimental scripts
• PINECONE_API_KEY, PINECONE_INDEX_NAME — Vector DB for RAG pipelines (backend/scripts/rag/_shared.py)

Summary

• Stripe billing requires API keys, webhook secrets, and price IDs for subscription management
• Deepgram integration mandates DEEPGRAM_API_KEY with optional self-hosted configuration variables
• Google Cloud Storage needs nine distinct bucket names defined in backend/utils/other/storage.py
• Security depends on ENCRYPTION_SECRET, ADMIN_KEY, and WORKFLOW_API_KEY for privileged operations
• Development mode uses LOCAL_DEVELOPMENT to relax authentication constraints

Frequently Asked Questions

What happens if a required environment variable is missing?

The backend raises RuntimeError or similar exceptions during startup. For example, backend/utils/stripe.py explicitly checks if not stripe.api_key: raise RuntimeError("STRIPE_API_KEY missing"), causing immediate failure before the FastAPI server can accept requests.

Do I need all 40+ variables for local development?

No. Set LOCAL_DEVELOPMENT to true to bypass certain authentication checks, and only configure the subsystems you intend to test. For example, omit Stripe variables if not testing billing, or exclude Deepgram self-hosted variables if using the managed service.

Where are Stripe webhook secrets actually used?

STRIPE_WEBHOOK_SECRET and STRIPE_CONNECT_WEBHOOK_SECRET are consumed in backend/utils/stripe.py to verify webhook signatures via Stripe’s library, ensuring payment events originate from Stripe and not malicious actors.

How does the backend distinguish between production and self-hosted Deepgram?

The code in backend/utils/stt/streaming.py checks os.getenv("DEEPGRAM_SELF_HOSTED_ENABLED", "").lower() == "true". When enabled, it routes requests to DEEPGRAM_SELF_HOSTED_URL instead of the standard Deepgram endpoint.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}