Overview

Self-hosting starts with the application stack. Billing, storage, email, and analytics are additional infrastructure decisions after that stack is healthy.

Minimum deployable stack

The repository does not currently provide a one-command production deployment. Before following the optional-service guides, plan and operate:

• PostgreSQL 17 with the pgvector extension, migrations, backups, and restore tests
• Redis for queues, caching, and realtime coordination
• the API service, web application, and background workers from the same release
• public web/API/WebSocket URLs, TLS, allowed origins, and Better Auth secrets/URLs
• QStash/Workflow-compatible job delivery and signing keys
• an OpenRouter key and model policy for AI/embedding features you enable
• secret storage/rotation, structured logs, health checks, alerts, and rollback

The local docker-compose.yml is a development baseline for Postgres, Redis, and GeoIP. It is not a production topology. Run migrations before serving a new release and keep the API, web, workers, schema, and published SDK expectations version-aligned.

Once that core is running, settle these four responsibilities:

Cossistant expects:

• a clear billing mode decision: keep Polar enabled, or disable billing and run with unlimited self-hosted entitlements
• object storage for uploads and public file reads
• transactional email infrastructure that can send mail, receive replies, and report lifecycle events
• analytics infrastructure for inbox metrics and live presence, or an explicit decision to disable those managed analytics features

We recommend an AWS-first path for the official self-host setup because the repo already ships Terraform modules for it, but the docs in this section are organized around roles rather than vendors:

• Billing covers the POLAR_ENABLED switch, why Polar stays enabled by default, and what changes when billing is disabled
• Storage covers uploads, public file reads, and the AWS S3 setup path
• Email Setup covers transactional email, inbound replies, and how to choose between Resend and SES
• Analytics covers Tinybird-backed analytics, the Tinybird/DataFast toggle env vars, and what happens when analytics are disabled

Billing responsibility

Cossistant has two valid billing modes for self-hosting:

• keep Polar enabled and preserve the hosted subscription and AI metering behavior
• disable Polar and run in a self-hosted mode where billing flows, credit metering, and plan limits are bypassed

Polar stays enabled by default so the repo behaves like the managed product unless you explicitly opt out.

Use the Billing guide to decide which mode you want and to configure POLAR_ENABLED.

Why the AWS-first path is recommended

The repo already ships Terraform modules for both services:

• infra/aws/s3-public-setup
• infra/aws/ses-email-setup

That matters because the self-host path is concrete instead of theoretical. You are not starting from scratch with generic storage or email plumbing. You are following infrastructure that already matches what the app expects at runtime.

Storage responsibility

Cossistant needs object storage where the API can generate presigned upload URLs and where uploaded files can be read back through stable public URLs.

In practice that means:

• the API signs uploads
• the browser uploads directly to object storage
• the app stores and renders the resulting public URLs
• uploaded files can be grouped by organization, website, and entity

Use the Storage guide to set that up.

Email responsibility

For email, Cossistant needs more than simple outbound delivery. The app also depends on reply routing and lifecycle events.

In practice that means:

• React Email renders the email content inside the app
• outbound sending is selected by EMAIL_TRANSPORT_PROVIDER
• reply-to addresses point to an inbound domain controlled by Cossistant
• inbound replies eventually come back into the API as normalized webhook payloads
• bounce, complaint, and failure events feed suppression state

The good news is that you can choose your transport:

• resend is supported and remains the default
• ses is supported and is the AWS-native path for self-hosting

Use the Email Setup guide to choose a provider and configure the full inbound and outbound path.

Analytics responsibility

Cossistant uses analytics infrastructure for two product areas:

• inbox analytics
• live visitor presence and "last seen in app" enrichment

For self-hosting, you have two valid paths:

• keep Tinybird enabled and point the app at your Tinybird setup
• disable Tinybird entirely and run without the Tinybird-backed analytics UI

The app also includes a separate DataFast script for our hosted web analytics. Self-hosters can disable that independently.

Use the Analytics guide to choose how you want to handle both Tinybird and DataFast in your deployment.

How the pieces fit together

At a high level, a self-hosted deployment looks like this:

1. A browser requests a presigned upload URL from the API.
2. The API signs a PUT to S3 and returns the upload URL plus the public URL.
3. The browser uploads the file directly to S3 instead of streaming it through the API.
4. Cossistant sends email using React Email templates and the provider selected by EMAIL_TRANSPORT_PROVIDER.
5. New reply-to addresses point to the inbound domain for the active email provider.
6. Resend or SES delivers inbound replies and lifecycle events back into the API using the provider-specific bridge path configured in the app.
7. The API turns those events into timeline messages, notification triggers, and bounce or complaint records.
8. Polar-backed billing stays enabled by default unless you explicitly disable it with POLAR_ENABLED=false.
9. Tinybird-backed inbox analytics and live presence are either enabled through your analytics setup or explicitly disabled through env flags.

Recommended setup order

For a clean first deployment:

1. Provision PostgreSQL/pgvector and Redis, configure secrets and public URLs, run migrations, and start the API, web app, and workers.
2. Verify authentication, API health, WebSocket connectivity, background jobs, and backup/restore before optional integrations.
3. Read Billing and decide whether Polar stays enabled.
4. Set up Storage and verify uploads.
5. Configure Email and test outbound plus inbound replies.
6. Configure the repository's Tinybird resources or explicitly disable Analytics and DataFast.
7. Exercise an upgrade and rollback in staging before production traffic.

If you are doing a greenfield self-host deployment and do not plan to use Resend at all, you can move directly to SES once DNS, identities, and webhooks are confirmed working in your environment.

Guides

• Storage
• Billing
• Email Setup
• Analytics