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) and passed to the web container by docker-compose.yml. 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: 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

Owlat supports four email providers: a custom MTA for direct SMTP delivery (default), AWS SES, Resend, and a generic SMTP relay. Set the EMAIL_PROVIDER variable in the Convex dashboard:

npx convex env set EMAIL_PROVIDER mta     # default
npx convex env set EMAIL_PROVIDER ses
npx convex env set EMAIL_PROVIDER resend
npx convex env set EMAIL_PROVIDER smtp

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_...
   

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.

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.