# Required Environment Variables for the Omi Backend: Complete Configuration Guide

> Configure the Omi backend by understanding over 40 required environment variables. This guide details necessary Stripe API keys and speech-to-text credentials for runtime configuration.

- Repository: [omi/omi](https://github.com/basedhardware/omi)
- Tags: how-to-guide
- Published: 2026-02-26

---

**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`](https://github.com/basedhardware/omi/blob/main/backend/utils/stripe.py) and [`backend/utils/stt/streaming.py`](https://github.com/basedhardware/omi/blob/main/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`](https://github.com/basedhardware/omi/blob/main/backend/utils/stripe.py) and [`backend/utils/subscription.py`](https://github.com/basedhardware/omi/blob/main/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`](https://github.com/basedhardware/omi/blob/main/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.

```python

# 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`](https://github.com/basedhardware/omi/blob/main/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`)

```python

# 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`](https://github.com/basedhardware/omi/blob/main/backend/utils/stt/vad.py))
- **`HOSTED_SPEAKER_EMBEDDING_API_URL`** — Speaker embedding service endpoint ([`backend/utils/stt/speaker_embedding.py`](https://github.com/basedhardware/omi/blob/main/backend/utils/stt/speaker_embedding.py))
- **`HOSTED_SPEECH_PROFILE_API_URL`** — Speech profile service endpoint ([`backend/utils/stt/speech_profile.py`](https://github.com/basedhardware/omi/blob/main/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`](https://github.com/basedhardware/omi/blob/main/backend/utils/pusher.py))
- **`PUSHER_ENABLED`** — Feature flag automatically set to `true` when `HOSTED_PUSHER_API_URL` is present ([`backend/routers/transcribe.py`](https://github.com/basedhardware/omi/blob/main/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`](https://github.com/basedhardware/omi/blob/main/backend/utils/social.py))
- **`PERPLEXITY_API_KEY`** — Perplexity AI search API ([`backend/utils/retrieval/tools/perplexity_tools.py`](https://github.com/basedhardware/omi/blob/main/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`](https://github.com/basedhardware/omi/blob/main/backend/utils/retrieval/tools/google_utils.py))
- **`GOOGLE_MAPS_API_KEY`** — Geocoding services ([`backend/utils/conversations/location.py`](https://github.com/basedhardware/omi/blob/main/backend/utils/conversations/location.py))
- **`TYPESENSE_HOST`**, **`TYPESENSE_HOST_PORT`**, **`TYPESENSE_API_KEY`** — Search engine connection ([`backend/utils/conversations/search.py`](https://github.com/basedhardware/omi/blob/main/backend/utils/conversations/search.py))

## Google Cloud Storage Buckets

File storage requires nine distinct bucket names loaded in [`backend/utils/other/storage.py`](https://github.com/basedhardware/omi/blob/main/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.

```python

# 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`](https://github.com/basedhardware/omi/blob/main/backend/utils/other/hume.py))

## Security and Admin Credentials

Critical security variables include:

- **`ENCRYPTION_SECRET`** — Payload encryption key ([`backend/utils/encryption.py`](https://github.com/basedhardware/omi/blob/main/backend/utils/encryption.py))
- **`WORKFLOW_API_KEY`** — Protects workflow endpoints ([`backend/utils/routers/workflow.py`](https://github.com/basedhardware/omi/blob/main/backend/utils/routers/workflow.py))
- **`ADMIN_KEY`** — Master admin secret for privileged actions ([`backend/routers/updates.py`](https://github.com/basedhardware/omi/blob/main/backend/routers/updates.py))
- **`BASE_API_URL`** — Base URL for internal micro-service calls ([`backend/routers/task_integrations.py`](https://github.com/basedhardware/omi/blob/main/backend/routers/task_integrations.py))
- **`MARKETPLACE_APP_REVIEWERS`** — Comma-separated list of user IDs with review privileges ([`backend/routers/users.py`](https://github.com/basedhardware/omi/blob/main/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`](https://github.com/basedhardware/omi/blob/main/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`](https://github.com/basedhardware/omi/blob/main/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`](https://github.com/basedhardware/omi/blob/main/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`](https://github.com/basedhardware/omi/blob/main/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`](https://github.com/basedhardware/omi/blob/main/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`](https://github.com/basedhardware/omi/blob/main/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.