Overview

Self-hosting deploys the full Wraps control plane — API Lambda, dashboard, SQS workers, DynamoDB, and EventBridge Scheduler — into your AWS account using SST. You fork the Wraps repository, configure a handful of secrets, and run a single command. Everything runs in your account; no Wraps SaaS servers are in the critical path.

Prerequisites

1

Fork the Repository

The self-hosted deployment scripts live in the Wraps monorepo. Fork it so you can receive upstream updates on your own schedule.

1. Fork on GitHub — go to github.com/wraps-team/wraps and click Fork. Keep the default branch name main.
2. Clone your fork and install:
   Terminal

   git clone https://github.com/YOUR_ORG/wraps.gitcd wrapspnpm install

2

Deploy the Control Plane

Run the deploy script from the root of your fork. It provisions all AWS infrastructure via SST, runs database migrations, and writes an .env.selfhost file with the outputs.

# Pass all required values as flags (non-interactive):pnpm selfhost:deploy \  --database-url "postgres://user:pass@your-db.neon.tech/wraps" \  --license-key "wraps_lic_..." \  --yes# Or run without flags — the script will prompt you:pnpm selfhost:deploy

The script will:

1. Check your AWS credentials
2. Prompt for any missing values (database URL and license key) if not passed as flags
3. Write .env.selfhost with auto-generated secrets
4. Run sst install then deploy the Lambda, dashboard, and supporting AWS resources via SST
5. Append the Lambda URL, app URL, and any email variables to .env.selfhost

After the deploy completes, your .env.selfhost will look like this:

# Created automatically by pnpm selfhost:deployDATABASE_URL=postgres://user:pass@your-db.neon.tech/wrapsBETTER_AUTH_SECRET=<auto-generated>UNSUBSCRIBE_SECRET=<auto-generated>LICENSE_KEY=wraps_lic_...# Set when --web-domain flag is provided:SELFHOST_WEB_DOMAIN=dashboard.yourdomain.com# Populated after SST deploy completes:# Without --web-domain, NEXT_PUBLIC_APP_URL is a *.cloudfront.net URL:NEXT_PUBLIC_APP_URL=https://d1abc123xyz.cloudfront.netWRAPS_API_URL=https://abc123.lambda-url.us-east-1.on.awsBETTER_AUTH_URL=https://d1abc123xyz.cloudfront.net# Populated if email infrastructure was found:WRAPS_EMAIL_ROLE_ARN=arn:aws:iam::123456789012:role/wraps-email-roleAUTH_EMAIL_CONFIGURATION_SET=wraps-email-eventsAUTH_EMAIL_FROM=noreply@yourdomain.com

3

Deploy Email Infrastructure

Initialise email sending with AWS SES. This creates IAM roles, configures SES, and sets up event processing for open and click tracking.

wraps email init

If you only need SMS, skip this step and run wraps sms init instead.

4

Create Your Account and Connect

With the dashboard running, create your account, then authenticate the CLI against your instance and register the AWS connection.

1. Open your dashboard URL and sign up with email and password.
2. Create your organization — you will be prompted during onboarding. The CLI requires an organization to exist before it can connect.
3. Sign in the CLI — reads your deployment metadata to find the dashboard URL, then opens a browser for device authorization against your own instance:

wraps selfhost login

Once signed in, register this AWS account with your self-hosted control plane. This creates the wraps-console-access-role IAM role and enables event streaming from your email infrastructure to the dashboard:

wraps selfhost connect

Two additional commands are available once you are signed in:

• wraps selfhost env — prints the environment variables needed to deploy apps/web against your self-hosted control plane (useful for Vercel or any external hosting).
• wraps selfhost logout — removes the local session token for your self-hosted instance.

5

Verify Your Deployment

Check the health of your self-hosted control plane from the CLI:

wraps selfhost status

A healthy deployment reports the API URL, app URL, AWS region, deployment timestamp, and license key prefix. Open your dashboard URL and confirm your connected AWS account and any email or SMS infrastructure are visible.

Keeping Up to Date

New Wraps releases include Lambda updates, database migrations, and dashboard improvements. Choose the upgrade path that fits your workflow.

Manual upgrade

Pull upstream changes into your fork, then run the upgrade script. It re-deploys the SST stack and runs any pending database migrations automatically.

# Manual upgrade from your fork:pnpm selfhost:upgrade# Runs SST deploy + database migrations automatically

The upgrade script redeploys both the Lambda and the dashboard in a single run — no separate steps required.

Automated upgrades with GitHub Actions

Your fork includes two pre-built workflows that handle the full update loop hands-free:

Follow these steps to enable them in your fork.

{  "Version": "2012-10-17",  "Statement": [    {      "Effect": "Allow",      "Principal": {        "Federated": "arn:aws:iam::YOUR_ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"      },      "Action": "sts:AssumeRoleWithWebIdentity",      "Condition": {        "StringEquals": {          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"        },        "StringLike": {          "token.actions.githubusercontent.com:sub": "repo:YOUR_GITHUB_ORG/wraps:*"        }      }    }  ]}

.env.selfhost Reference

The deploy script creates and maintains .env.selfhost in your repo root. These values are read by SST at deploy time and injected as Lambda environment variables.

Next Steps