Environment Variables

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

Variables are lazily loaded: the app starts even with missing keys.

Automated Setup: The GAIA CLI 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.

Manual Setup

Copy environment files

cp apps/api/.env.example apps/api/.env 
cp apps/web/.env.example apps/web/.env 

Set required variables

At minimum, set these in apps/api/.env:

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 

Start development

mise dev

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

When using Docker Compose, these have sensible defaults.

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

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

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 and Slack Bot for setup instructions.

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

Complete apps/api/.env example

# 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

CLI Auto-Discovery

The GAIA CLI can automatically discover and configure environment variables:

# 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.

Getting Started

Self-Hosting

CLI

Contributing

Bot Development

Conventions

Why you need this

Manual Setup

API Environment Variables

Always Required

Environment & Deployment

Database & Message Queue

Authentication & OAuth

AI & Machine Learning

Search & Web Content

Media & Content Processing

External Integrations

Memory & Context

Payments

Voice Agent

Monitoring & Analytics

Web Environment Variables

Full Example

CLI Auto-Discovery

See Also

​Why you need this

​Manual Setup

​API Environment Variables

​Always Required

​Environment & Deployment

​Database & Message Queue

​Authentication & OAuth

​AI & Machine Learning

​Search & Web Content

​Media & Content Processing

​External Integrations

​Memory & Context

​Payments

​Voice Agent

​Monitoring & Analytics

​Web Environment Variables

​Full Example

​CLI Auto-Discovery

​See Also

Why you need this

Manual Setup

API Environment Variables

Always Required

Environment & Deployment

Database & Message Queue

Authentication & OAuth

AI & Machine Learning

Search & Web Content

Media & Content Processing

External Integrations

Memory & Context

Payments

Voice Agent

Monitoring & Analytics

Web Environment Variables

Full Example

CLI Auto-Discovery

See Also