Environment variables

Every environment variable a Metis Suite instance reads, grouped by topic, with defaults.

Each variable is one of two kinds:

Startup: read every time the app starts. Change it in .env and restart the app.
Starting value: read once, the first time preflight runs, to fill in a setting the owner then manages in the dashboard. After that, change it under Dashboard, System. See How configuration works.

Any variable can also come from the optional config file. A wrong value stops the app from starting, and the error names the variable.

Core

Variable	Kind	What it does	Default
`BETTER_AUTH_URL`	Startup	The address people use to reach the app. An `https://` address turns on secure cookies.	`http://localhost:3000`
`BETTER_AUTH_SECRET`	Startup	The app’s secret. At least 32 characters. Required.
`METIS_ENCRYPTION_KEY`	Startup	Protects stored passwords and tokens. 32 random bytes, base64 (`openssl rand -base64 32`). Required. Back it up.
`METIS_SETUP_CODE`	Startup	Opens `/setup` to create the first account. At least 8 characters.	Not set
`METIS_OWNER_EMAIL`	Startup	The owner’s email. Only this account sees the owner dashboard. When not set, nobody does.	Not set
`METIS_SOURCE_URL`	Startup	Where the Source code link on every page goes. See Source code link.	`https://github.com/trymetis/metis`

Database

Variable	Kind	What it does
`METIS_DB_DRIVER`	Startup	`sqld` (a libSQL server, as in the Compose stack), `turso`, or `local` (a file, for development only, never for a deployment).
`DATABASE_URL`	Startup	The app database: `http(s)://` or `ws(s)://` for sqld, `libsql://` for Turso, `file:` for local.
`DATABASE_AUTH_TOKEN`	Startup	Its token. Required for sqld and Turso.
`MASTRA_DATABASE_URL`	Startup	The AI memory database. A separate database on the same driver.
`MASTRA_DATABASE_AUTH_TOKEN`	Startup	Its token.
`SQLD_AUTH_JWT_KEY`	Startup	The bundled database server’s public key. The bootstrap script generates it.
`SQLD_ADMIN_KEY`	Startup	The key for the bundled database server’s admin access. The bootstrap script generates it.

For a stack you set up without the bootstrap script, bash bootstrap.sh sqld-auth prints a matching SQLD_AUTH_JWT_KEY and token pair.

Variable	Kind	What it does	Default
`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`	Starting value	Your Google OAuth client.	Not set
`MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET`	Starting value	Your Microsoft app registration.	Not set
`ZOHO_CLIENT_ID`, `ZOHO_CLIENT_SECRET`	Starting value	Your Zoho OAuth client.	Not set
`ZOHO_REGION`	Starting value	`com`, `in`, `eu`, `com.au` or `jp`.	`com`

Server lists

Each is a JSON array of server entries, used as a starting value. See Server lists.

Every entry has a name (1 to 64 characters, unique) and an optional id (letters, digits, - and _, unique). Hosts are hostnames, never URLs.

Variable	Keys, with defaults
`METIS_IMAP_SERVERS`	`imap.host`, `imap.port` (993), `imap.secure` (true), `smtp.host`, `smtp.port` (465), `smtp.secure` (true), `allowInsecureTls` (false)
`METIS_CALDAV_SERVERS`	`url` (the full URL, with `https://`), `allowInsecureTls` (false)
`METIS_CLOUDFLARE_SERVERS`	`domain` (a bare domain such as `example.com`), `endpoint` (an `https://` URL)
`METIS_RESEND_SERVERS`	`domain`, `endpoint` (an `https://` URL)
`METIS_S3_SERVERS`	`endpoint` (`http://` or `https://`), `region` (`us-east-1`), `accessKeyId`, `secretAccessKey`, `forcePathStyle` (true), `allowInsecureTls` (false), `transfer` (`direct` or `relay`, default `direct`), `checksums` (`required` or `supported`, default `required`)
`METIS_WEBDAV_SERVERS`	`url`, `allowInsecureTls` (false)
`METIS_FTP_SERVERS`	`host`, `port` (21), `secure` (`explicit`, `implicit` or `none`, default `explicit`), `allowInsecureTls` (false), `poolSize` (1 to 10, default 2)
`METIS_SFTP_SERVERS`	`host`, `port` (22), `hostKeySha256` (required, as `ssh-keygen -l` prints it), `poolSize` (1 to 10, default 3)

Drive transfers

Variable	Kind	What it does	Default
`METIS_DRIVE_RELAY_SECRET`	Startup	Needed for relayed drives (WebDAV, FTP, SFTP and relayed S3). At least 32 characters.	Not set
`METIS_DRIVE_RELAY_MAX_MB`	Starting value	The largest relayed file, in MB.	`256`
`METIS_DRIVE_RELAY_CONCURRENCY`	Starting value	Relayed transfers one person can run at a time.	`3`

Mail images

Variable	Kind	What it does	Default
`METIS_MAIL_IMAGE_PROXY`	Startup	When `true`, remote images in mail load through your instance instead of straight from the sender’s server.	`false`
`METIS_MAIL_IMAGE_PROXY_MAX_MB`	Startup	The largest image the proxy loads, in MB. At most 100.	`10`

AI model (LLM)

Variable	Kind	What it does	Default
`METIS_LLM_DRIVER`	Starting value	`openai`, `anthropic`, `openai-compatible` or `disabled`.	`disabled`
`OPENAI_API_KEY`	Starting value	The key for `openai`. Also used by the `openai` decision model.
`ANTHROPIC_API_KEY`	Starting value	The key for `anthropic`.
`METIS_LLM_API_KEY`	Starting value	The key for `openai-compatible`. Optional.
`METIS_LLM_BASE_URL`	Starting value	The API address, for `openai-compatible`.
`METIS_LLM_NAME`	Starting value	A name for the provider, for `openai-compatible`. Optional.
`METIS_LLM_STRUCTURED_OUTPUTS`	Starting value	Use structured outputs, for `openai-compatible`. When off, summaries need about an 8k-token context window.	`false`
`METIS_LLM_CHAT_MODEL`	Starting value	The model for the assistant and agents. Required when a driver is on.
`METIS_LLM_SMART_REPLY_MODEL`	Starting value	The model for suggested replies. Required when a driver is on.
`METIS_LLM_CLASSIFIER_MODEL`	Starting value	The model for labels. Required when a driver is on.
`METIS_LLM_SUMMARY_MODEL`	Starting value	The model for summaries. Required when a driver is on.
`METIS_LLM_SUMMARY_VISION`	Starting value	Send images to the summaries model.	`false`

Decision model

All of these are read at startup. See AI models.

Variable	What it does	Default
`METIS_DECISION_DRIVER`	`systemone`, `openai` or `disabled`.	`disabled`
`METIS_DECISION_MODEL`	The model. Required unless disabled.
`METIS_DECISION_BASE_URL`	The server address, for `systemone`.	`https://api.typesafe.ai/v1`
`METIS_DECISION_API_KEY`	The key, for `systemone`. Optional.
`METIS_DECISION_CLASSIFIER`	Use it for inbox labels.	`false`
`METIS_DECISION_SUMMARY_GATE`	Use it as the summary gate.	`false`
`METIS_DECISION_WORKFLOW_NODE`	Use it in workflow Ask and Branch steps.	`false`
`METIS_DECISION_CLASSIFIER_BATCH`	Inbox label calls at a time, 1 to 25.	`5`

A decision switch does nothing while METIS_LLM_DRIVER is disabled, because AI is off for the whole instance. The dashboard refuses to save an LLM change that leaves a switch on without an LLM, and the deploy checks show a warning.

Phishing detection

Variable	Kind	What it does	Default
`METIS_PHISHING_DETECTION_DRIVER`	Starting value	`metis` or `disabled`.	`disabled`
`BACKEND_URL`	Starting value	The phishing detection backend’s address. Required for `metis`.

Outgoing email

Variable	Kind	What it does	Default
`METIS_MAIL_DRIVER`	Starting value	`log` (write to the server log), `noop`, `resend` or `smtp`.	`log`
`MAIL_FROM`	Starting value	The sender. Required for `resend` and `smtp`.	`Metis Suite <noreply@localhost>`
`MAIL_FROM_AUTH`	Starting value	The sender for sign-in mail.	`MAIL_FROM`
`MAIL_FROM_INVITE`	Starting value	The sender for invitations.	`MAIL_FROM`
`RESEND_API_KEY`	Starting value	Your Resend API key, for `resend`.
`SMTP_URL`	Starting value	A full SMTP URL, for `smtp`. Set this or `SMTP_HOST`.
`SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`	Starting value	The SMTP server, in parts.
`SMTP_SECURE`	Starting value	Use TLS from the start of the connection.

Cache

Variable	Kind	What it does	Default
`METIS_CACHE_DRIVER`	Starting value	`memory`, `redis` or `upstash`. With `memory`, each process keeps its own sessions and rate-limit counters and loses them on restart. Use `redis` or `upstash` when you run more than one process.	`memory`
`METIS_CACHE_URL`	Starting value	The Redis or Upstash address.
`METIS_CACHE_TOKEN`	Starting value	The Upstash token.

Background work

See Background work.

Variable	Kind	What it does	Default
`METIS_WORKFLOW_RUNNER_DRIVER`	Starting value	`internal`, `cron` or `bullmq`.	`internal`
`METIS_WORKFLOW_CADENCE_SEC`	Starting value	Seconds between ticks, 1 to 86400.	`60`
`METIS_WORKFLOW_TICK_BUDGET_MS`	Starting value	How long one tick may run, 1000 to 600000 (at most 55000 under `cron`).	`45000`
`METIS_WORKFLOW_BATCH_SIZE`	Starting value	Work taken per round, 1 to 500.	`25`
`METIS_WORKFLOW_CONCURRENCY`	Starting value	Work run at the same time, 1 to 64.	`4`
`METIS_WORKFLOW_REDIS_URL`	Starting value	Your Redis, for `bullmq`.
`METIS_WORKFLOW_QUEUE_PREFIX`	Starting value	The queue name prefix, for `bullmq`.	`metis-workflows`
`CRON_SECRET`	Starting value	The secret your scheduler sends in `X-Metis-Secret`, for `cron`.

Variable	Kind	What it does	Default
`METIS_SIGNUP_DISABLED`	Starting value	`true` for invite only, `false` for open sign-up.	`true`
`METIS_TERMS_URL`	Starting value	Your terms of service.	Not set
`METIS_PRIVACY_URL`	Starting value	Your privacy policy.	Not set
`METIS_LEGAL_VERSION`	Starting value	The version of your terms that people agree to.	`1`

Other

Variable	Kind	What it does	Default
`METIS_CONFIG_PATH`	Startup	The path of the config file. If the file does not exist, the app does not start.	Not set
`METIS_UPDATER_SOCKET`	Startup	Connects the app to the updater. The Compose stack sets it for you. Without it, there is no Updates page.	Set by Compose

Bootstrap script

These are read by the bootstrap script only. See Install with the bootstrap script.

Variable	What it does	Default
`METIS_DOMAIN`	Your domain. When set, Caddy serves the app over HTTPS.	Not set
`METIS_VERSION`	The release to install, such as `1.2.3`.	The newest release
`INSTALL_DIR`	Where the stack is installed.	`/opt/metis-suite`
`APP_PORT`	The port the app listens on, on `127.0.0.1`.	`3000`
`COMPOSE_REF`	The branch or tag to download the Compose file from.	`main`
`COMPOSE_URL`	A full URL for the Compose file.
`APP_IMAGE`, `PREFLIGHT_IMAGE`, `WORKER_IMAGE`, `UPDATER_IMAGE`	Exact images to use instead of a release.
`SQLD_IMAGE`, `CADDY_IMAGE`	Other images for the database server and Caddy.