Skip to main content

​
Environment Configuration

GAIA uses many integrations, but you don’t need all keys to start. We load env via Pydantic settings and lazily initialize providers only when first used. See: Lazy Loading Env. Variables.

​
What you must set

  • Backend (always required in all envs): MONGO_DB, REDIS_URL, WORKOS_API_KEY, WORKOS_CLIENT_ID, WORKOS_COOKIE_PASSWORD
  • Production adds: databases/queues + integration keys are required (see ProductionSettings)
  • Development: most integrations are optional; missing keys only disable that feature

​
Minimal .env to boot locally

Create backend/.env with just the essentials. If you use Docker, defaults are provided by Compose. 
# Core
ENV=development
HOST=http://localhost:8000
FRONTEND_URL=http://localhost:3000

# Datastores (use docker defaults or set your own)
MONGO_DB=mongodb://mongo:27017/gaia
REDIS_URL=redis://redis:6379

# Auth (WorkOS for sessions)
WORKOS_API_KEY=your-workos-api-key
WORKOS_CLIENT_ID=your-workos-client-id
WORKOS_COOKIE_PASSWORD=your-random-cookie-secret

​
Optional keys by feature (add when needed)

  • LLMs: OPENAI_API_KEY or GOOGLE_API_KEY (Gemini) or HUGGINGFACE_API_KEY
  • Speech: ASSEMBLYAI_API_KEY, DEEPGRAM_API_KEY
  • Search & web content: TAVILY_API_KEY, FIRECRAWL_API_KEY, OPENWEATHER_API_KEY
  • Cloud media (uploads/images): CLOUDINARY_CLOUD_NAME, CLOUDINARY_API_KEY, CLOUDINARY_API_SECRET
  • Auth (Google OAuth): GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
  • Code exec sandbox: E2B_API_KEY
  • Memory (Mem0): MEM0_API_KEY, MEM0_ORG_ID, MEM0_PROJECT_ID
  • Email: RESEND_API_KEY, RESEND_AUDIENCE_ID
  • Blog admin: BLOG_BEARER_TOKEN
  • Queues/DB (prod): POSTGRES_URL, RABBITMQ_URL, CHROMADB_HOST, CHROMADB_PORT
  • Composio: COMPOSIO_KEY, COMPOSIO_WEBHOOK_SECRET
  • Telemetry: SENTRY_DSN, POSTHOG_API_KEY
Add only what you need; dev will warn and the feature stays inactive until keys are added.

​
Backend Environment Variables (reference)

# Core application
ENV=development
HOST=localhost
FRONTEND_URL=http://localhost:3000
DISABLE_PROFILING=true

# Databases & queues (Docker defaults)
POSTGRES_URL=postgresql://postgres:postgres@postgres:5432/langgraph
MONGO_DB=mongodb://mongo:27017/gaia
REDIS_URL=redis://redis:6379
CHROMADB_HOST=chromadb
CHROMADB_PORT=8000
RABBITMQ_URL=amqp://guest:guest@rabbitmq:5672/

# Auth (WorkOS mandatory), Google OAuth optional in dev
WORKOS_API_KEY=your-workos-api-key
WORKOS_CLIENT_ID=your-workos-client-id
WORKOS_COOKIE_PASSWORD=your-random-cookie-secret
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# Selected integrations (add when used)
OPENAI_API_KEY=sk-your-openai-api-key
GOOGLE_API_KEY=your-google-ai-api-key
HUGGINGFACE_API_KEY=hf_your-huggingface-token
ASSEMBLYAI_API_KEY=your-assemblyai-api-key
DEEPGRAM_API_KEY=your-deepgram-api-key
TAVILY_API_KEY=your-tavily-api-key
FIRECRAWL_API_KEY=your-firecrawl-api-key
OPENWEATHER_API_KEY=your-openweather-api-key
E2B_API_KEY=your-e2b-api-key
CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-cloudinary-api-key
CLOUDINARY_API_SECRET=your-cloudinary-api-secret
MEM0_API_KEY=your-mem0-api-key
MEM0_ORG_ID=your-mem0-org-id
MEM0_PROJECT_ID=your-mem0-project-id
RESEND_API_KEY=your-resend-api-key
RESEND_AUDIENCE_ID=your-resend-audience-id
BLOG_BEARER_TOKEN=your-blog-bearer-token
COMPOSIO_KEY=your-composio-key
COMPOSIO_WEBHOOK_SECRET=your-composio-webhook-secret
SENTRY_DSN=your-sentry-dsn
POSTHOG_API_KEY=your-posthog-api-key

​
Frontend Environment Variables

Frontend envs are typically local and added as needed during build.
# Base url of the backend api
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000/api/v1/

# Optional blog token for admin blog actions
NEXT_PUBLIC_BLOG_BEARER_TOKEN=your-blog-management-token-here

​
See also