Self-Hosting

Owlat runs entirely on your own infrastructure via a single Docker Compose file. No cloud services are required — the stack includes its own database and real-time engine, and can run its own mail server (MTA) and antivirus scanner (ClamAV). The mail server and antivirus scanner are gated behind Docker Compose profiles (mta and clamav), so which of them run depends on your COMPOSE_PROFILES — see Stack Overview.

Why Self-Host

• Data sovereignty — your emails, contacts, and analytics never leave your servers
• Compliance — meet GDPR, HIPAA, or industry-specific data residency requirements
• Air-gapped environments — run without any external network dependencies
• Full control — customize, audit, and extend every component

Prerequisites

Supported platforms

Owlat runs on different operating systems depending on which part you mean — the desktop client, the self-hosted server, or a contributor checkout.

Desktop app

The desktop app ships for macOS (universal binary), Linux, and Windows. On Linux, end users need a few system runtime libraries installed for the WebKit-based shell to load:

• Debian / Ubuntu: libwebkit2gtk-4.1-0, librsvg2-2
• Fedora: webkit2gtk4.1, librsvg2

macOS and Windows bundle everything they need, so no extra packages are required there.

Self-hosted server

The self-hosted server is Linux only by design. It relies on systemd, Docker Engine, and binds the standard mail and web ports (25, 143, 443, 993). The blessed install path is a fresh Linux VPS.

macOS and Windows are not supported as a server host. For local evaluation on those machines, use Docker Desktop with the manual docker compose flow — that runs the same containers without needing a Linux host.

Contributor / dev checkout

Contributing works natively on macOS and Linux. On Windows, run the repo under WSL2 or Git Bash, because the lint and verification gates are bash scripts. See CONTRIBUTING for the full development setup.

Fastest path

On a fresh Linux VPS with Docker + Docker Compose v2 installed:

curl -fsSL https://get.owlat.app | bash

The one-liner clones the repo, runs preflight checks, installs the owlat CLI to /usr/local/bin, and hands off to the containerized owlat quickstart wizard. That single flow generates secrets, writes your .env, starts the Docker stack, mints the Convex admin key, deploys the functions, sets the Convex runtime environment variables, and bootstraps your admin account — no Bun or Node required on the host. Non-interactive usage:

# Skip prompts, accept all defaults
OWLAT_ASSUME_YES=1 curl -fsSL https://get.owlat.app | bash

# Read answers from a config file (for CI / Ansible)
OWLAT_CONFIG_FILE=/path/to/answers.env curl -fsSL https://get.owlat.app | bash

# Pin a specific release tag for a reproducible install
OWLAT_REF=v0.1.0 curl -fsSL https://get.owlat.app | bash

Quick Start

Option A: owlat quickstart (recommended)

The recommended first-run flow is the containerized quickstart wizard. It runs the setup CLI (built from apps/setup-cli/) inside the wolvesdotink/setup Docker image, so the only host requirements are Docker and Docker Compose v2. One command does the full deploy: config wizard → docker compose up -d → admin-key mint → function deploy → Convex env vars → admin bootstrap.

git clone https://github.com/wolvesdotink/owlat.git
cd owlat
scripts/owlat quickstart

If you ran the one-liner above, the owlat CLI is already on your PATH, so you can simply run owlat quickstart. The full flow takes about 10 minutes from an empty VPS to a working install and handles everything in Option B below automatically — including pushing the Convex runtime env vars (BETTER_AUTH_SECRET, SITE_URL, UNSUBSCRIBE_SECRET, EMAIL_PROVIDER, MTA_API_URL, and the sender identity) into the deployment, so auth invites and the first send work without any extra steps.

Option B: Manual Setup

1. Clone and configure

git clone https://github.com/wolvesdotink/owlat.git
cd owlat
cp .env.selfhost.example .env

2. Generate secrets

# Instance secret (hex)
openssl rand -hex 32

# MTA API key and webhook secret (base64)
openssl rand -base64 32
openssl rand -base64 32

Paste the generated values into .env for INSTANCE_SECRET, MTA_API_KEY, and MTA_WEBHOOK_SECRET.

3. Start the stack

docker compose up -d

4. Wait for Convex to be ready

# Watch logs until you see "ready" or "listening"
docker compose logs -f convex
# Press Ctrl+C once ready

5. Generate the admin key

docker compose exec convex ./generate_admin_key.sh

Copy the output key and add it to your .env:

# In .env, set:
CONVEX_ADMIN_KEY=<paste-key-here>

No restart is needed — the always-on services don't read CONVEX_ADMIN_KEY. Only the one-shot convex-deploy container (next step) and the optional sidecars consume it, and they re-read .env each time they run.

6. Deploy functions

# Deploy the main Convex functions
docker compose --profile deploy run --rm convex-deploy

7. Set Convex environment variables

These are application-level variables read by the serverless functions. Set them using the Convex CLI with your admin key:

export CONVEX_URL=http://localhost:3210
export CONVEX_ADMIN_KEY=<your-admin-key>

npx convex env set BETTER_AUTH_SECRET "$(openssl rand -base64 32)" --url $CONVEX_URL --admin-key $CONVEX_ADMIN_KEY
npx convex env set UNSUBSCRIBE_SECRET "$(openssl rand -base64 32)" --url $CONVEX_URL --admin-key $CONVEX_ADMIN_KEY
npx convex env set SITE_URL "http://localhost:3000" --url $CONVEX_URL --admin-key $CONVEX_ADMIN_KEY
# Do NOT set CONVEX_SITE_URL here — it is a Convex BUILT-IN and `convex env set`
# rejects it (EnvVarNameForbidden). The backend derives it from
# CONVEX_SITE_ORIGIN on the convex container, which docker-compose interpolates
# from NUXT_PUBLIC_CONVEX_SITE_URL in your .env.
npx convex env set EMAIL_PROVIDER "mta" --url $CONVEX_URL --admin-key $CONVEX_ADMIN_KEY
npx convex env set MTA_API_URL "http://mta:3100" --url $CONVEX_URL --admin-key $CONVEX_ADMIN_KEY
npx convex env set MTA_API_KEY "<your-mta-api-key>" --url $CONVEX_URL --admin-key $CONVEX_ADMIN_KEY
npx convex env set MTA_WEBHOOK_SECRET "<your-mta-webhook-secret>" --url $CONVEX_URL --admin-key $CONVEX_ADMIN_KEY
npx convex env set DEFAULT_FROM_EMAIL "noreply@example.com" --url $CONVEX_URL --admin-key $CONVEX_ADMIN_KEY
npx convex env set DEFAULT_FROM_NAME "Owlat" --url $CONVEX_URL --admin-key $CONVEX_ADMIN_KEY
npx convex env set DEFAULT_FROM_DOMAIN "example.com" --url $CONVEX_URL --admin-key $CONVEX_ADMIN_KEY

8. Open the dashboard

open http://localhost:3000

Stack Overview

A few more services run only on demand, not as part of the always-on stack:

• convex-deploy (--profile deploy) — one-shot container that pushes apps/api functions, schema, and HTTP routes to the backend, and sets Convex runtime env vars. Run it after first boot and after every image pull: docker compose --profile deploy run --rm convex-deploy.
• code-worker (--profile inbox-codetasks, also available via --profile dev) — the optional AI coding-agent sidecar; off by default.
• convex-dashboard (--profile dashboard) — admin UI for inspecting data and debugging functions. Start it with docker compose --profile dashboard up -d convex-dashboard. It binds to 127.0.0.1 only, so on a remote VPS open an SSH tunnel (ssh -L 6791:127.0.0.1:6791 host) before browsing to http://localhost:6791.

For a deeper dive into the architecture, see Self-Hosting Architecture.

What's Next

• Configuration Reference — all environment variables, service topology, and volumes
• DNS & Email Setup — SPF, DKIM, DMARC, and bounce handling for production email
• Production Deployment — reverse proxy, TLS, firewall, backups, and monitoring
• Maintenance & Updates — keeping your instance up to date and troubleshooting