Skip to main content

​
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

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

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.
VariableDescription
GAIA_EMBEDDING_MODELEmbedding model name (default mixedbread-ai/mxbai-embed-large-v1)
GAIA_EMBEDDING_DIMEmbedding vector dimension (default 1024)
MEMORY_EMBEDDING_SIDECAR_URLURL of a shared embedding sidecar; loads the model in-process when unset
GAIA_CHROMA_COLLECTION_SUFFIXSuffix appended to ChromaDB collection names (for isolating environments)

​
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

# 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