> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heygaia.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables

> Complete guide to configuring environment variables for GAIA

## Why you need this

GAIA is several apps (API, web, bots) talking to several services (PostgreSQL, MongoDB, Redis, LLM providers, OAuth integrations). Environment variables are how each app finds those services and authenticates with them. If you're self-hosting or developing locally, this page is the reference for what goes in each `.env` file and what happens when something is missing.

You rarely need all of them: a minimal local setup needs only the database URLs and auth keys shown in Manual Setup below. Everything else enables a specific feature, skip a key and that feature is disabled, but the app still runs.

GAIA uses Pydantic settings to load environment variables with validation. Settings are defined in `apps/api/app/config/settings.py` with two modes:

* **Development**: Most keys optional, missing ones just disable features
* **Production**: All integration keys required for full functionality

<Note>
  Variables are lazily loaded: the app starts even with missing keys.
</Note>

<Tip>
  **Automated Setup**: The [GAIA CLI](/cli/installation) automatically discovers required environment variables from your codebase using Python AST parsing (for API) and source analysis (for Web). Run `gaia init` to skip manual configuration.
</Tip>

***

## Manual Setup

<Steps>
  <Step title="Copy environment files">
    ```bash theme={null}
    cp apps/api/.env.example apps/api/.env 
    cp apps/web/.env.example apps/web/.env 
    ```
  </Step>

  <Step title="Set required variables">
    At minimum, set these in `apps/api/.env`:

    ```bash theme={null}
    ENV=development
    MONGO_DB=mongodb://mongo:27017/gaia 
    REDIS_URL=redis://redis:6379
    WORKOS_API_KEY=your-workos-api-key 
    WORKOS_CLIENT_ID=your-workos-client-id
    WORKOS_COOKIE_PASSWORD=your-32-char-random-secret 
    ```
  </Step>

  <Step title="Start development">
    ```bash theme={null}
    mise dev 
    ```
  </Step>
</Steps>

***

## API Environment Variables

### Always Required

These are required in **both** development and production:

| Variable                 | Description                               |
| ------------------------ | ----------------------------------------- |
| `ENV`                    | `development` or `production`             |
| `MONGO_DB`               | MongoDB connection string                 |
| `REDIS_URL`              | Redis connection string                   |
| `WORKOS_API_KEY`         | WorkOS API key for authentication         |
| `WORKOS_CLIENT_ID`       | WorkOS client ID                          |
| `WORKOS_COOKIE_PASSWORD` | Secret for session cookies (min 32 chars) |

### Environment & Deployment

| Variable                    | Default                  | Description                   |
| --------------------------- | ------------------------ | ----------------------------- |
| `HOST`                      | `https://api.heygaia.io` | API host URL                  |
| `FRONTEND_URL`              | `https://heygaia.io`     | Frontend app URL              |
| `ENABLE_PROFILING`          | `false`                  | Enable performance profiling  |
| `SHOW_MISSING_KEY_WARNINGS` | `true`                   | Log warnings for missing keys |

***

### Database & Message Queue

<Note>When using Docker Compose, these have sensible defaults.</Note>

| Variable        | Docker Default                                           | Description                   |
| --------------- | -------------------------------------------------------- | ----------------------------- |
| `POSTGRES_URL`  | `postgresql://postgres:postgres@postgres:5432/langgraph` | PostgreSQL connection         |
| `CHROMADB_HOST` | `chromadb`                                               | ChromaDB vector database host |
| `CHROMADB_PORT` | `8000`                                                   | ChromaDB port                 |
| `RABBITMQ_URL`  | `amqp://guest:guest@rabbitmq:5672/`                      | RabbitMQ for message queue    |

***

### Authentication & OAuth

| Variable                      | Required  | Description                     |
| ----------------------------- | --------- | ------------------------------- |
| `GOOGLE_CLIENT_ID`            | Prod only | Google OAuth client ID          |
| `GOOGLE_CLIENT_SECRET`        | Prod only | Google OAuth client secret      |
| `DISCORD_OAUTH_CLIENT_ID`     | Optional  | Discord OAuth app client ID     |
| `DISCORD_OAUTH_CLIENT_SECRET` | Optional  | Discord OAuth app client secret |
| `SLACK_OAUTH_CLIENT_ID`       | Optional  | Slack OAuth app client ID       |
| `SLACK_OAUTH_CLIENT_SECRET`   | Optional  | Slack OAuth app client secret   |

<Note>
  Computed OAuth callback URLs are generated automatically: -
  `WORKOS_REDIRECT_URI` → `{HOST}/api/v1/oauth/workos/callback` -
  `GOOGLE_CALLBACK_URL` → `{HOST}/api/v1/oauth/google/callback` -
  `COMPOSIO_REDIRECT_URI` → `{HOST}/api/v1/oauth/composio/callback` -
  `DISCORD_OAUTH_REDIRECT_URI` → `{HOST}/api/v1/platform-auth/discord/callback` -
  `SLACK_OAUTH_REDIRECT_URI` → `{HOST}/api/v1/platform-auth/slack/callback`
</Note>

<Note>
  `DISCORD_OAUTH_CLIENT_ID` and `SLACK_OAUTH_CLIENT_ID` are optional, without them, users must link their accounts using the `/auth` bot command instead of the web UI. See [Discord Bot](/bots/discord) and [Slack Bot](/bots/slack) for setup instructions.
</Note>

***

### AI & Machine Learning

| Variable         | Description                   |
| ---------------- | ----------------------------- |
| `OPENAI_API_KEY` | OpenAI API key for GPT models |
| `GOOGLE_API_KEY` | Google AI API key for Gemini  |

***

### Search & Web Content

| Variable              | Description                      |
| --------------------- | -------------------------------- |
| `TAVILY_API_KEY`      | Tavily search API                |
| `LLAMA_INDEX_KEY`     | LlamaIndex/LlamaCloud API        |
| `FIRECRAWL_API_KEY`   | Firecrawl web scraping           |
| `OPENWEATHER_API_KEY` | OpenWeather API for weather data |

***

### Media & Content Processing

| Variable                | Description                      |
| ----------------------- | -------------------------------- |
| `ASSEMBLYAI_API_KEY`    | AssemblyAI for speech-to-text    |
| `DEEPGRAM_API_KEY`      | Deepgram for audio transcription |
| `CLOUDINARY_CLOUD_NAME` | Cloudinary cloud name            |
| `CLOUDINARY_API_KEY`    | Cloudinary API key               |
| `CLOUDINARY_API_SECRET` | Cloudinary API secret            |

***

### External Integrations

| Variable                  | Description                      |
| ------------------------- | -------------------------------- |
| `COMPOSIO_KEY`            | Composio integration key         |
| `COMPOSIO_WEBHOOK_SECRET` | Webhook verification secret      |
| `E2B_API_KEY`             | E2B code sandbox API key         |
| `RESEND_API_KEY`          | Resend email API key             |
| `RESEND_AUDIENCE_ID`      | Resend audience ID               |
| `BLOG_BEARER_TOKEN`       | Bearer token for blog management |

***

### Memory & Context

GAIA's memory runs on a self-hosted engine (PostgreSQL + ChromaDB + local
embeddings) — no external API keys are required. All variables below are
optional and have sensible defaults.

| Variable                        | Description                                                               |
| ------------------------------- | ------------------------------------------------------------------------- |
| `GAIA_EMBEDDING_MODEL`          | Embedding model name (default `mixedbread-ai/mxbai-embed-large-v1`)       |
| `GAIA_EMBEDDING_DIM`            | Embedding vector dimension (default `1024`)                               |
| `MEMORY_EMBEDDING_SIDECAR_URL`  | URL of a shared embedding sidecar; loads the model in-process when unset  |
| `GAIA_CHROMA_COLLECTION_SUFFIX` | Suffix appended to ChromaDB collection names (for isolating environments) |

***

### Payments

| Variable                       | Description               |
| ------------------------------ | ------------------------- |
| `DODO_PAYMENTS_API_KEY`        | Dodo Payments API key     |
| `DODO_WEBHOOK_PAYMENTS_SECRET` | Dodo webhook verification |

***

### Voice Agent

| Variable               | Description                       |
| ---------------------- | --------------------------------- |
| `LIVEKIT_URL`          | LiveKit server URL                |
| `LIVEKIT_API_KEY`      | LiveKit API key                   |
| `LIVEKIT_API_SECRET`   | LiveKit API secret                |
| `AGENT_SECRET`         | Voice agent authentication secret |
| `DEEPGRAM_API_KEY`     | Deepgram speech-to-text API key   |
| `ELEVENLABS_API_KEY`   | ElevenLabs TTS API key            |
| `ELEVENLABS_TTS_MODEL` | ElevenLabs TTS model ID           |
| `ELEVENLABS_VOICE_ID`  | ElevenLabs voice ID               |
| `GAIA_BACKEND_URL`     | Backend URL for voice agent       |

***

### Monitoring & Analytics

| Variable          | Description               |
| ----------------- | ------------------------- |
| `SENTRY_DSN`      | Sentry error tracking DSN |
| `POSTHOG_API_KEY` | PostHog analytics API key |
| `OPIK_API_KEY`    | Opik evaluation API key   |
| `OPIK_WORKSPACE`  | Opik workspace ID         |

***

## Web Environment Variables

Set these in `apps/web/.env`:

| Variable                        | Description                                          |
| ------------------------------- | ---------------------------------------------------- |
| `NEXT_PUBLIC_API_BASE_URL`      | API endpoint (e.g., `http://localhost:8000/api/v1/`) |
| `NEXT_PUBLIC_BLOG_BEARER_TOKEN` | Optional blog admin token                            |

***

## Full Example

<Accordion title="Complete apps/api/.env example">
  ```bash theme={null}
  # Environment
  ENV=development
  HOST=http://localhost:8000
  FRONTEND_URL=http://localhost:3000

  # Databases (Docker defaults)

  MONGO_DB=mongodb://mongo:27017/gaia
  REDIS_URL=redis://redis:6379
  POSTGRES_URL=postgresql://postgres:postgres@postgres:5432/langgraph
  CHROMADB_HOST=chromadb
  CHROMADB_PORT=8000
  RABBITMQ_URL=amqp://guest:guest@rabbitmq:5672/

  # Auth (required)

  WORKOS_API_KEY=sk_test_xxxx
  WORKOS_CLIENT_ID=client_xxxx
  WORKOS_COOKIE_PASSWORD=your-32-character-random-secret

  # Google OAuth (optional in dev)

  GOOGLE_CLIENT_ID=xxxx.apps.googleusercontent.com
  GOOGLE_CLIENT_SECRET=GOCSPX-xxxx

  # AI (add what you need)

  OPENAI_API_KEY=sk-xxxx
  GOOGLE_API_KEY=AIza-xxxx

  # Search & Tools

  TAVILY_API_KEY=tvly-xxxx
  FIRECRAWL_API_KEY=fc-xxxx

  # Media

  CLOUDINARY_CLOUD_NAME=your-cloud
  CLOUDINARY_API_KEY=xxxx
  CLOUDINARY_API_SECRET=xxxx

  # Monitoring

  SENTRY_DSN=https://xxxx@sentry.io/xxxx
  POSTHOG_API_KEY=phc_xxxx

  ```
</Accordion>

***

## CLI Auto-Discovery

The GAIA CLI can automatically discover and configure environment variables:

```bash theme={null}
# Interactive setup with auto-discovery
gaia init

# Or run setup separately
gaia setup
```

The CLI auto-discovery process:

* **Parses `settings.py`**: Uses Python AST parsing to extract all environment variable definitions
* **Scans `.env.example`**: Identifies required variables from example files
* **Prompts for missing values**: Interactive prompts for any undefined variables
* **Validates configuration**: Ensures all critical variables are properly set

This eliminates manual `.env` file editing and reduces configuration errors.

***

## See Also

* [Development Setup](/developers/development-setup)