Self-Hosting Architecture

Owlat is designed to run entirely on your own infrastructure. Every component is open-source, and the entire stack deploys via a single Docker Compose file.

The Stack

The self-hosted stack is defined in the repo's root docker-compose.yml:

A local LLM ships as an optional service. Bring up the bundled Ollama container with --profile ai (also enabled under --profile dev) and set LLM_PROVIDER=ollama (the backend resolves it at http://ollama:11434/v1), or point the same variable at an Ollama instance you supply — see LLM configuration below.

What Convex provides natively

The open-source Convex backend (ADR-006) bundles capabilities that would otherwise require separate services:

• Database — document-oriented with indexes, full-text search, and ACID transactions
• Vector search — native vector indexes available for embedding-based retrieval (the substrate the Knowledge Graph and semantic file search are built on as those features mature)
• File storage — binary file uploads and downloads via ctx.storage (media library, attachments, semantic files)
• Real-time subscriptions — reactive queries that push updates to the UI over WebSocket
• Scheduled functions — cron jobs and one-off scheduled tasks (campaign sending, analytics reporting, sending-reputation cleanup, knowledge decay)
• HTTP actions — webhook endpoints, API routes, tracking pixels

This means no PostgreSQL, no MinIO, no separate vector database. The Convex backend is the single stateful service.

Docker Compose

The canonical definition lives in the repo's root docker-compose.yml. The excerpt below shows the core service wiring — refer to the real file for the full set of build args, health checks, and version-pinning env vars.

services:
  # Database + serverless functions
  convex:
    image: ghcr.io/get-convex/convex-backend:${CONVEX_BACKEND_VERSION:-...}
    ports:
      - "${CONVEX_PORT:-3210}:3210"        # Backend API
      - "${CONVEX_SITE_PORT:-3211}:3211"   # HTTP actions / site proxy
    volumes:
      - convex-data:/convex/data
    environment:
      INSTANCE_SECRET: ${INSTANCE_SECRET}
      CONVEX_CLOUD_ORIGIN: ${NUXT_PUBLIC_CONVEX_URL:-http://localhost:3210}
      CONVEX_SITE_ORIGIN: ${NUXT_PUBLIC_CONVEX_SITE_URL:-http://localhost:3211}

  # Admin/debugging UI (separate service, port 6791)
  convex-dashboard:
    image: ghcr.io/get-convex/convex-dashboard:${CONVEX_DASHBOARD_VERSION:-...}
    ports:
      - "${DASHBOARD_PORT:-6791}:6791"
    environment:
      CONVEX_URL: http://convex:3210

  # Nuxt web app
  web:
    image: ghcr.io/wolvesdotink/web:${OWLAT_VERSION:-latest}
    ports:
      - "${WEB_PORT:-3000}:3000"
    environment:
      NUXT_PUBLIC_CONVEX_URL: ${NUXT_PUBLIC_CONVEX_URL:-http://localhost:3210}
      NUXT_PUBLIC_CONVEX_SITE_URL: ${NUXT_PUBLIC_CONVEX_SITE_URL:-http://localhost:3211}
      NUXT_PUBLIC_SITE_URL: ${NUXT_PUBLIC_SITE_URL:-http://localhost:3000}
      OWLAT_DEPLOYMENT_MODE: ${OWLAT_DEPLOYMENT_MODE:-selfhost}
      INSTANCE_SECRET: ${INSTANCE_SECRET}   # for calling the updater sidecar

  mta:
    image: ghcr.io/wolvesdotink/mta:${OWLAT_VERSION:-latest}
    ports:
      - "${MTA_SMTP_PORT:-25}:25"     # Inbound SMTP (bounce processing)
      - "${MTA_HTTP_PORT:-3100}:3100" # HTTP API
    environment:
      REDIS_URL: redis://redis:6379
      CONVEX_SITE_URL: http://convex:3211
      MTA_API_KEY: ${MTA_API_KEY}
      MTA_WEBHOOK_SECRET: ${MTA_WEBHOOK_SECRET}

  redis:
    image: redis:${REDIS_VERSION:-7.4-alpine}
    command: redis-server --appendonly yes
    volumes:
      - redis-data:/data

  clamav:
    image: clamav/clamav:${CLAMAV_VERSION:-stable}
    volumes:
      - clamav-data:/var/lib/clamav

  # In-app update sidecar (reached only via the internal network)
  updater:
    image: ghcr.io/wolvesdotink/updater:${OWLAT_VERSION:-latest}
    # mounts only the install dir; reaches Docker through the least-privilege docker-socket-proxy (DOCKER_HOST), not the raw socket

  # Reverse proxy with automatic HTTPS (production)
  caddy:
    image: caddy:${CADDY_VERSION:-2.8-alpine}
    ports: ["80:80", "443:443"]
    profiles: [tls]

  # One-shot: push tenant functions to the backend after first boot
  convex-deploy:
    image: ghcr.io/wolvesdotink/convex-deploy:${OWLAT_VERSION:-latest}
    environment:
      CONVEX_SELF_HOSTED_URL: http://convex:3210
      CONVEX_SELF_HOSTED_ADMIN_KEY: ${CONVEX_ADMIN_KEY}
    profiles: [deploy]

  # AI coding-agent sidecar (feature request → prototype)
  code-worker:
    build: { context: ., dockerfile: apps/code-worker/Dockerfile }
    profiles: [inbox-codetasks, dev]

volumes:
  convex-data:
  redis-data:
  clamav-data:
  code-workspace:
  caddy-data:
  caddy-config:

Environment Variables

Owlat splits its configuration between compose-level variables (in .env, copied from .env.selfhost.example) that wire the containers together, and Convex function variables set on the backend via convex env set (or applied for you by owlat quickstart). The tables below cover both — the Scope column tells you where each one lives.

Required

The .env.selfhost.example file in the repo root lists every compose-level variable. The Convex-function secrets are applied automatically by owlat quickstart, or set by hand with convex env set once the backend is up.

The hardened VPS template (infra/templates/.env.vps.template) additionally requires REDIS_PASSWORD.

LLM Configuration (for Agent Pipeline)

These are Convex function variables (set with convex env set). See ADR-007: Pluggable LLM Provider for details.

Optional

How the stack evolves

The Docker Compose file grows with each phase of the roadmap:

The architecture is designed so that adding AI capabilities does not add required infrastructure. The agent pipeline, knowledge graph, and semantic search all run as Convex functions. The LLM itself is a configuration choice, not a required service — use a hosted OpenAI/OpenRouter/Anthropic key, or run inference locally with the bundled Ollama container (--profile ai, also enabled under --profile dev).

Security & isolation

Self-hosting means running AI agents on your own infrastructure — which requires the same defense-in-depth approach applied to the email pipeline. The security model covers credential isolation, process sandboxing, and environment hygiene.

Credential isolation

Agent pipeline functions never see raw API keys or secrets directly. All sensitive configuration flows through the Convex backend's environment variable system:

• LLM credentials — the API key is read inside getLLMProvider() in apps/api/convex/lib/llmProvider.ts; the credential resolver resolveApiKey() there accepts LLM_API_KEY, OPENROUTER_API_KEY, or OPENAI_API_KEY (first one set wins). The key never appears in agent context, LLM prompts, or log output.
• Channel provider credentials — channel API keys (SMS/WhatsApp/generic) are encrypted at rest: updateChannelConfig schedules encryptAndPersistConfig (apps/api/convex/channels/outbound.ts), which wraps the config in an AES-256-GCM envelope via lib/credentialCrypto before it lands in the channelConfigs row. They are decrypted only when an outbound channel function needs them to make a provider call.
• Self-hosted Ollama — if you run a local Ollama container, keep it on the Docker internal network (ollama:11434) with no published host port. No API key is required for Ollama, and the backend resolves its base URL automatically when LLM_PROVIDER=ollama.

# If you supply an Ollama container, leave it unpublished —
# reachable only from other Docker services
ollama:
  image: ollama/ollama
  # No 'ports:' mapping — only accessible via the Docker network

Process sandboxing

Agent-generated content runs in isolated execution environments:

• Visualization agent output — rendered in <iframe sandbox="allow-scripts"> with no access to the parent DOM, Convex client, cookies, or navigation. See Visualization Agent.
• Coding agent sidecar — the code-worker container (run under --profile inbox-codetasks, also enabled by --profile dev) gets its own code-workspace volume, separate from the backend's convex-data volume, and runs with no-new-privileges. It talks to the backend only through the Convex API URL.

code-worker:
  build:
    context: .
    dockerfile: apps/code-worker/Dockerfile
  volumes:
    - code-workspace:/workspace   # Isolated workspace, not convex-data
  environment:
    CONVEX_URL: http://convex:3210
    CONVEX_ADMIN_KEY: ${CONVEX_ADMIN_KEY} # authenticates internal-function calls
  security_opt:
    - no-new-privileges:true
  profiles:
    - inbox-codetasks
    - dev

Environment variable hygiene

Sensitive variables follow strict scoping rules:

Convex environment variables are never passed to agent-generated code. The code-worker sidecar receives only the Convex client URL, the deployment admin key, and LLM configuration. It polls an internalQuery and drives internalMutations, which an anonymous client cannot reach, so — exactly like apps/imap and apps/mail-sync — it authenticates with the deployment admin key (CONVEX_ADMIN_KEY) via setAdminAuth on the ConvexHttpClient (apps/code-worker/src/convexClient.ts). Compose passes the key into the service (docker-compose.yml). Keep the worker on the internal Docker network and don't expose its endpoints.

Getting started

# 1. Clone the repository
git clone https://github.com/wolvesdotink/owlat.git
cd owlat

# 2. Configure secrets
cp .env.selfhost.example .env   # then fill in INSTANCE_SECRET, MTA_*, URLs, ...

# 3. Start the stack
docker compose up -d

# 4. Generate the admin key and put it in .env as CONVEX_ADMIN_KEY
docker compose exec convex ./generate_admin_key.sh

# 5. Deploy the tenant functions (one-shot job, reads CONVEX_ADMIN_KEY)
docker compose --profile deploy run --rm convex-deploy

# 6. Open the dashboard
open http://localhost:3000