# Deploy on AWS

> Deploy the Sypnia engine on your own AWS account with one CloudFormation template, check it, create the first project, point a domain at it, update it, and remove it.

Applies to: the Sypnia engine (open source, self-hosted). Status: at launch.  
Source: https://docs.sypnia.com/self-hosting/deploy-aws/

For agents: How to deploy the self-hosted Sypnia engine on AWS with the one CloudFormation template sypnia-aws.yaml: what it creates (three Lambda functions, a queue, a schedule, an S3 bucket, a CloudFront address, optional RDS Postgres), its parameters, step-by-step commands with expected results, custom domain, updates, changing settings, and removal.

**\[Engine]** This page is for whoever deploys the open-source engine on their own AWS account. It does not apply to Sypnia Cloud, which is this same shape run by us. If you do not use AWS, follow [Deploy with Docker](https://docs.sypnia.com/self-hosting/deploy-docker).

**At the end you will have:** the engine answering at an HTTPS address of your AWS account, its bucket and its database, a first project with an ingest key and an API token, and `sypnia doctor` passing.

**You need:** an AWS account and the [AWS CLI](https://docs.aws.amazon.com/cli/) version 2, signed in as someone who can create functions, roles, a bucket, a queue and a CloudFront distribution; `jq` and `openssl`; about 30 minutes, half of it waiting.

> **Note: Planned names**
>
> The engine is not released yet. The template's file name, its address and its parameters are the planned ones, and may change before launch. Times are estimates.

## What the template creates

One CloudFormation template, `sypnia-aws.yaml`, creates everything in one stack. The same `sypnia` binary runs as three functions; each one is the engine with one role.

**Figure (diagram not drawn yet)**: The stack the template creates. Three functions are the same binary with three roles.

It will show: ARCHITECTURE DIAGRAM of the AWS stack, left to right, inside one frame labelled «Your AWS account · stack: sypnia». Far left, outside the frame: «Your app (SDK)» and, below it, «You · your coding agent · your CI». Node 1: «Address · CloudFront · https\://sypnia.example.com» receiving both. From it two arrows: upper arrow labelled «/v1/ingest/\* · /v1/otlp/\* · /v1/sdk.js» to node 2 «Function: ingest»; lower arrow labelled «everything else: /v1/\*, /mcp, /console» to node 3 «Function: api». From «Function: ingest» an arrow to node 4 «Queue (intake)» labelled «event batches», and a second thin arrow straight to node 6 «Bucket» labelled «replay chunks, page snapshots». From the Queue an arrow to node 5 «Function: worker» labelled «wakes it, up to 10 s of batches». Above the worker a small clock node «Schedule · every minute» with an arrow into the worker. From the worker: an arrow to node 6 «Bucket (S3)» labelled «segments, per-session files, Parquet» and an arrow to node 7 «Postgres (RDS, or yours)» labelled «problems, numbers, sessions». From «Function: api» thin read arrows to Bucket and Postgres. From the worker two dashed arrows leaving the frame to the right: «your webhook» and «your AI provider (off until you set a key)». The lit element is the path Address → ingest → Queue → worker. Numbered callouts 1 to 7 on the nodes in the order given. A small tag on the Postgres node: «optional: created by the template or brought by you».

| # | Resource                                                            | What it does                                                                                                                                                                                                            | Template default                                                    |
| - | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| 1 | A CloudFront distribution                                           | The engine's one HTTPS address. Sends `/v1/ingest/*`, `/v1/otlp/*` and `/v1/sdk.js` to the ingest function and everything else to the API function. Takes your own domain if you give one.                              | No caching, except `/v1/sdk.js`                                     |
| 2 | Function `sypnia-ingest`                                            | `SYPNIA_ROLE=ingest`. Checks each batch and puts it in the queue; writes replay chunks and page snapshots to the bucket.                                                                                                | 256 MB, 10 s, at most 40 copies at once                             |
| 3 | Function `sypnia-api`                                               | `SYPNIA_ROLE=api`. The API, the MCP server and the Console.                                                                                                                                                             | 512 MB, 30 s, at most 20 copies                                     |
| 4 | A queue, and a second one for messages that failed five times       | Holds batches for up to 4 days until the worker writes them. It is the buffer a function cannot keep in memory.                                                                                                         | Standard queue                                                      |
| 5 | Function `sypnia-worker`, and a schedule that wakes it every minute | `SYPNIA_ROLE=worker`. Writes segments, finds problems, counts, runs uptime checks, the agent, alerts, webhooks and retention. Woken by the queue, and by the schedule when there is no traffic.                         | 1,024 MB, 15 min, at most 2 copies                                  |
| 6 | An S3 bucket                                                        | Raw events, replays, snapshots, source maps. Private, encrypted, public access blocked, a rule that lets your address read replays from a browser, and one lifecycle rule that removes unfinished uploads after 7 days. | Kept when the stack is deleted                                      |
| 7 | An RDS Postgres, **only if you ask for it**                         | The database. Postgres 16, 20 GB, encrypted, daily backups kept 7 days, its password generated and stored in Secrets Manager.                                                                                           | `db.t4g.micro`; a final snapshot is taken when the stack is deleted |
|   | Roles, and a log group per function                                 | Each function may touch only this stack's bucket and queue: `ingest` may send to the queue and put objects, `api` may read objects and sign links, `worker` may read and write the bucket. Logs are kept 30 days.       |                                                                     |
|   | Two alarms                                                          | One when a message lands in the second queue, one when the worker keeps failing. They show in CloudWatch; point them at a notification of yours if you want to be told.                                                 |                                                                     |

You do not operate the queue or the schedule: the template creates them and AWS runs them. Why functions need a queue, what each function is woken by, and what it changes in the timing, is in [Deployment shapes](https://docs.sypnia.com/architecture/deployment-shapes) and [Data flow](https://docs.sypnia.com/architecture/data-flow).

> **Warning: The database the template creates is reachable from the internet**
>
> The functions run outside a private network, so that they can reach your webhook, your AI provider and the addresses of your uptime checks without a NAT gateway, which alone costs about USD 33 a month. A database they can reach is therefore reachable from the internet too. The template protects it with a generated 32-character password and refuses connections without TLS. If that is not acceptable to you, bring a Postgres with the network rules you want (`DatabaseUrl`), or use the [Docker shape](https://docs.sypnia.com/self-hosting/deploy-docker) inside your own network.

## Parameters

| Parameter                               | Default                    | What it sets                                                                                                                    |
| --------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `RootToken`                             | Required                   | The [root token](https://docs.sypnia.com/concepts/projects-keys-and-tokens), `SYPNIA_ROOT_TOKEN`. At least 32 characters.       |
| `CreateDatabase`                        | `true`                     | `true` creates the RDS Postgres. `false` uses `DatabaseUrl`.                                                                    |
| `DatabaseUrl`                           | Empty                      | Your own Postgres, as `SYPNIA_DATABASE_URL`. Required when `CreateDatabase` is `false`. End it with `?sslmode=require`.         |
| `DatabaseInstanceClass`                 | `db.t4g.micro`             | The size of the database the template creates.                                                                                  |
| `DomainName`                            | Empty                      | Your own domain for the engine, such as `sypnia.example.com`. Empty uses the address CloudFront gives the stack.                |
| `CertificateArn`                        | Empty                      | The certificate for `DomainName`, from AWS Certificate Manager in `us-east-1`. Required with `DomainName`.                      |
| `AiProvider`, `AiApiKey`, `AiModel`     | `none`, empty, empty       | `SYPNIA_AI_PROVIDER`, `SYPNIA_AI_API_KEY`, `SYPNIA_AI_MODEL`. The agent is off while the provider is `none`.                    |
| `AlertWebhookUrl`, `AlertWebhookSecret` | Empty                      | `SYPNIA_ALERT_WEBHOOK_URL`, `SYPNIA_ALERT_WEBHOOK_SECRET`. Empty sends nothing; alerts are still recorded.                      |
| `Version`                               | The template's own version | Which release of the engine the functions run.                                                                                  |
| `CodeBucket`                            | `sypnia-releases-<region>` | The bucket the function package is read from. Change it only if your region has none (see [Troubleshooting](#troubleshooting)). |

The template sets these settings itself, and you should not change them: `SYPNIA_BASE_URL`, `SYPNIA_ROLE`, `SYPNIA_STORAGE_BUCKET`, `SYPNIA_STORAGE_REGION`, `SYPNIA_TRUSTED_PROXY_HOPS` and `SYPNIA_DATABASE_MAX_CONNECTIONS`. Every other setting of the [configuration reference](https://docs.sypnia.com/self-hosting/configuration) has its default until you [change it](#change-a-setting).

## Deploy

### 1. Install the sypnia command on your machine

You will use it to create the tables, check the deployment and create the first project.

```bash
curl -fsSL https://sypnia.com/install.sh | sh
sypnia version
```

**You should see:**

```text
sypnia 1.0.0 (a1c9e3f, 2026-03-01) schema 12
```

### 2. Choose the region and make the root token

```bash
export AWS_REGION=us-east-1
openssl rand -hex 32 > sypnia-root-token.txt
chmod 600 sypnia-root-token.txt
```

**You should see:**A file with 64 characters. Keep it somewhere safe, such as your password manager: it can do everything on every project.

### 3. Download the template

```bash
curl -fsSLO https://github.com/sypnia/sypnia/releases/latest/download/sypnia-aws.yaml
```

**You should see:**A file named `sypnia-aws.yaml` in the current folder. Read it if you want to know exactly what will be created: it is the whole deployment.

### 4. Deploy the stack

With a database created by the template:

```bash
aws cloudformation deploy \
  --template-file sypnia-aws.yaml \
  --stack-name sypnia \
  --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND \
  --parameter-overrides \
    RootToken="$(cat sypnia-root-token.txt)" \
    CreateDatabase=true
```

With your own Postgres, replace the last line with these two:

```bash
    CreateDatabase=false \
    DatabaseUrl='postgres://sypnia:<password>@<host>:5432/sypnia?sslmode=require'
```

**You should see:**

```text
Waiting for changeset to be created..
Waiting for stack create/update to complete
Successfully created/updated stack - sypnia
```

About 15 minutes when the template creates the database, about 5 when you bring yours. The database and the CloudFront address take the longest.

### 5. Load the engine's settings into your shell

The functions hold the engine's settings as environment variables. Read them from the worker, so the commands you run next use exactly the same database and bucket.

```bash
eval "$(aws lambda get-function-configuration --function-name sypnia-worker \
  --query 'Environment.Variables' --output json \
  | jq -r 'to_entries[] | select(.key | startswith("SYPNIA_")) | "export \(.key)=\(.value | @sh)"')"
echo "$SYPNIA_BASE_URL"
```

**You should see:**The address of your engine, such as `https://d2k4x7example.cloudfront.net`. Your shell now holds secrets, the root token among them: close it when you finish.

### 6. Create the tables

```bash
sypnia migrate
```

**You should see:**A list of applied migrations that ends with `database is up to date`. Until you run this, the functions refuse to start and the address answers with an error.

### 7. Check the deployment

```bash
curl -i "$SYPNIA_BASE_URL/healthz"
sypnia doctor --skip ai
```

**You should see:**

`HTTP/2 200` from the first command. From the second:

```text
config    ok    12 settings read, 0 unknown
database  ok    postgres 16.4, schema 12 (up to date), 41 ms
storage   ok    s3://sypnia-bucket-1a2b3c4d5e6f: put, get, delete, presign
address   ok    https://d2k4x7example.cloudfront.net/healthz answered 200
webhook   skip  SYPNIA_ALERT_WEBHOOK_URL is not set (alerts are recorded only)
clock     ok    0.3 s from the database's clock
all checks passed
```

`sypnia doctor` runs on your machine with your own AWS sign-in. It proves the settings, the database and the bucket. That the functions themselves can reach them is proved by `healthz` and by the next two steps.

### 8. Create the first project and a token

```bash
sypnia project create --name Shop
```

**You should see:**

```text
project     shop (prj_5k2m9x4q7w1z)
ingest key  spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e

Put the ingest key in your app. It is public: it can only send.
Next: sypnia token create --project shop --name "My laptop" --scopes read,replay
```

```bash
sypnia token create --project shop --name "My laptop" --scopes read,replay
```

**You should see:**A line that starts with `sps_`. It is shown once: copy it now.

### 9. Send from your app and see it arrive

Point the SDK at your engine with `endpoint`, as in the [quickstart](https://docs.sypnia.com/start/quickstart-self-host): `init({ project: 'spk_…', endpoint: '<your base URL>' })`. Open your app, click around, then:

```bash
SYPNIA_API_TOKEN=<your sps_ token> sypnia problems --environment development
```

**You should see:**Within 2 minutes of a first error, one problem. Sessions and numbers follow within 10 minutes. The Console is at `<your base URL>/console`.

Before real traffic, [point your domain](#point-a-domain-at-it) at the engine, so the address in your app is the final one, and go through the [security checklist](https://docs.sypnia.com/self-hosting/security-checklist).

## Point a domain at it

**At the end you will have:** the engine at `https://sypnia.example.com`. Do this before you ship the SDK in your app. The CloudFront address keeps working afterwards, so nothing that already sends to it breaks.

### 1. Ask for a certificate in us-east-1

CloudFront only takes certificates from `us-east-1`, whatever region your stack is in.

```bash
aws acm request-certificate --region us-east-1 \
  --domain-name sypnia.example.com --validation-method DNS \
  --query CertificateArn --output text
```

**You should see:**An address that starts with `arn:aws:acm:us-east-1:`. Keep it for the next steps.

### 2. Prove the domain is yours

```bash
aws acm describe-certificate --region us-east-1 --certificate-arn <the ARN> \
  --query "Certificate.DomainValidationOptions[0].ResourceRecord"
```

Create the `CNAME` record it prints at your DNS provider, then wait:

```bash
aws acm wait certificate-validated --region us-east-1 --certificate-arn <the ARN>
```

**You should see:**The command returns without a message, usually within a few minutes of the record existing.

### 3. Give the domain to the stack

Parameters you do not name keep their value.

```bash
aws cloudformation deploy \
  --template-file sypnia-aws.yaml \
  --stack-name sypnia \
  --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND \
  --parameter-overrides DomainName=sypnia.example.com CertificateArn=<the ARN>
```

**You should see:**`Successfully created/updated stack - sypnia`, after about 5 minutes.

### 4. Point the DNS record at the stack

```bash
aws cloudformation describe-stacks --stack-name sypnia \
  --query "Stacks[0].Outputs[?OutputKey=='DistributionDomain'].OutputValue" --output text
```

Create a `CNAME` record from `sypnia.example.com` to the name it prints. For a bare domain without a subdomain, use your DNS provider's alias record.

### 5. Check

```bash
curl -i https://sypnia.example.com/healthz
```

**You should see:**`HTTP/2 200`. `SYPNIA_BASE_URL` is now `https://sypnia.example.com`: links in alerts and prompts use it, and so does the Console. Load the settings into your shell again before the next `sypnia` command.

## Change a setting

Settings are read when a function starts, and a deploy restarts the functions.

- **A setting that has a parameter:** deploy again with the new value. For example, to connect a model:

  ```bash
  aws cloudformation deploy \
    --template-file sypnia-aws.yaml --stack-name sypnia \
    --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND \
    --parameter-overrides AiProvider=openrouter AiApiKey=<your key> AiModel=<model>
  ```

  Then load the settings again and run `sypnia doctor --only ai`.

- **Any other setting:** the three functions share one list of environment variables near the top of the template, under `Globals`. Add the setting's `SYPNIA_…` line there, keep the edited file, and deploy it. Keep your changes when you download a newer template.

## Update the engine

**At the end you will have:** the three functions on the new version, without stopping ingest. Migrations only add, so the old functions keep working against the new tables while the stack updates.

### 1. Read what changed

The [changelog](https://docs.sypnia.com/reference/changelog) says what each version changes and whether it asks anything of you.

### 2. Update the command and the template

```bash
curl -fsSL https://sypnia.com/install.sh | sh
curl -fsSLO https://github.com/sypnia/sypnia/releases/latest/download/sypnia-aws.yaml
sypnia version
```

**You should see:**The new version and the schema it needs, such as `sypnia 1.1.0 (…) schema 13`.

### 3. Update the tables first

With the settings loaded in your shell:

```bash
sypnia migrate
```

**You should see:**`database is up to date`.

### 4. Deploy the new template

```bash
aws cloudformation deploy \
  --template-file sypnia-aws.yaml \
  --stack-name sypnia \
  --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND
```

**You should see:**`Successfully created/updated stack - sypnia`. Every parameter keeps its value.

### 5. Check the version that answers

```bash
curl -s -o /dev/null -D - "$SYPNIA_BASE_URL/v1/whoami" \
  -H "Authorization: Bearer $SYPNIA_ROOT_TOKEN" | grep -i sypnia-version
```

**You should see:**`sypnia-version: 1.1.0`

To go back, deploy the previous template again. The database needs nothing: an older engine works against a newer schema. More on this in [Upgrades, backups, retention](https://docs.sypnia.com/self-hosting/upgrades-backups-retention).

## Remove everything

Deleting the stack removes the functions, the queue, the schedule, the address, the roles and the logs. It deliberately leaves your data: the bucket is kept, and the database the template created is deleted after a final snapshot.

### 1. Note the names, then delete the stack

```bash
aws cloudformation describe-stacks --stack-name sypnia --query "Stacks[0].Outputs" --output table
aws cloudformation delete-stack --stack-name sypnia
aws cloudformation wait stack-delete-complete --stack-name sypnia
```

**You should see:**The table shows `BucketName` and, if the template created the database, `DatabaseIdentifier`. The last command returns without a message after about 10 minutes.

### 2. Delete the bucket and everything in it

This cannot be undone.

```bash
aws s3 rb s3://<BucketName> --force
```

**You should see:**A line `remove_bucket: <BucketName>` at the end.

### 3. Delete the database's final snapshot

Only if the template created the database.

```bash
aws rds describe-db-snapshots --db-instance-identifier <DatabaseIdentifier> \
  --query "DBSnapshots[].DBSnapshotIdentifier" --output text
aws rds delete-db-snapshot --db-snapshot-identifier <the name printed>
```

### 4. Remove what you created by hand

The DNS records, the certificate (`aws acm delete-certificate`), and the root token file.

After this, nothing of Sypnia is left in the account and nothing is billed.

## Troubleshooting

| What you see                                                                                  | Why                                                                                                                                                     | What to do                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Requires capabilities : [CAPABILITY_AUTO_EXPAND]`                                            | The template uses a CloudFormation transform.                                                                                                           | Pass both capabilities, as in the commands above.                                                                                                                                              |
| The stack fails on a function with «S3 bucket does not exist» or «Access Denied»              | The function package is not published in your region.                                                                                                   | Download `sypnia-lambda-arm64.zip` from the same release, upload it to a bucket of yours in that region under `<Version>/sypnia-lambda-arm64.zip`, and deploy with `CodeBucket=<your bucket>`. |
| The stack fails with «The specified SSL certificate doesn't exist, isn't in us-east-1 region» | The certificate was requested in another region.                                                                                                        | Request it again with `--region us-east-1`.                                                                                                                                                    |
| `healthz` answers `502` or `503` right after the first deploy                                 | The tables do not exist yet. The engine refuses to start against a schema older than itself.                                                            | Run `sypnia migrate`. To see the reason: `aws logs tail /aws/lambda/sypnia-api --since 10m`.                                                                                                   |
| `sypnia doctor` says `database FAIL` from your machine, with your own Postgres                | Your database does not accept connections from the internet. The functions are outside your network, as your machine is.                                | Allow the connection with TLS, or use a database the functions can reach.                                                                                                                      |
| `sypnia doctor` passes and no problem ever appears                                            | The worker is not running.                                                                                                                              | `aws logs tail /aws/lambda/sypnia-worker --since 10m`. A line that names a missing setting, or a database error, says what to fix.                                                             |
| The API answers `503` with `Retry-After` under load                                           | The database has no free connection.                                                                                                                    | See [Scaling and cost](https://docs.sypnia.com/self-hosting/scaling-and-cost#database-connections).                                                                                            |
| Browsers get `403 origin_not_allowed`                                                         | The project lists allowed origins, and your app's is not among them.                                                                                    | Add it with `PATCH /v1/projects/{project_ref}`. See the [API reference](https://docs.sypnia.com/api/projects-keys-and-tokens).                                                                 |
| Events arrive and the Console does not play a replay                                          | The replay is read by your browser straight from the bucket, through a short-lived link. A proxy or an extension that blocks `amazonaws.com` breaks it. | Try another browser profile. See [The Console](https://docs.sypnia.com/self-hosting/console#when-something-does-not-show).                                                                     |

## Next
