Docs

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 Engine At launch

View as Markdown
On this page
  1. What the template creates
  2. Parameters
  3. Deploy
  4. Install the sypnia command on your machine
  5. Choose the region and make the root token
  6. Download the template
  7. Deploy the stack
  8. Load the engine's settings into your shell
  9. Create the tables
  10. Check the deployment
  11. Create the first project and a token
  12. Send from your app and see it arrive
  13. Point a domain at it
  14. Ask for a certificate in us-east-1
  15. Prove the domain is yours
  16. Give the domain to the stack
  17. Point the DNS record at the stack
  18. Check
  19. Change a setting
  20. Update the engine
  21. Read what changed
  22. Update the command and the template
  23. Update the tables first
  24. Deploy the new template
  25. Check the version that answers
  26. Remove everything
  27. Note the names, then delete the stack
  28. Delete the bucket and everything in it
  29. Delete the database's final snapshot
  30. Remove what you created by hand
  31. Troubleshooting
  32. Next

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.

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 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.

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.

Diagram to drawARCHITECTURE 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».
Figure. The stack the template creates. Three functions are the same binary with three roles.
#ResourceWhat it doesTemplate default
1A CloudFront distributionThe 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
2Function sypnia-ingestSYPNIA_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
3Function sypnia-apiSYPNIA_ROLE=api. The API, the MCP server and the Console.512 MB, 30 s, at most 20 copies
4A queue, and a second one for messages that failed five timesHolds batches for up to 4 days until the worker writes them. It is the buffer a function cannot keep in memory.Standard queue
5Function sypnia-worker, and a schedule that wakes it every minuteSYPNIA_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
6An S3 bucketRaw 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
7An RDS Postgres, only if you ask for itThe 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 functionEach 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 alarmsOne 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 and Data flow.

Parameters

ParameterDefaultWhat it sets
RootTokenRequiredThe root token, SYPNIA_ROOT_TOKEN. At least 32 characters.
CreateDatabasetruetrue creates the RDS Postgres. false uses DatabaseUrl.
DatabaseUrlEmptyYour own Postgres, as SYPNIA_DATABASE_URL. Required when CreateDatabase is false. End it with ?sslmode=require.
DatabaseInstanceClassdb.t4g.microThe size of the database the template creates.
DomainNameEmptyYour own domain for the engine, such as sypnia.example.com. Empty uses the address CloudFront gives the stack.
CertificateArnEmptyThe certificate for DomainName, from AWS Certificate Manager in us-east-1. Required with DomainName.
AiProvider, AiApiKey, AiModelnone, empty, emptySYPNIA_AI_PROVIDER, SYPNIA_AI_API_KEY, SYPNIA_AI_MODEL. The agent is off while the provider is none.
AlertWebhookUrl, AlertWebhookSecretEmptySYPNIA_ALERT_WEBHOOK_URL, SYPNIA_ALERT_WEBHOOK_SECRET. Empty sends nothing; alerts are still recorded.
VersionThe template’s own versionWhich release of the engine the functions run.
CodeBucketsypnia-releases-<region>The bucket the function package is read from. Change it only if your region has none (see 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 has its default until you change it.

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.

    Terminal
    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

    Terminal
    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

    Terminal
    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:

    Terminal
    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:

    Terminal
        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.

    Terminal
    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

    Terminal
    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

    Terminal
    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

    Terminal
    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
    Terminal
    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: init({ project: 'spk_…', endpoint: '<your base URL>' }). Open your app, click around, then:

    Terminal
    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 at the engine, so the address in your app is the final one, and go through the 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.

    Terminal
    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

    Terminal
    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:

    Terminal
    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.

    Terminal
    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

    Terminal
    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

    Terminal
    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:

    Terminal
    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 says what each version changes and whether it asks anything of you.

  2. Update the command and the template

    Terminal
    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:

    Terminal
    sypnia migrate
    You should see
    database is up to date.
  4. Deploy the new template

    Terminal
    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

    Terminal
    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.

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

    Terminal
    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.

    Terminal
    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.

    Terminal
    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 seeWhyWhat 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 deployThe 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 PostgresYour 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 appearsThe 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 loadThe database has no free connection.See Scaling and cost.
Browsers get 403 origin_not_allowedThe project lists allowed origins, and your app’s is not among them.Add it with PATCH /v1/projects/{project_ref}. See the API reference.
Events arrive and the Console does not play a replayThe 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.

Next

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close