Self-hosting
What 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.
On this page
- What you run
- Two ways to deploy
- What you need
- What it costs
- What you do not get
- What must be running for each feature
- The pages of this section
- The order to follow
- Try it on your machine
- Deploy it where it will live
- Go through the security checklist
- Set up backups, then decide retention
- Connect the optional pieces
Engine This section is for whoever will run the open-source engine on their own infrastructure. Nothing here applies to Sypnia Cloud, where we run the same engine for you. If you only want to try the engine on your laptop, start with the self-host quickstart and come back here before you put real traffic on it.
What you run
Three things, and nothing else:
| Piece | What it is | What it holds |
|---|---|---|
| The engine | One program, sypnia. It receives events, processes them, answers the API and the MCP server, and serves the Console. | Nothing. It keeps no state of its own. |
| A bucket | Any S3-compatible object store: Amazon S3, Cloudflare R2, MinIO. | Raw events, replay chunks, page snapshots, source maps. |
| A Postgres database | Version 15 or later: Amazon RDS, Supabase, Neon, or your own server. | Problems, the session index, numbers per hour and per day, projects, keys, tokens and settings. |
What else there is depends on the shape you deploy:
- As one long-running process (Docker, or any server): nothing besides the engine, Postgres and the bucket. No queue, no cache, no search server.
- With the AWS template: the engine runs as three functions, and the template also creates a schedule and a managed queue between ingest and the worker. You do not operate either: nothing to patch, size or restart.
Why two stores are enough is in How the engine is built, and the two shapes side by side are in Deployment shapes.
Each piece that depends on a provider is your choice. Two of them, alert delivery and the AI provider, are off until you connect them, and the engine works without either:
Object storage
Holds raw events, replay chunks, page snapshots and source maps.
- Default deployment
- The bucket the template creates.
- Alternatives the docs explain
- Any S3-compatible store: Amazon S3, Cloudflare R2, MinIO.
- Sypnia Cloud uses
- Amazon S3.
Database
Holds the aggregates, the session index, problems and configuration.
- Default deployment
- A Postgres URL you provide, or the one the template creates.
- Alternatives the docs explain
- Amazon RDS, Supabase, Neon, or your own server.
- Sypnia Cloud uses
- Postgres.
Alert delivery
Gets an alert from the engine to a person.
- Default deployment
- None. Alerts are recorded, and sent to a webhook if you set one.
- Alternatives the docs explain
- Recipes: e-mail with Amazon SES, e-mail with any SMTP server, or your own function on the webhook.
- Sypnia Cloud uses
- E-mail through Amazon SES, and alerts inside the app.
AI provider
Runs the model behind the agent’s analysis and the ready prompt.
- Default deployment
- Off until you set a key.
- Alternatives the docs explain
- OpenRouter, the OpenAI API, the Anthropic API, Google Gemini, or any OpenAI-compatible endpoint, hosted or local.
- Sypnia Cloud uses
- OpenRouter.
Pull requests
Opens the pull request with the fix.
- Default deployment
- Not in the engine.
- Alternatives the docs explain
- Use the prompt or the MCP server with your own coding agent.
- Sypnia Cloud uses
- The Sypnia GitHub App.
Two ways to deploy
The same binary runs in two shapes. Pick by what you already operate.
| Deploy on AWS | Deploy with Docker | |
|---|---|---|
| What runs | Three functions (ingest, API, worker), a managed queue, a schedule, a bucket, and an address in front, all created by the template. Postgres is created by the template or brought by you. | One long-running process, sypnia serve, next to a Postgres and a bucket. |
| You look after | Almost nothing between upgrades. No server to patch. | A server: its disk, its updates, its restarts. |
| Good when | Traffic comes in bursts, or you already live in AWS. | You have a server, want one bill that does not move, or do not use AWS. |
| Smallest sensible setup | The template’s defaults. | 2 vCPU, 4 GB of memory, 40 GB of disk for everything on one machine (an estimate; see Scaling and cost). |
| Sypnia Cloud uses | This shape, in us-east-1. |
You can move from one to the other later: both read the same bucket layout and the same database schema.
What you need
- A domain name and HTTPS. Browsers send to the engine’s address, and that address is written into your app. Choose it once:
https://sypnia.example.com. - An account with a cloud provider, or a server. For AWS, permission to create functions, a bucket, a queue and roles. For Docker, a Linux machine with Docker and Compose.
- Someone who can restore a Postgres backup. The database holds what cannot be rebuilt: your projects, keys, tokens, and what people marked on problems. See Upgrades, backups, retention.
- About an hour for the first deployment, and a few minutes for each upgrade.
- A model key, only if you want the sentence in plain words. Without one the engine works, and problems keep their technical title. See Models and what is sent.
You do not need a Sypnia account. A self-hosted engine never contacts Sypnia, the company: no licence check, no usage report, no telemetry.
What it costs
The engine is free: no licence fee, and no limit set by us on projects, events, replays or retention. You pay your own provider.
| Size | Traffic | AWS shape | One server with Docker |
|---|---|---|---|
| Small | About 1,000 sessions and 130,000 events a day (4 million events a month) | About USD 22 a month, most of it the database | About USD 25 to 30 a month |
| Medium | About 10,000 sessions and 1.3 million events a day (40 million events a month) | About USD 60 to 85 a month | About USD 60 to 75 a month |
These are estimates, not quotes. The arithmetic behind each number, what makes it move, and the measured figures of the system this engine comes from are in Scaling and cost.
What you do not get
The engine does all the receiving, storing and analysing. What Sypnia Cloud adds is everything around it. If you self-host, none of this exists unless you build it:
| Sypnia Cloud has | A self-hosted engine has |
|---|---|
| The full app: performance, uptime and click-map screens, search, the daily summary | The Console: the problems list and the session replay viewer. Everything else is data you read through the API, the CLI or the MCP server. |
| Users, organizations and roles | Projects, ingest keys and API tokens. Whoever holds a token gets in. |
| Alerts by e-mail and inside the app | Alerts recorded, and sent to a webhook if you set one. The default deployment sends no e-mail. Recipe: Alert e-mails from a self-hosted engine. |
| The daily summary by e-mail | No summary e-mail. GET /v1/summary returns what is failing now. |
| The agent, with a model included | The agent, off until you set your own model key. |
| Pull requests opened by the Sypnia GitHub App | No pull requests. Use the prompt or the MCP server with your own coding agent. |
| Uptime checks from three regions | Uptime checks from the one place where your worker runs. |
| Upgrades, backups and capacity done for you | Yours to do. |
| Support by e-mail on paid plans | Community support, in the engine’s repository. |
There is no WhatsApp and no Slack integration in either.
What must be running for each feature
One process started with sypnia serve runs everything. If you split the engine into roles, or run it as functions, this is what each feature needs:
| Feature | Needs |
|---|---|
| Receiving events, replay chunks and OpenTelemetry traces | The ingest role, reachable from browsers at your base URL. |
| New problems, sessions, numbers, alerts, webhooks, retention | The worker role, or sypnia aggregate run by your own scheduler every minute. |
| Uptime checks | The worker role, and SYPNIA_UPTIME_ENABLED left at true. Checks are made from the machine or region where the worker runs, so it sees your app from one place. If the worker shares a server with the app it watches, an outage of that server stops the checks too: run them from somewhere else. Private and loopback addresses are refused unless you set SYPNIA_UPTIME_ALLOW_PRIVATE_ADDRESSES. |
| The API, the MCP server and the Console | The api role. |
| The sentence in plain words | The worker role and an AI provider. |
The roles are a flag of sypnia serve. The default, all, is every row of this table in one process.
The pages of this section
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.
Run the Sypnia engine on any server with Docker Compose, next to a Postgres and an S3-compatible store, with HTTPS, a first project, its keys and a health check.
Every setting of the Sypnia engine: its environment variable, type, default and what it changes, with the choices for each pluggable piece.
Where a self-hosted engine keeps each kind of data, how much space it takes, how to measure it, and which bucket rules to add and which to avoid.
What the engine's one built-in page shows, how to open it with an API token, how to protect it or switch it off, and what it does not do compared with the Sypnia Cloud app.
How to upgrade a self-hosted engine without losing data, what to back up and how to restore it, and how to choose how long each kind of data is kept.
What a self-hosted engine costs each month for a small and a medium project, with the arithmetic, what makes the bill move, the first limits you meet, and when to go from one process to several or to functions.
What to close on a self-hosted engine before real traffic reaches it, each item with the setting or command that does it and the check that proves it.
The order to follow
Try it on your machine
Follow the self-host quickstart. It takes about fifteen minutes and shows you every moving part.
Deploy it where it will live
Deploy on AWS or Deploy with Docker. Both end with
sypnia doctorpassing and a first project.Go through the security checklist
The security checklist is short. Do it before you point a real app at the engine.
Connect the optional pieces
A model key for the agent, and a webhook for alerts. Both are in the configuration reference.