Environment Variables

Look up what each setting in an .env file does.

Self-hosting? You don’t need this page to get started. gaia up writes a working configuration and generates every secret. See CLI setup. Add AI and tool keys in Settings → Providers & Tools, no file editing needed.

Most variables are optional. A missing key turns off one feature, and the app still starts.

How settings load

Settings live in apps/api/app/config/settings.py and run in one of three modes:

Mode	What is required
Development	Little. Missing keys just disable features
Self-host (`ENV=selfhost`)	Database addresses and machine secrets. Provider keys are set at runtime
Production	Database addresses and secrets. A missing integration key turns that integration off with a warning, and GAIA still boots

Manual setup (contributors)

Copy the example files

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

Set the minimum

In apps/api/.env:

ENV=development
MONGO_DB=mongodb://mongo:27017/gaia
REDIS_URL=redis://redis:6379
AUTH_MODE=local

AUTH_MODE=local gives email-and-password sign-in with no outside service. For WorkOS, use AUTH_MODE=workos and set the WorkOS variables.

Start

mise dev

API Environment Variables

On a self-hosted instance, the provider and tool keys (AI providers, search, Firecrawl, OpenWeather, LlamaParse, GitHub, Cloudinary, Google OAuth, Composio, Resend, E2B) can be set in Settings → Providers & Tools instead, where they are stored encrypted. The environment variable is used when nothing is saved there.

Always Required

These are required in every mode:

Variable	Description
`ENV`	`development`, `production`, or `selfhost`
`MONGO_DB`	MongoDB connection string
`REDIS_URL`	Redis connection string

In production and self-host, these are also required:

Variable	Description
`POSTGRES_URL`	PostgreSQL connection (optional in development)
`RABBITMQ_URL`	RabbitMQ connection (optional in development)
`AGENT_SECRET`	Voice agent authentication secret
`BOT_SESSION_TOKEN_SECRET`	Secret for bot session tokens (min 32 chars)
`EMAIL_UNSUBSCRIBE_SECRET`	Secret for signing unsubscribe links

Instance & Auth Mode

Variable	Default	Description
`AUTH_MODE`	`workos`	`local` (email + password sign-in) or `workos` (AuthKit hosted UI). Self-host uses `local`; production refuses it.
`INSTANCE_SECRET`	generated	Signs local sessions and derives the key that encrypts stored provider credentials. `gaia up` writes a random one into `.env` on a fresh install, which keeps the key out of the database. If it is unset, a secret is generated on first boot and stored in the database next to the credentials it encrypts, so anyone with a database dump can decrypt them. Never change it once credentials are stored.
`OLLAMA_BASE_URL`	unset	Ollama endpoint as seen by the backend; unset means no Ollama lane. Inside Docker use `http://host.docker.internal:11434`; native runs use `localhost`.

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
`BLOB_STORE`	per deployment	Where uploaded and generated files live: `local` (self-host), `s3` or `cloudinary`. Never `local` in production
`LOCAL_FILE_STORAGE_PATH`	`/var/lib/gaia/files`	Folder for files under `BLOB_STORE=local`; the self-host compose mounts a volume here
`S3_ENDPOINT_URL`	unset	S3 API URL of the bucket service under `BLOB_STORE=s3`, such as `https://<account>.r2.cloudflarestorage.com`. Required with `s3`
`S3_BUCKET`	unset	Bucket name under `BLOB_STORE=s3`. Required with `s3`
`S3_ACCESS_KEY_ID`	unset	Access key for the bucket. Required with `s3`
`S3_SECRET_ACCESS_KEY`	unset	Secret key for the bucket. Required with `s3`
`S3_REGION`	unset	Signing region, such as `auto` on R2 and Railway. Unset signs for `us-east-1`
`S3_ADDRESSING_STYLE`	`virtual`	`virtual` puts the bucket in the host name (AWS, R2, B2, Railway); `path` puts it in the path (MinIO, older Railway buckets)
`LOOPBACK_HOST_ALIAS`	unset	Hostname that reaches the host from inside the container (`host.docker.internal` in the self-host compose), so a custom MCP server added as `localhost` still works

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
`WORKOS_API_KEY`	Only when `AUTH_MODE=workos`	WorkOS API key for authentication
`WORKOS_CLIENT_ID`	Only when `AUTH_MODE=workos`	WorkOS client ID
`WORKOS_COOKIE_PASSWORD`	Only when `AUTH_MODE=workos`	Secret for session cookies (min 32 chars)
`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

AUTH_MODE selects the sign-in method: workos routes users through WorkOS’s AuthKit hosted UI, while local enables first-party email + password accounts (the self-host default, also usable in development so contributors need no WorkOS account — the first account created becomes the instance admin, and others join by invite link from Settings → Members). The three WORKOS_* variables are validated and required only when AUTH_MODE=workos.

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

Self-host: set these in Settings → Providers & Tools instead. The variables are fallbacks, and a saved key wins.

Variable	Description
`OPENROUTER_API_KEY`	OpenRouter API key
`OPENAI_API_KEY`	OpenAI API key
`GOOGLE_API_KEY`	Google AI API key for Gemini; also embeds tools for tool search (without it, a local model does that)
`OLLAMA_BASE_URL`	Ollama endpoint (see Instance & Auth Mode)

OpenAI-compatible gateways (OpenCode, Nous Research, or any custom endpoint) are also configured through Settings → Providers & Tools.

Search & Web Content

Variable	Description
`TAVILY_API_KEY`	Tavily search API
`LLAMA_INDEX_KEY`	LlamaParse, for reading scanned PDFs (text PDFs and Office files need no key)
`FIRECRAWL_API_KEY`	Firecrawl web scraping
`OPENWEATHER_API_KEY`	OpenWeather API for weather data
`EXA_API_KEY`	Exa web search
`BRAVE_API_KEY`	Brave web search
`SEARXNG_BASE_URL`	A SearXNG instance for web search, no key

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
`LOCAL_CODE_SANDBOX`	Self-host only: run code in local Docker containers when no E2B key is set. Set by the `docker-compose.sandbox.yml` override (`gaia up --code-sandbox`), which also mounts the Docker socket; never set it by hand
`LOCAL_SANDBOX_LAB_EVENTS_CALLBACK_URL`	Self-host only: where coding-agent runs in a local sandbox report back (the proxy on the host gateway). Set by the same `docker-compose.sandbox.yml` override
`RESEND_API_KEY`	Resend email API key
`RESEND_AUDIENCE_ID`	Resend audience ID
`BLOG_BEARER_TOKEN`	Bearer token for blog management

Memory & Context

Memory runs locally on PostgreSQL, ChromaDB and a local embedding model. No keys are needed, and the defaults work.

Tuning variables

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
`MEMORY_EMBEDDING_SIDECAR_CONCURRENCY`	Max in-flight sidecar inferences (default `cores / MEMORY_ONNX_THREADS`)
`MEMORY_ONNX_THREADS`	ONNX intra-op threads per inference (default `4`)
`MEMORY_SIDECAR_MAX_BATCH_TEXTS`	Max texts per embedding forward pass / per HTTP call (default `16`)
`MEMORY_SIDECAR_MAX_BATCH_CHARS`	Max total characters per embed/rerank HTTP chunk (default `64000`)
`MEMORY_SIDECAR_MAX_TEXT_CHARS`	Hard cap on a single text; larger inputs are rejected with `413` (default `65000`)
`MEMORY_SIDECAR_SLOT_WAIT_SECONDS`	How long a request waits for an inference slot before `503` (default `20`)
`MEMORY_SIDECAR_RETRIES`	Retries for transient sidecar failures (`429`/`503`/connection errors) before failing (default `2`)
`MEMORY_SIDECAR_RETRY_MAX_WAIT_SECONDS`	Backoff between sidecar retries in seconds (default `5`)
`MEMORY_MODEL_CACHE_DIR`	Persistent cache for fastembed model weights (~1.85GB, avoids re-download)
`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

Self-host never contacts Dodo, so no payment keys are needed.

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_PROJECT_TOKEN`	PostHog project token
`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 (development, local auth)

# 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 — email + password, no external provider needed

AUTH_MODE=local

# To use WorkOS instead, set AUTH_MODE=workos and add:
# 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 — or configure in Settings → Providers & Tools)

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_PROJECT_TOKEN=phc_xxxx

Minimal apps/api/.env example (self-host)

gaia up generates this for you — shown here for reference:

ENV=selfhost
AUTH_MODE=local

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 # container port (8080 is host-mapped only)
RABBITMQ_URL=amqp://guest:guest@rabbitmq:5672/

# Generated per machine by gaia up — never commit these anywhere
AGENT_SECRET=<generated>
BOT_SESSION_TOKEN_SECRET=<generated>
EMAIL_UNSUBSCRIBE_SECRET=<generated>

Everything else is optional. AI provider keys are added at runtime in Settings → Providers & Tools; Infisical is never contacted.

Generate the file for you

gaia up writes a complete self-host configuration. For a source checkout, run the interactive wizard:

gaia init

It reads the config schema and .env.example, asks only for missing values, and checks the result.

Get Started

Configure

Connect Apps

Use It Everywhere

Maintain

Reference

How settings load

Manual setup (contributors)

API Environment Variables

Always Required

Instance & Auth Mode

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

Generate the file for you

See Also

​How settings load

​Manual setup (contributors)

​API Environment Variables

​Always Required

​Instance & Auth Mode

​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

​Generate the file for you

​See Also

How settings load

Manual setup (contributors)

API Environment Variables

Always Required

Instance & Auth Mode

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

Generate the file for you

See Also