Overview

Self-hosting deploys the Wraps control plane API as an AWS Lambda function in your account, backed by your own Postgres database. Your team's dashboard runs on Vercel and connects to the Lambda directly — no Wraps SaaS in the loop.

Prerequisites

1

Deploy the Control Plane API

Run the deploy command. The CLI will walk you through selecting a region, connecting a database, and entering your license key. The control plane API is deployed as an AWS Lambda with a public function URL.

# Pass flags directly (non-interactive):wraps selfhost deploy --database-url "postgres://user:pass@your-db.example.com/wraps"wraps selfhost deploy --neon-api-key "your-key" --neon-org-id "org-..."# Or run without flags — the CLI will prompt you to choose:wraps selfhost deploy

The CLI will:

1. Prompt for AWS region if not specified via flag
2. Prompt for license key, app URL, and any missing database details
3. Run database migrations on your Postgres instance
4. Deploy the Lambda function, DynamoDB tables, SQS queues, and EventBridge scheduler via Pulumi
5. Print the API URL (e.g. https://abc123.lambda-url.us-east-1.on.aws)

2

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.

3

Get Your Environment Variables

Generate the .env block for your Vercel dashboard deployment. This reads your local Wraps metadata and prints all required variables in KEY=value format.

wraps selfhost env

The output looks like this — copy it and keep it ready for Step 4:

DATABASE_URL=postgres://user:pass@your-db.neon.tech/wrapsNEXT_PUBLIC_APP_URL=https://dashboard.yourdomain.comNEXT_PUBLIC_API_URL=https://abc123.lambda-url.us-east-1.on.awsCORS_ORIGIN=https://dashboard.yourdomain.comBETTER_AUTH_SECRET=<generated-secret>UNSUBSCRIBE_SECRET=<generated-secret>WRAPS_LICENSE_KEY=v1.scale.2027-01-01.<fingerprint>AWS_BACKEND_ACCOUNT_ID=123456789012

4

Deploy the Dashboard to Vercel

The Wraps dashboard lives in apps/web in the Wraps monorepo. Fork or clone the repo and deploy that directory to Vercel.

1. Fork the Wraps repo and connect it to a new Vercel project. Set the root directory to apps/web.
2. Add all environment variables from the wraps selfhost env output into Vercel → Project Settings → Environment Variables. Scope them to Production (and Preview if needed).
3. Trigger a deployment — Vercel will build and deploy the dashboard. The first deploy will succeed but the dashboard will not be able to call AWS until you complete Step 5.

5

Set Up Vercel OIDC Authentication

The dashboard reads AWS resources (SES stats, CloudWatch, DynamoDB) without any stored credentials. It uses Vercel OIDC federation to obtain short-lived AWS tokens automatically.

{  "Version": "2012-10-17",  "Statement": [    {      "Effect": "Allow",      "Principal": {        "Federated": "arn:aws:iam::YOUR_ACCOUNT_ID:oidc-provider/oidc.vercel.com/YOUR_TEAM_ID"      },      "Action": "sts:AssumeRoleWithWebIdentity",      "Condition": {        "StringEquals": {          "oidc.vercel.com/YOUR_TEAM_ID:aud": "sts.amazonaws.com"        }      }    }  ]}

{  "Version": "2012-10-17",  "Statement": [    {      "Effect": "Allow",      "Action": "sts:AssumeRole",      "Resource": "arn:aws:iam::YOUR_ACCOUNT_ID:role/wraps-console-access-role"    }  ]}

# Add after setting up Vercel OIDC (Step 5):AWS_ROLE_ARN=arn:aws:iam::123456789012:role/<your-vercel-backend-role>

6

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 in a browser and sign up with email and password.
2. Create your organization — you will be prompted to do this during onboarding. The CLI requires an organization to exist before it can connect.
3. Sign in the CLI — run the command below. It 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 (which your dashboard uses to read SES stats, CloudWatch metrics, and DynamoDB event history) and enables event streaming from your email infrastructure to the dashboard.

wraps selfhost connect

7

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, Lambda ARN, deployed version, and database connectivity. Then open your dashboard URL and confirm your connected AWS account, SES sending stats, and any email or SMS infrastructure you deployed in Steps 1–2 are visible.

Upgrading

When a new Wraps CLI version is released, upgrade the control plane Lambda in place. Migrations run automatically.

wraps selfhost upgrade

After upgrading the CLI, redeploy your Vercel dashboard project to pick up any frontend changes.

Next Steps