Environment Variables

Owlat uses environment variables to configure providers, security scanning, authentication, and feature-flag prerequisites. Convex backend variables (everything read through apps/api/convex/lib/env.ts) are set via the Convex dashboard; the web app, MTA, IMAP server, and mail-sync worker read their own process env (in self-host, all of it comes from a single .env file consumed by docker-compose.yml).

Self-hosted configuration

Self-hosters put everything in a single .env file at the repo root. Start from the template:

cp .env.selfhost.example .env

The template and docker-compose.yml reference these variables:

Required secrets

Public URLs

MTA (mail sending)

Deployment mode (web app & compose)

These are not Convex backend vars — they are not read through lib/env.ts. OWLAT_DEPLOYMENT_MODE is consumed by the web app (apps/web/nuxt.config.ts, exposed as runtimeConfig.public.deploymentMode). You still set OWLAT_DEPLOYMENT_MODE in .env; docker-compose.yml passes it to the web container as NUXT_PUBLIC_DEPLOYMENT_MODE, because Nitro overlays runtime config only from NUXT_PUBLIC_* names — a value passed under any other name is ignored and the app keeps whatever its image was built with. OWLAT_HOSTED_MODE is a .env flag written by the setup CLI based on the chosen deployment mode; it is inert in this OSS repo (no service reads it), so self-hosters leave it false.

Port overrides (optional)

All ports default to sensible values. Override only if the defaults conflict:

# CONVEX_PORT=3210
# CONVEX_SITE_PORT=3211
# DASHBOARD_PORT=6791
# WEB_PORT=3000
# MTA_HTTP_PORT=3100
# MTA_SMTP_PORT=25
# IMAP_PORT=993

Optional: PostHog analytics

# NUXT_PUBLIC_POSTHOG_API_KEY=
# NUXT_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com

Optional: LLM provider (ai flag)

Only needed if any AI flag is on. See Providers → LLM provider for full details.

# LLM_PROVIDER=openai          # openai | openrouter | ollama  (Claude works via openai + an OpenAI-compatible LLM_BASE_URL)
# LLM_API_KEY=sk-...
# LLM_MODEL_FAST=gpt-4o-mini   # used for classify/extract/guard/summarize
# LLM_MODEL_CAPABLE=gpt-4o     # used for draft tasks
# LLM_MODEL=                   # single-model fallback for both tiers when *_FAST/*_CAPABLE are unset
# LLM_EMBEDDING_MODEL=text-embedding-3-small
# LLM_BASE_URL=                # override for ollama / vLLM / LM Studio
# --- Local-by-default embedding plane (optional) ---
# LOCAL_EMBEDDING_BASE_URL=http://ollama:11434/v1   # an OpenAI-compatible /embeddings sidecar
# LOCAL_EMBEDDING_MODEL=nomic-embed-text            # NOTE: its width must match the vector index

AI spend budget (per-org dollar ceiling)

A pre-call gate (convex/analytics/spendBudget.ts) that caps LLM dollar spend per org, on top of the per-call-count rate limits. Spend is aggregated from analytics/llmUsage + lib/llm/pricing. When a ceiling is hit the gate fails closed: the autonomous agent degrades to draft-only (mail is never dropped — it routes to human review) and advisory, user-triggered AI is paused once remaining headroom drops within the reserve. All four are unset/0 by default, which makes the gate a no-op.

Optional: Personal mail / IMAP (postbox flag)

The IMAP server (apps/imap) reads these on startup. Only relevant when the postbox flag is on.

# IMAP_PORT=993
# IMAP_LISTEN=0.0.0.0
# IMAP_GREETING_HOST=mail.example.com
# IMAP_TLS_CERT_FILE=/opt/owlat/certs/default.crt
# IMAP_TLS_KEY_FILE=/opt/owlat/certs/default.key
# TLS_CERT_DIR=/opt/owlat/certs        # fallback if IMAP_TLS_* not set
# REDIS_URL=                           # see note below

The IMAP server authenticates to Convex with CONVEX_ADMIN_KEY (it sets admin auth on a ConvexHttpClient and calls the mail/appPasswords:verify function directly — apps/imap/src/convex.ts). It does not read MTA_WEBHOOK_SECRET. Its log level comes from LOG_LEVEL (the VPS compose maps IMAP_LOG_LEVEL onto it).

Optional: Mail sync — external mailboxes (mail.external flag)

When the mail.external flag is on, users can connect their own IMAP/SMTP accounts. Convex hands those off to a separate mail-sync worker (infra/templates/docker-compose.vps.yml, the external-mail compose profile). Convex reaches the worker the same way it reaches the MTA — via deployment env vars set in the Convex dashboard:

Optional: Code worker + least-privilege proxies (inbox.codeTasks flag)

When the inbox.codeTasks flag is on, a code-worker sidecar claims queued code tasks and opens pull requests. It runs UNTRUSTED, inbound-email-driven code, so the shipped Compose stacks put it behind two sidecars rather than handing it the deployment admin key:

• convex-fn-proxy holds the real CONVEX_ADMIN_KEY and forwards ONLY the thirteen Convex functions the worker legitimately calls (codeWorkTasks:* and plugins/workerTasks:*); any other function path is rejected 403. The worker authenticates to it with CODE_WORKER_PROXY_TOKEN, which the proxy constant-time-compares, strips, and replaces with the admin key.
• code-worker-egress (tinyproxy) is a forward-proxy the worker's HTTP_PROXY/HTTPS_PROXY point at; it permits only the Convex proxy, the git remote and the LLM endpoint and denies all other outbound (infra/code-worker/tinyproxy.conf + tinyproxy.filter).

These variables live in the Compose .env (they are read by the worker and the proxy containers — not by the Convex backend, so they are not in lib/env.ts):

Optional: Inbound channel webhooks (SMS / WhatsApp / generic)

These secrets authenticate inbound webhook callbacks from third-party channel providers. They are read by the webhook adapters in apps/api/convex/webhooks/adapters/. (Inbound only — outbound SMS/WhatsApp send is not wired end-to-end; see Communication Channels.)

Optional: Other Convex backend vars

A few more variables are read through lib/env.ts and set in the Convex dashboard. None are required for a basic self-host:

Where to Set Variables

Convex backend (all process.env references in apps/api/):

npx convex env set VAR_NAME value

Or set them in the Convex dashboard under your deployment's Settings > Environment Variables.

Nuxt frontend (apps/web/.env):

NUXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
NUXT_PUBLIC_CONVEX_SITE_URL=https://your-deployment.convex.site
NUXT_PUBLIC_SITE_URL=http://localhost:3000

Email Sending

Provider Selection

Which send transports exist, what each one needs and what it can do is declared once, in packages/shared/src/sendProviderCatalog.ts (ADR-0055). This section restates that declaration and nothing else: apps/docs/__tests__/pageInvariants.test.ts reads both and fails when this page documents a Convex variable the backend never reads, and apps/docs/__tests__/docsVocabulary.test.ts fails on a variable named here that nothing declares. Set EMAIL_PROVIDER to a value from the first column to route every send through that kind; a per-org provider route overrides it per message type. There is no implicit default: leaving the variable unset is not "use the MTA" — resolution is fail-closed, so an instance with no route config and no value here refuses its sends rather than dispatching to a phantom MTA.

npx convex env set EMAIL_PROVIDER mandrill   # or any other value from the table above

Required is the presence gate the rest of the system reads: until every variable in that cell is set, the kind is not configured — it cannot be routed to, and it is not eligible as the deliverability fallback relay. Optional variables refine a transport that already works (a feedback signing key, a TLS floor, a dedicated IP pool), so a Convex deployment that never sets one still dispatches.

Both columns describe the Convex side, which is the only side the catalog knows about. A service you run yourself can hold its own contract on top: MTA_WEBHOOK_SECRET is optional to the gate above and mandatory to apps/mta, whose loadConfig() refuses to boot without it — so on a self-hosted stack, set it wherever the MTA's own reference below says to.

The optional column may name more than the catalog does, never fewer, and SES is where the two cases sit side by side. SES_CONFIGURATION_SET is read by the transport, on every send: the adapter stamps it on the SendEmail/SendRawEmail command so SES event publishing can attribute the resulting feedback — which is why the catalog declares it optional (a send without it works; only the attribution is lost, and setting it later applies to later sends only, never retroactively). SES_SNS_TOPIC_ARN is read only by the feedback verifier (webhooks/adapters/ses.ts) — the send path never looks at it, and it is not a signing key either, since SNS signs with a certificate — so no catalog field describes it and this reference is the only place it is written down. Neither gates whether SES can send, which is why neither is in the presence gate. A bundled plugin transport declares its own variables in its contribution instead — they are PLUGIN_-prefixed and never reach lib/env.ts, so they are documented by the plugin's README rather than here.

AWS SES

Setup Steps

1. Create an IAM user in AWS with programmatic access and the AmazonSESFullAccess policy (or a scoped policy allowing ses:SendEmail and ses:SendRawEmail).
2. Verify your sending domain in the SES console. SES requires domain verification before you can send emails.
3. Request production access if your SES account is in sandbox mode. Sandbox mode limits sending to verified addresses only.
4. Set the environment variables:

   npx convex env set EMAIL_PROVIDER ses
   npx convex env set AWS_SES_REGION eu-west-1
   npx convex env set AWS_SES_ACCESS_KEY_ID AKIA...
   npx convex env set AWS_SES_SECRET_ACCESS_KEY ...
   

5. (Recommended) Enable the bounce & complaint feedback loop. Without it, SES accepts your mail but never tells Owlat when a message hard-bounces or is marked as spam, so those addresses are not suppressed and your sender reputation silently decays. Owlat receives SES feedback through an Amazon SNS topic:
   • Create an SNS topic (e.g. owlat-ses-feedback) and add an HTTPS subscription pointing at https://<your-convex-site-url>/webhooks/ses. Owlat confirms the subscription automatically (it verifies the SNS message signature and then calls the SubscribeURL).
   • Set SES_SNS_TOPIC_ARN to that topic's ARN so Owlat accepts feedback only from your topic (until it is set the endpoint stays closed):

     npx convex env set SES_SNS_TOPIC_ARN arn:aws:sns:eu-west-1:123456789012:owlat-ses-feedback
     

   • In the SES console, create a Configuration Set, add an event destination publishing Bounce, Complaint and Delivery events to that SNS topic, and set SES_CONFIGURATION_SET to its name so every send is attributed:

     npx convex env set SES_CONFIGURATION_SET owlat-ses
     

   • The Delivery page (Settings → Delivery) shows a live "last event received" line so you can confirm feedback is arriving.
   
   Every SNS request is signature-verified fail-closed: its SigningCertURL is pinned to an sns.*.amazonaws.com host, its Timestamp must be recent, and its TopicArn must match SES_SNS_TOPIC_ARN, so forged or replayed feedback is rejected.

Resend

Setup Steps

1. Create a Resend account at resend.com and add your sending domain.
2. Generate an API key from the Resend dashboard.
3. (Optional) Set up webhooks for delivery tracking:
   • In Resend, create a webhook pointing to your Convex site URL's webhook endpoint
   • Copy the webhook signing secret
4. Set the environment variables:

   npx convex env set EMAIL_PROVIDER resend
   npx convex env set RESEND_API_KEY re_...
   npx convex env set RESEND_WEBHOOK_SECRET whsec_...
   

Emailit

Set EMAIL_PROVIDER=emailit and EMAILIT_API_KEY, then create an Emailit webhook pointing at <CONVEX_SITE_URL>/webhooks/emailit. Enable accepted, attempted, delivered, bounced, complained, failed, rejected, and suppressed email events. Owlat verifies X-Emailit-Signature as HMAC-SHA256 over <X-Emailit-Timestamp>.<raw body> with a five-minute freshness bound. Provider open/click tracking stays disabled on sends because Owlat's first-party tracking remains authoritative.

npx convex env set EMAIL_PROVIDER emailit
npx convex env set EMAILIT_API_KEY em_...
npx convex env set EMAILIT_WEBHOOK_SECRET whsec_...

Generic SMTP relay

When you already have an SMTP submission host — Mailgun, Postmark, SendGrid, Brevo, or a self-run relay — set EMAIL_PROVIDER=smtp and point Owlat at it. There is no per-provider API adapter: any relay that speaks SMTP works.

With a relay, the sending IPs and DKIM signing belong to the relay provider — configure SPF and DKIM for your From-domain in the relay's dashboard, not through the built-in MTA DNS bundle.

Mailchimp Transactional (Mandrill)

Set EMAIL_PROVIDER=mandrill to send through an existing Mailchimp Transactional account. This is the migration arm: a team arriving from Mailchimp keeps their current deliverability on day one, and Owlat's ramp controller then moves traffic onto the built-in MTA cell by cell as the measurements allow.

Owlat composes the whole MIME message itself and posts it to Mandrill's messages/send-raw, with Mandrill's open/click tracking, link rewriting and auto-text generation explicitly off. Tracking stays first-party, so both sending arms are measured on identical instrumentation — enable send, deferral, hard_bounce, soft_bounce, spam, unsub and reject on the webhook, but not open/click.

Create the webhook at Mailchimp Transactional → Settings → Webhooks, pointing at <CONVEX_SITE_URL>/webhooks/mandrill. Mandrill shows the signing key once, immediately after saving — that value is MANDRILL_WEBHOOK_KEY. Until it is set, Owlat rejects every posted batch rather than trusting an unsigned one, so sending looks healthy while bounces, complaints and reject-list hits silently never arrive. Delivery → Provider shows the exact URL, the event list, and whether the key is present. Only MANDRILL_API_KEY is written by the in-app transport editor; the other three are .env-only, so rotating the sending key can never unset a working feedback loop.

Two transports of the same kind

Every transport kind above gets one default instance for free, whose id is the kind itself (mta, ses, resend, smtp, mandrill, emailit) and which reads the unsuffixed variables. Declare named instances when you want two configurations of the same kind side by side — keeping a warm fallback relay while trialling a second one, for example.

A named instance reads its kind's variables suffixed with __<INSTANCEKEY>, so smtp#backup reads SMTP_RELAY_HOST__BACKUP, SMTP_RELAY_USERNAME__BACKUP and SMTP_RELAY_PASSWORD__BACKUP:

npx convex env set SEND_TRANSPORT_INSTANCES smtp#backup
npx convex env set SMTP_RELAY_HOST__BACKUP smtp.postmarkapp.com
npx convex env set SMTP_RELAY_USERNAME__BACKUP ...
npx convex env set SMTP_RELAY_PASSWORD__BACKUP ...

Removing an instance from the list, or removing its variables, makes sends addressed to that transport id fail closed — they never silently fall back to another transport's credentials. Malformed entries are ignored rather than crashing dispatch, as is a second entry whose key derives the same variable suffix as an earlier one (a-b and a_b both give __A_B). A plugin-contributed transport can have named instances too, on the same terms, when its contribution declares configuration variables of its own — those are PLUGIN_-prefixed and read the same __<INSTANCEKEY> suffix. One that declares none reads the plugin's own deployment-wide variables, which no suffix reaches, so declaring an instance of it is rejected rather than silently sending with the default instance's credentials.

Setup Steps

1. Create an SMTP credential in your relay provider's dashboard (a domain- or account-scoped SMTP username and password).
2. Verify your sending domain with the relay (publish its SPF/DKIM records) so your mail authenticates.
3. Set the environment variables:

   npx convex env set EMAIL_PROVIDER smtp
   npx convex env set SMTP_RELAY_HOST smtp.mailgun.org
   npx convex env set SMTP_RELAY_PORT 587
   npx convex env set SMTP_RELAY_USERNAME postmaster@mg.example.com
   npx convex env set SMTP_RELAY_PASSWORD ...
   

Custom MTA

When using the custom MTA (EMAIL_PROVIDER=mta), the Convex backend connects to the MTA service over HTTP. See the MTA System docs for full architecture details.

Setup Steps

1. Deploy the MTA service from apps/mta/ (see the MTA System docs for configuration).
2. Set the environment variables in the Convex dashboard:

   npx convex env set EMAIL_PROVIDER mta
   npx convex env set MTA_API_URL http://mta.internal:3100
   npx convex env set MTA_API_KEY your-shared-api-key
   npx convex env set MTA_WEBHOOK_SECRET your-webhook-secret
   

Common Email Configuration

These variables apply regardless of which provider you use:

Email Security

Optional environment variables for email content and attachment scanning. See the Email Security docs for details on the scanning pipeline.

Variables

Set in the Convex dashboard:

Set in the MTA environment:

Setup Steps

1. (Optional) Enable URL reputation checking — get a Google Safe Browsing API key from the Google Cloud Console:

   npx convex env set GOOGLE_SAFE_BROWSING_API_KEY AIza...
   

2. (Optional) Enable ClamAV malware scanning — deploy ClamAV alongside the MTA (see MTA System > ClamAV Sidecar) and set the internal URL:

   npx convex env set MTA_INTERNAL_URL http://mta.internal:3100
   

Analytics (PostHog)

Owlat integrates with PostHog for product analytics and error tracking. The integration is optional — everything works without it.

Variables

Convex dashboard:

Nuxt frontend (apps/web/.env):

Setup Steps

1. Create a PostHog project at posthog.com and copy the project API key.
2. Add the organization group type in PostHog: go to Settings → Groups → add a group type called organization. This enables organization-level analytics.
3. Set the environment variables:

   # Convex (server-side events)
   npx convex env set POSTHOG_API_KEY phc_...
   npx convex env set POSTHOG_HOST https://eu.i.posthog.com
   
   # apps/web/.env (client-side events)
   NUXT_PUBLIC_POSTHOG_API_KEY=phc_...
   NUXT_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com
   

Tracked Events

Client-side (automatic):

• $pageview — SPA page navigations
• $pageleave — page leave events
• $exception — Vue errors and unhandled promise rejections
• User identification and organization group association

Server-side (fire-and-forget from mutations):

• campaign_created, campaign_sent
• contact_created
• automation_created, automation_activated, automation_paused
• topic_created

All server events include organizationId as a property and PostHog group.

LLM provider (AI features)

The ai flag and every flag that depends on it require an LLM provider. The same provider powers email template translations, the AI agent, knowledge graph embeddings, and dashboard generation. See Providers → LLM provider for the interface contract and how to add a new provider.

Variables

Setup

npx convex env set LLM_PROVIDER openai
npx convex env set LLM_API_KEY sk-...
# Override defaults if you want a specific model:
npx convex env set LLM_MODEL_FAST gpt-4o-mini
npx convex env set LLM_MODEL_CAPABLE gpt-4o

For a local Ollama:

npx convex env set LLM_PROVIDER ollama
npx convex env set LLM_BASE_URL http://host.docker.internal:11434/v1
npx convex env set LLM_MODEL_FAST llama3.1:8b
npx convex env set LLM_MODEL_CAPABLE llama3.1:70b

Notifications

Notifications are handled client-side by the desktop app; there is no server-side notification-provider env var. All knowledge retrieval uses Convex's built-in vector index (ctx.vectorSearch), so there is no vector-store env var either.

Personal mail / IMAP (apps/imap)

These are read by the IMAP server, not the Convex backend. Only relevant when the postbox flag is on.

The IMAP server authenticates to Convex with CONVEX_ADMIN_KEY (it sets admin auth on a ConvexHttpClient and calls mail/appPasswords:verify directly — apps/imap/src/convex.ts). It does not read MTA_WEBHOOK_SECRET. The HMAC /webhooks/mta-verify-credential endpoint, by contrast, is the MTA's SMTP-submission credential check (see the Custom MTA section above and Postbox Architecture).

Authentication

Set BETTER_AUTH_SECRET in the Convex dashboard. Use a long, random string:

npx convex env set BETTER_AUTH_SECRET $(openssl rand -base64 32)

Nuxt Frontend

These go in apps/web/.env:

Complete Reference

Tenant App (apps/api)

Frontend (apps/web)

MTA (apps/mta)

IMAP server (apps/imap)

Started only when the postbox flag is on (via the personal-mail Docker Compose profile).

The IMAP server does not read MTA_WEBHOOK_SECRET. Its only required Convex credential is CONVEX_ADMIN_KEY.