Environment Variables

Complete reference for all Atlas environment variables with defaults and examples.

All Atlas configuration is via environment variables. Most have safe defaults — a minimal deployment needs only an LLM provider key and a datasource URL.

LLM Provider

Variable	Default	Description
`ATLAS_PROVIDER`	`anthropic` (`gateway` on Vercel)	LLM provider: `anthropic`, `openai`, `bedrock`, `ollama`, `gateway`
`ATLAS_MODEL`	Provider default	Model ID override (e.g. `claude-sonnet-4-6`, `gpt-4o`)
`OLLAMA_BASE_URL`	`http://localhost:11434/v1`	Ollama server URL. Only used when `ATLAS_PROVIDER=ollama`

Each provider requires its own API key:

Provider	API Key Variable
`anthropic`	`ANTHROPIC_API_KEY`
`openai`	`OPENAI_API_KEY`
`bedrock`	`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` + `AWS_REGION`
`ollama`	None (local)
`gateway`	`AI_GATEWAY_API_KEY`

Default models per provider:

Provider	Default Model
`anthropic`	`claude-opus-4-6`
`openai`	`gpt-4o`
`bedrock`	`anthropic.claude-opus-4-6-v1:0`
`ollama`	`llama3.1`
`gateway`	`anthropic/claude-opus-4.6`

Database

Variable	Default	Description
`ATLAS_DATASOURCE_URL`	—	Analytics datasource connection string (PostgreSQL or MySQL). Optional when datasources are defined in `atlas.config.ts`
`DATABASE_URL`	—	Atlas internal Postgres (auth, audit, conversations). Optional — Atlas works without it
`ATLAS_DEMO_DATA`	—	Set `true` to use the internal DB as both analytics datasource and internal DB

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.

Query Safety

Variable	Default	Description
`ATLAS_ROW_LIMIT`	`1000`	Max rows returned per query
`ATLAS_QUERY_TIMEOUT`	`30000`	Query timeout in milliseconds
`ATLAS_TABLE_WHITELIST`	`true`	Only allow queries against tables defined in the semantic layer
`ATLAS_SCHEMA`	`public`	PostgreSQL schema name. Used by the CLI for profiling (`init`, `diff`) and by the API at runtime to set the connection `search_path`

See SQL Validation Pipeline for how these are enforced.

Authentication

Variable	Default	Description
`ATLAS_AUTH_MODE`	Auto-detected	Explicit auth mode: `none`, `api-key`, `managed`, `byot`

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

ATLAS_AUTH_JWKS_URL set → BYOT
BETTER_AUTH_SECRET set → Managed
ATLAS_API_KEY set → Simple Key
None of the above → No auth

See Authentication for full setup guides.

Simple Key

Variable	Default	Description
`ATLAS_API_KEY`	—	Shared secret. Clients send `Authorization: Bearer <key>` or `X-API-Key: <key>`
`ATLAS_API_KEY_ROLE`	`analyst`	Role for API key users: `viewer`, `analyst`, `admin`

Managed (Better Auth)

Variable	Default	Description
`BETTER_AUTH_SECRET`	—	Session signing secret. Min 32 chars, cryptographically random. Requires `DATABASE_URL`
`BETTER_AUTH_URL`	Auto-detected	Base URL for auth endpoints. Auto-detected on Vercel; set explicitly for Railway/Docker
`BETTER_AUTH_TRUSTED_ORIGINS`	—	Comma-separated CSRF-allowed origins
`ATLAS_ADMIN_EMAIL`	—	User matching this email gets `admin` role on signup. If unset, first signup gets admin

BYOT (Bring Your Own Token)

Variable	Default	Description
`ATLAS_AUTH_JWKS_URL`	—	JWKS endpoint URL for JWT signature verification
`ATLAS_AUTH_ISSUER`	—	Expected JWT `iss` claim (required)
`ATLAS_AUTH_AUDIENCE`	—	Expected JWT `aud` claim (optional)
`ATLAS_AUTH_ROLE_CLAIM`	`role` then `atlas_role`	Dot-delimited JWT claim path for role extraction (e.g. `app_metadata.role`). Default is a fallback chain: Atlas checks the `role` claim first, then falls back to `atlas_role` if `role` is not present

Rate Limiting

Variable	Default	Description
`ATLAS_RATE_LIMIT_RPM`	`0` (disabled)	Max requests per minute per user. 0 or unset = unlimited
`ATLAS_TRUST_PROXY`	`false`	Trust `X-Forwarded-For` / `X-Real-IP` headers. Set `true` behind a reverse proxy

Row-Level Security

Variable	Default	Description
`ATLAS_RLS_ENABLED`	—	Set `true` to enable RLS filtering on queries
`ATLAS_RLS_COLUMN`	—	Column name used for filtering (e.g. `tenant_id`)
`ATLAS_RLS_CLAIM`	—	JWT/session claim path for RLS value extraction (e.g. `org_id`)
`ATLAS_RLS_CLAIMS`	—	Static JSON claims for RLS with simple-key auth

ATLAS_RLS_CLAIMS is a JSON string that provides static claims for row-level security filtering. This variable is only used with simple-key (ATLAS_API_KEY) auth mode, where there is no JWT or session to extract claims from. For managed and BYOT auth, RLS claims are extracted from the user's JWT/session automatically.

ATLAS_RLS_CLAIMS='{"tenant_id": "acme-corp"}'

Networking & CORS

Variable	Default	Description
`ATLAS_PUBLIC_URL`	—	Public base URL for constructing action approval URLs. When not set, derived from request headers. Set explicitly in production for reliable approve/deny links in `/api/v1/query` responses
`ATLAS_CORS_ORIGIN`	`*`	CORS allowed origin. Must set explicitly for cross-origin + managed auth (cookie-based)
`NEXT_PUBLIC_ATLAS_API_URL`	—	Next.js frontend: cross-origin API URL. When unset, same-origin via Next.js rewrites
`ATLAS_API_URL`	`http://localhost:3001`	Rewrite target for same-origin mode (only used when `NEXT_PUBLIC_ATLAS_API_URL` is unset)

Sandbox & Isolation

Variable	Default	Description
`ATLAS_RUNTIME`	—	Runtime hint: `vercel` enables Vercel-specific sandbox and optimizations
`ATLAS_SANDBOX`	—	Set `nsjail` to enforce nsjail isolation (hard fail if unavailable)
`ATLAS_SANDBOX_URL`	—	Sidecar service URL for explore isolation (e.g. `http://sandbox-sidecar:8080`)
`SIDECAR_AUTH_TOKEN`	—	Shared secret for sidecar auth (set on both API and sidecar)
`ATLAS_NSJAIL_PATH`	Auto-detected	Explicit path to nsjail binary
`ATLAS_NSJAIL_TIME_LIMIT`	`10`	nsjail per-command time limit in seconds
`ATLAS_NSJAIL_MEMORY_LIMIT`	`256`	nsjail per-command memory limit in MB

See Sandbox Architecture for the full selection priority.

Actions

Variable	Default	Description
`ATLAS_ACTIONS_ENABLED`	—	Set `true` to enable the action framework (approval-gated write operations)
`ATLAS_ACTION_APPROVAL`	`manual`	Default approval mode for actions: `auto`, `manual`, or `admin-only`
`ATLAS_ACTION_TIMEOUT`	`30000`	Per-action execution timeout in milliseconds
`ATLAS_ACTION_MAX_PER_CONVERSATION`	`10`	Maximum number of actions allowed per conversation
`ATLAS_EMAIL_ALLOWED_DOMAINS`	—	Comma-separated list of allowed email recipient domains for the email action plugin. When unset, all domains are allowed

These env vars can also be set via atlas.config.ts under actions.defaults. See the declarative config guide for details.

Scheduler

Variable	Default	Description
`ATLAS_SCHEDULER_ENABLED`	—	Set `true` to enable scheduled task execution
`ATLAS_SCHEDULER_BACKEND`	`bun`	Execution backend: `bun`, `webhook`, or `vercel`
`ATLAS_SCHEDULER_SECRET`	—	Shared secret for the `/tick` endpoint (non-Vercel). On Vercel, use `CRON_SECRET` instead
`CRON_SECRET`	—	Vercel-native alternative to `ATLAS_SCHEDULER_SECRET`. When set, the `/tick` endpoint requires `Authorization: Bearer <secret>`. Takes precedence over `ATLAS_SCHEDULER_SECRET`
`ATLAS_SCHEDULER_MAX_CONCURRENT`	`5`	Max concurrent task executions per tick
`ATLAS_SCHEDULER_TIMEOUT`	`60000`	Per-task timeout in milliseconds
`ATLAS_SCHEDULER_TICK_INTERVAL`	`60`	Tick interval in seconds

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.

Email Delivery

Variable	Default	Description
`RESEND_API_KEY`	—	Resend API key for email delivery in scheduled tasks
`ATLAS_EMAIL_FROM`	`Atlas <noreply@useatlas.dev>`	From address for scheduled task emails

Slack Integration

Variable	Default	Description
`SLACK_SIGNING_SECRET`	—	Enables Slack integration. Used to verify request signatures
`SLACK_BOT_TOKEN`	—	Single-workspace mode (skip OAuth)
`SLACK_CLIENT_ID`	—	Multi-workspace OAuth app client ID
`SLACK_CLIENT_SECRET`	—	Multi-workspace OAuth app client secret

Python Tool

Variable	Default	Description
`ATLAS_PYTHON_ENABLED`	—	Set `true` to enable the `executePython` agent tool. Requires `ATLAS_SANDBOX_URL` to be set (Python runs in the sandbox sidecar for isolation)
`ATLAS_PYTHON_TIMEOUT`	`30000`	Python execution timeout in milliseconds

Runtime

Variable	Default	Description
`PORT`	`3001`	HTTP port for the standalone Hono API server. Most platforms (Railway, Render, Fly) set this automatically

Logging & Observability

Variable	Default	Description
`ATLAS_LOG_LEVEL`	`info`	Pino log level: `trace`, `debug`, `info`, `warn`, `error`, `fatal`
`OTEL_EXPORTER_OTLP_ENDPOINT`	—	OpenTelemetry collector endpoint. When set, Atlas emits trace spans for agent steps via `@opentelemetry/api`

Environment Variables

On this page