Skip to main content

​
Overview

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

1

Copy environment files

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

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
3

Start development

mise dev

​
API Environment Variables

​
Always Required

These are required in both development and production:
VariableDescription
ENVdevelopment or production
MONGO_DBMongoDB connection string
REDIS_URLRedis connection string
WORKOS_API_KEYWorkOS API key for authentication
WORKOS_CLIENT_IDWorkOS client ID
WORKOS_COOKIE_PASSWORDSecret for session cookies (min 32 chars)

​
Environment & Deployment

VariableDefaultDescription
HOSThttps://api.heygaia.ioAPI host URL
FRONTEND_URLhttps://heygaia.ioFrontend app URL
ENABLE_PROFILINGfalseEnable performance profiling
SHOW_MISSING_KEY_WARNINGStrueLog warnings for missing keys

​
Database & Message Queue

When using Docker Compose, these have sensible defaults.
VariableDocker DefaultDescription
POSTGRES_URLpostgresql://postgres:postgres@postgres:5432/langgraphPostgreSQL connection
CHROMADB_HOSTchromadbChromaDB vector database host
CHROMADB_PORT8000ChromaDB port
RABBITMQ_URLamqp://guest:guest@rabbitmq:5672/RabbitMQ for message queue

​
Authentication & OAuth

VariableRequiredDescription
GOOGLE_CLIENT_IDProd onlyGoogle OAuth client ID
GOOGLE_CLIENT_SECRETProd onlyGoogle OAuth client secret
DISCORD_OAUTH_CLIENT_IDOptionalDiscord OAuth app client ID
DISCORD_OAUTH_CLIENT_SECRETOptionalDiscord OAuth app client secret
SLACK_OAUTH_CLIENT_IDOptionalSlack OAuth app client ID
SLACK_OAUTH_CLIENT_SECRETOptionalSlack 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

VariableDescription
OPENAI_API_KEYOpenAI API key for GPT models
GOOGLE_API_KEYGoogle AI API key for Gemini

​
Search & Web Content

VariableDescription
TAVILY_API_KEYTavily search API
LLAMA_INDEX_KEYLlamaIndex/LlamaCloud API
FIRECRAWL_API_KEYFirecrawl web scraping
OPENWEATHER_API_KEYOpenWeather API for weather data

​
Media & Content Processing

VariableDescription
ASSEMBLYAI_API_KEYAssemblyAI for speech-to-text
DEEPGRAM_API_KEYDeepgram for audio transcription
CLOUDINARY_CLOUD_NAMECloudinary cloud name
CLOUDINARY_API_KEYCloudinary API key
CLOUDINARY_API_SECRETCloudinary API secret

​
External Integrations

VariableDescription
COMPOSIO_KEYComposio integration key
COMPOSIO_WEBHOOK_SECRETWebhook verification secret
E2B_API_KEYE2B code sandbox API key
RESEND_API_KEYResend email API key
RESEND_AUDIENCE_IDResend audience ID
BLOG_BEARER_TOKENBearer token for blog management

​
Memory & Context

VariableDescription
MEM0_API_KEYMem0 memory API key
MEM0_ORG_IDMem0 organization ID
MEM0_PROJECT_IDMem0 project ID

​
Payments

VariableDescription
DODO_PAYMENTS_API_KEYDodo Payments API key
DODO_WEBHOOK_PAYMENTS_SECRETDodo webhook verification

​
Voice Agent

VariableDescription
LIVEKIT_URLLiveKit server URL
LIVEKIT_API_KEYLiveKit API key
LIVEKIT_API_SECRETLiveKit API secret
AGENT_SECRETVoice agent authentication secret
DEEPGRAM_API_KEYDeepgram speech-to-text API key
ELEVENLABS_API_KEYElevenLabs TTS API key
ELEVENLABS_TTS_MODELElevenLabs TTS model ID
ELEVENLABS_VOICE_IDElevenLabs voice ID
GAIA_BACKEND_URLBackend URL for voice agent

​
Monitoring & Analytics

VariableDescription
SENTRY_DSNSentry error tracking DSN
POSTHOG_API_KEYPostHog analytics API key
OPIK_API_KEYOpik evaluation API key
OPIK_WORKSPACEOpik workspace ID

​
Web Environment Variables

Set these in apps/web/.env:
VariableDescription
NEXT_PUBLIC_API_BASE_URLAPI endpoint (e.g., http://localhost:8000/api/v1/)
NEXT_PUBLIC_BLOG_BEARER_TOKENOptional blog admin token

​
Full 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

# Memory

MEM0_API_KEY=m0xxxx
MEM0_ORG_ID=org-xxxx
MEM0_PROJECT_ID=proj-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.

​
See Also