Environment Variables

Atlas can be configured entirely via environment variables. Most have safe defaults — a minimal deployment needs only an LLM provider key and a datasource URL. For multi-datasource setups or advanced configuration, see the Configuration reference.

Precedence

Config loading is binary — when atlas.config.ts exists, it is used exclusively for structure. Env vars like ATLAS_DATASOURCE_URL are not merged in as fallbacks. Fields omitted from the config file get Zod schema defaults, not env var values.

1. Config file found → all structural config (datasources, tools, semanticLayer, plugins, actions, rls, scheduler) comes from the file
2. No config file → all configuration comes from environment variables
3. Some vars are always env-only — secrets (ANTHROPIC_API_KEY, BETTER_AUTH_SECRET), runtime hints (ATLAS_RUNTIME), and networking (PORT, ATLAS_CORS_ORIGIN) are always read from environment variables regardless of config file presence
4. Auth mode can be set via the config file auth field or ATLAS_AUTH_MODE env var. Priority: env var → config file → auto-detection

See the Configuration reference for the full atlas.config.ts guide.

LLM Provider

LLM provider and model configuration.

When ATLAS_PROVIDER is not set, the default depends on the runtime environment. On Vercel (detected via the platform-set VERCEL env var), the default is gateway. Everywhere else, the default is anthropic.

Each provider requires its own API key:

Default models per provider:

# Anthropic (default provider)
ATLAS_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
# Optional: override the default model
# ATLAS_MODEL=claude-sonnet-4-6

# OpenAI
ATLAS_PROVIDER=openai
OPENAI_API_KEY=sk-...
# Optional: override the default model
# ATLAS_MODEL=gpt-4o

# AWS Bedrock (uses IAM credentials)
ATLAS_PROVIDER=bedrock
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...

# Ollama (local, no API key needed)
ATLAS_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434/v1
# Optional: override the default model
# ATLAS_MODEL=llama3.1

# Any OpenAI-compatible server (vLLM, TGI, LiteLLM, LocalAI)
ATLAS_PROVIDER=openai-compatible
ATLAS_MODEL=llama3.1                           # Required — no default
OPENAI_COMPATIBLE_BASE_URL=http://localhost:8000/v1  # Required
# OPENAI_COMPATIBLE_API_KEY=...                # Optional — most local servers don't need one

Database

Demo data fallback chain: When ATLAS_DEMO_DATA=true and ATLAS_DATASOURCE_URL is not set, Atlas resolves the analytics datasource by checking DATABASE_URL_UNPOOLED first, then DATABASE_URL. This lets a single Postgres instance (e.g. Neon on Vercel) serve as both the analytics datasource and Atlas's internal database.

# Local dev: Docker Compose provisions both databases
DATABASE_URL=postgresql://atlas:atlas@localhost:5432/atlas
ATLAS_DATASOURCE_URL=postgresql://atlas:atlas@localhost:5432/atlas_demo

# Production: separate databases for isolation
DATABASE_URL=postgresql://user:pass@internal-host:5432/atlas
ATLAS_DATASOURCE_URL=postgresql://readonly:pass@analytics-host:5432/warehouse

# Vercel with Neon: single Postgres for everything
DATABASE_URL=postgresql://...@neon-host/atlas?sslmode=require
ATLAS_DEMO_DATA=true
# ATLAS_DATASOURCE_URL not needed — falls back to DATABASE_URL

Agent

Security

Query safety and SQL validation settings. See SQL Validation Pipeline for how these are enforced.

# Production: tighter limits
ATLAS_ROW_LIMIT=500           # Fewer rows per query
ATLAS_QUERY_TIMEOUT=15000     # 15s timeout (default: 30s)
ATLAS_TABLE_WHITELIST=true    # Only semantic layer tables (default)
ATLAS_SCHEMA=analytics        # Non-default PostgreSQL schema

Auth

Authentication mode and per-mode settings. See Authentication for full setup guides.

When ATLAS_AUTH_MODE is not set, Atlas auto-detects based on which variables are present (checked in this order):

1. ATLAS_AUTH_JWKS_URL set → BYOT
2. BETTER_AUTH_SECRET set → Managed
3. ATLAS_API_KEY set → Simple Key
4. None of the above → No auth

Simple Key

# Simple key auth for headless integrations
ATLAS_API_KEY=your-secret-key-here
ATLAS_API_KEY_ROLE=analyst

Managed (Better Auth)

# Managed auth for multi-user web apps
BETTER_AUTH_SECRET=$(openssl rand -base64 32)
BETTER_AUTH_URL=https://api.example.com
BETTER_AUTH_TRUSTED_ORIGINS=https://app.example.com
ATLAS_ADMIN_EMAIL=admin@example.com
DATABASE_URL=postgresql://user:pass@host:5432/atlas

Social Login (OAuth)

Optional. Only applies to managed auth. Uncomment a provider block to enable social sign-in alongside email/password. Providers are auto-detected — only those with both CLIENT_ID and CLIENT_SECRET set are enabled.

# Enable Google + GitHub social login
GOOGLE_CLIENT_ID=123456789.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-...
GITHUB_CLIENT_ID=Iv1.abc123
GITHUB_CLIENT_SECRET=ghs_...

BYOT (Bring Your Own Token)

# BYOT with Auth0
ATLAS_AUTH_JWKS_URL=https://your-tenant.auth0.com/.well-known/jwks.json
ATLAS_AUTH_ISSUER=https://your-tenant.auth0.com/
ATLAS_AUTH_AUDIENCE=https://api.example.com
# Nested claim for role extraction
ATLAS_AUTH_ROLE_CLAIM=app_metadata.atlas_role

Rate Limiting

# Production rate limiting behind a reverse proxy
ATLAS_RATE_LIMIT_RPM=30
ATLAS_TRUST_PROXY=true

See Rate Limiting & Retry for client-side handling, SDK retry patterns, and troubleshooting.

Abuse Prevention

# Stricter abuse detection for production
ATLAS_ABUSE_QUERY_RATE=100
ATLAS_ABUSE_ERROR_RATE=0.3
ATLAS_ABUSE_THROTTLE_DELAY_MS=5000

See Abuse Prevention for details on graduated response and admin reinstatement.

Session Timeouts

# 1 hour idle timeout, 24 hour absolute timeout
ATLAS_SESSION_IDLE_TIMEOUT=3600
ATLAS_SESSION_ABSOLUTE_TIMEOUT=86400

These can also be configured via atlas.config.ts or changed at runtime via Admin > Settings.

Multi-Tenancy

Semantic Layer

For additional index configuration, use atlas.config.ts.

# Development: override semantic layer location (for production, use atlas.config.ts)
ATLAS_SEMANTIC_ROOT=/tmp/test-semantic

# Disable pre-computed index (agent will use explore tool instead)
ATLAS_SEMANTIC_INDEX_ENABLED=false

Row-Level Security

Env var shorthand for a single global RLS policy. For per-table policies, use atlas.config.ts. See Row-Level Security for the full guide.

# Single global RLS policy via env vars
ATLAS_RLS_ENABLED=true
ATLAS_RLS_COLUMN=tenant_id
ATLAS_RLS_CLAIM=org_id

# Static claims for simple-key auth
ATLAS_RLS_CLAIMS='{"tenant_id": "acme-corp"}'

Sandbox & Isolation

Explore tool isolation backends. See Sandbox Architecture for the full selection priority.

# Local dev: sidecar via docker compose (bun run db:up)
ATLAS_SANDBOX_URL=http://localhost:8080

# Production: sidecar as a separate service
ATLAS_SANDBOX_URL=http://sandbox-sidecar:8080
# Optional: shared secret for sidecar auth
SIDECAR_AUTH_TOKEN=your-shared-secret

# Self-hosted: nsjail for process isolation
ATLAS_SANDBOX=nsjail
# Optional: tune limits
ATLAS_NSJAIL_TIME_LIMIT=10
ATLAS_NSJAIL_MEMORY_LIMIT=256

Networking & CORS

# Production: cross-origin setup
ATLAS_CORS_ORIGIN=https://app.example.com
NEXT_PUBLIC_ATLAS_API_URL=https://api.example.com
ATLAS_PUBLIC_URL=https://api.example.com

Data Residency

Settings for multi-region deployments with per-workspace region routing. See also residency in atlas.config.ts and the Data Residency guide.

Appearance

Actions

Action framework settings. These can also be configured via atlas.config.ts. See the Actions guide for the full setup.

# Enable actions with admin-only approval
ATLAS_ACTIONS_ENABLED=true
ATLAS_ACTION_APPROVAL=admin-only
# Restrict email recipients to your domain
ATLAS_EMAIL_ALLOWED_DOMAINS=example.com,trusted-partner.com

Scheduler

Scheduled task execution. Can also be configured via atlas.config.ts. See Scheduled Tasks for the full guide.

Scheduler backend options:

• bun — In-process tick loop. Simplest for single-instance deployments.
• webhook — External cron service hits POST /:id/run. Use when you need external scheduling.
• vercel — Vercel Cron hits POST /tick. Use on Vercel deployments.

Dynamic Learning

Python Tool

See Python Tool for the full guide.

Email Delivery

Slack Integration

See Slack guide for the full setup.

Discord Integration

# Discord integration for guild (server) authorization
DISCORD_CLIENT_ID=123456789012345678
DISCORD_CLIENT_SECRET=your-discord-client-secret

Teams Integration

# Teams integration via Azure AD admin consent
TEAMS_APP_ID=your-teams-app-id

JIRA Integration

Requires the action framework to be enabled (ATLAS_ACTIONS_ENABLED=true).

# JIRA integration for the createJiraTicket action
JIRA_BASE_URL=https://yourorg.atlassian.net
JIRA_EMAIL=you@example.com
JIRA_API_TOKEN=your-api-token
JIRA_DEFAULT_PROJECT=PROJ

Stripe Billing

Stripe billing integration for SaaS deployments. Self-hosted deployments do not need these — the self-hosted experience has no billing or usage limits.

When STRIPE_SECRET_KEY is set, billing routes are mounted at /api/v1/billing and the Better Auth Stripe plugin handles checkout, webhooks, and subscription lifecycle at /api/auth/stripe/*.

For local development, use Stripe CLI to forward webhooks:

stripe listen --forward-to localhost:3001/api/auth/stripe/webhook

Enterprise

These can also be configured via atlas.config.ts.

SLA Monitoring

SaaS only. Thresholds for SLA alerting.

Backups

SaaS only. Automated internal database backups.

Custom Domains (Railway)

SaaS only. Required for custom domain support via Railway.

Demo Mode

Requires BETTER_AUTH_SECRET for demo token signing.

Runtime

Settings

Status Page

Logging & Observability

See Observability for the full setup guide.

See Also

• Configuration — Declarative atlas.config.ts for multi-datasource, plugins, and RLS
• Deploy — Platform-specific env var setup for Railway, Vercel, and Docker
• Authentication — Auth mode setup and required variables
• CLI Reference — atlas doctor validates your environment configuration
• Troubleshooting — Diagnosing startup errors from missing or invalid variables