Configuration
Every environment variable a self-hosted OpenDash reads, grouped by what it controls. Both images read the same settings.
OpenDash is configured entirely through environment variables. With Docker Compose they live in .env next to docker-compose.yml (start from infra/selfhost.env.example). Never commit that file.
Set them on both images
web and worker read the same settings. The worker calls the model providers and sends email; the web app needs the same keys to offer only the models that can run and to build links.
Required
| Variable | Description |
|---|---|
OPENDASH_KEK | Master key-encryption key for stored connection passwords and model keys. 32 bytes, base64 (openssl rand -base64 32). Back it up offline: without it, stored secrets can't be recovered. |
BETTER_AUTH_SECRET | Signs sessions, email links and dashboard frame links (openssl rand -base64 32). Changing it ends every directory sync token. |
BETTER_AUTH_URL | The HTTPS address people open OpenDash at. Also used for links in emails and for every identity provider's setup. |
BETTER_AUTH_TRUSTED_ORIGINS | Comma-separated exact HTTPS origins allowed to sign in. Usually the same as BETTER_AUTH_URL. |
EMAIL_FROM | Sender address, e.g. OpenDash <auth@example.com>, on a domain your provider lets you send from. |
RESEND_API_KEY or SMTP_URL | One email provider. Resend wins when both are set. See Email. |
OPENDASH_FRAMES_URL | The origin dashboards are served from: another domain pointed at this server, such as https://frames.example.com. Without it, dashboards don't open in production. See Dashboards. |
With Docker Compose you also set POSTGRES_PASSWORD and one password per database role (OPENDASH_DB_OWNER_PASSWORD, …_APP_…, …_SYSTEM_…, …_AUTH_…, …_QUEUE_…). Use URL-safe values such as openssl rand -hex 24: they go into connection URLs.
Access
| Variable | Default | Description |
|---|---|---|
OPENDASH_INVITE_ONLY | 1 | 1: only invited people (plus the bootstrap admin, once) can sign up. 0: anyone who can reach the address can sign up and create workspaces. |
OPENDASH_BOOTSTRAP_ADMIN_EMAIL | The first admin. Can sign up once while nobody has. A new invite-only instance refuses to start without it. | |
OPENDASH_TERMS_URL, OPENDASH_PRIVACY_URL, OPENDASH_SECURITY_URL | Optional links in the sign-in footer and sign-up terms line. Empty hides them. |
Keep sign-up closed on a public address
With OPENDASH_INVITE_ONLY=0, anyone who can reach the server can run the analyst on your model keys and connect sources that reach your network. Use it only on a private instance.
Sign-up, sign-in and password reset need email. In production the web app refuses to start without it.
| Variable | Description |
|---|---|
RESEND_API_KEY | A Resend API key, with the sender's domain verified in Resend. |
SMTP_URL | Any SMTP server: smtp://user:pass@host:587 (STARTTLS) or smtps://user:pass@host:465. TLS is required unless the URL ends in ?requireTLS=false, since sign-in links travel in these emails. |
SMTP has no idempotency key, so a retry after an unacknowledged send can deliver twice. The Message-ID is the same, so mail clients show one.
Models
| Variable | Description |
|---|---|
AI_GATEWAY_API_KEY | Vercel AI Gateway. When set, every allowed model runs through it. |
ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY | Without a gateway key, each maker's key runs its own models. |
These are the deployment's own provider. Workspaces can connect their own instead, under Settings → AI. OPENAI_API_KEY also turns on embeddings for search by meaning; see Models and providers.
Database
| Variable | Description |
|---|---|
DATABASE_URL | App queries. A transaction pooler is fine. |
DATABASE_DIRECT_URL | Direct or session-mode connection, for LISTEN. One connection per process. |
DATABASE_QUEUE_URL | Direct or session-mode connection as opendash_queue, for the job queue. |
DATABASE_AUTH_URL | As opendash_auth, for sign-in. |
DATABASE_SYSTEM_URL | As opendash_system, for the routine dispatcher and maintenance. |
OPENDASH_EXTRA_CA_CERTS | A certificate authority as PEM text, for a Postgres that signs with its own CA. Or mount a file and set NODE_EXTRA_CA_CERTS. |
The bundled compose file builds these URLs for you. The PostgreSQL page covers managed Postgres.
Dashboards
Dashboards need an origin of their own
A dashboard's code runs in a sandboxed frame served from a second domain pointed at the same server, so it never runs where an OpenDash session does. Set it in OPENDASH_FRAMES_URL, for example https://frames.opendash.example.com. It is written into the web image's security headers when the image is built, and read again when it runs, so it must be set at both times. The bundled docker-compose.yml, the Caddy profile and the published images don't pass it yet: until they do, dashboards don't open on a Docker Compose install. Everything else works.
In development you don't need it: the frames origin is the other loopback name of the same server (http://127.0.0.1:3000 when you open http://localhost:3000).
Connected services
| Variable | Default | Description |
|---|---|---|
OPENDASH_MCP | on | 0 turns off connected services (MCP servers) on this deployment: Settings hides them, the analyst isn't offered them, and nothing calls a server. |
Workers and scaling
| Variable | Default | Description |
|---|---|---|
WORKER_POOLS | all | Comma-separated pools this worker runs: query (connection checks, dashboard queries, metric checks, routine runs and sends), sync (learning sources, testing definitions), interactive (agent runs and what they send, dashboard summaries). Every install needs each pool running somewhere. |
OPENDASH_EDITION | community | cloud makes workers refuse private addresses, for hosting OpenDash for others. |
OPENDASH_EGRESS_IPS | The workers' fixed outbound IPs, shown on the connect form so people know what to allowlist. |
Networking
| Variable | Default | Description |
|---|---|---|
OPENDASH_BIND, OPENDASH_PORT | 127.0.0.1, 3000 | Where web listens on the host. |
OPENDASH_DOMAIN | With the Caddy profile: the domain to get a certificate for, or localhost. | |
OPENDASH_HTTP_PORT, OPENDASH_HTTPS_PORT | Caddy's ports, when not 80 and 443. | |
OPENDASH_TRUSTED_PROXIES | Your proxy's addresses or CIDR ranges, so per-IP rate limits count per client. | |
OPENDASH_CLIENT_IP_HEADERS | Other headers to read the client IP from, e.g. x-real-ip. |
Slack
| Variable | Description |
|---|---|
SLACK_CLIENT_ID, SLACK_CLIENT_SECRET, SLACK_SIGNING_SECRET | From the Slack app's Basic Information page. |
SLACK_APP_TOKEN | An app-level token (xapp-…) with connections:write, for Socket Mode. |
SLACK_PUBLIC_URL | Only when Slack must return to another HTTPS address than BETTER_AUTH_URL. |
See Slack and email for creating the app.
Enterprise
These settings apply to the source-available ee/ features. Enterprise
| Variable | Default | Description |
|---|---|---|
OPENDASH_LICENSE_KEY | Unlocks the ee/ features in production. Checked offline. | |
OPENDASH_AUDIT_RETENTION_DAYS | 90 | Audit log retention. Up to 2562 (seven years) with a license that covers the audit chain. |
OPENDASH_SSO_MAX_AUTH_AGE_HOURS | 12 | How often people at a domain that requires SSO sign in through their provider again. |
OPENDASH_SSO_TRUSTED_IDP_ORIGINS | Identity provider origins on your own network, comma-separated. |
Optional
| Variable | Description |
|---|---|
OPENDASH_SEED_DEMO, OPENDASH_DEMO_READER_PASSWORD | true seeds the sample company once, with a read-only user on this password. |
OTEL_EXPORTER_OTLP_ENDPOINT | Send OpenTelemetry traces to your collector over OTLP/HTTP. Spans carry ids, routes, timings and usage, never a question, its SQL or an answer. |
OTEL_SERVICE_NAME | The service name on those traces. |
OPENDASH_WEB_IMAGE, OPENDASH_WORKER_IMAGE | Published images to run instead of building from the clone. |
Docker Compose
Run the whole stack on one machine with the docker-compose.yml at the root of the repository, with optional automatic HTTPS through Caddy.
PostgreSQL
OpenDash keeps all of its state in one PostgreSQL. What version and extensions it needs, which connection goes where, and notes for Neon, Supabase, Amazon RDS and ClickHouse Managed Postgres.