Docs

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.

Applies to Engine At launch

View as Markdown
On this page
  1. What you run
  2. Two ways to deploy
  3. What you need
  4. What it costs
  5. What you do not get
  6. What must be running for each feature
  7. The pages of this section
  8. The order to follow
  9. Try it on your machine
  10. Deploy it where it will live
  11. Go through the security checklist
  12. Set up backups, then decide retention
  13. 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:

PieceWhat it isWhat it holds
The engineOne 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 bucketAny S3-compatible object store: Amazon S3, Cloudflare R2, MinIO.Raw events, replay chunks, page snapshots, source maps.
A Postgres databaseVersion 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 AWSDeploy with Docker
What runsThree 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 afterAlmost nothing between upgrades. No server to patch.A server: its disk, its updates, its restarts.
Good whenTraffic 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 setupThe 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 usesThis 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.

SizeTrafficAWS shapeOne server with Docker
SmallAbout 1,000 sessions and 130,000 events a day (4 million events a month)About USD 22 a month, most of it the databaseAbout USD 25 to 30 a month
MediumAbout 10,000 sessions and 1.3 million events a day (40 million events a month)About USD 60 to 85 a monthAbout 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 hasA self-hosted engine has
The full app: performance, uptime and click-map screens, search, the daily summaryThe 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 rolesProjects, ingest keys and API tokens. Whoever holds a token gets in.
Alerts by e-mail and inside the appAlerts 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-mailNo summary e-mail. GET /v1/summary returns what is failing now.
The agent, with a model includedThe agent, off until you set your own model key.
Pull requests opened by the Sypnia GitHub AppNo pull requests. Use the prompt or the MCP server with your own coding agent.
Uptime checks from three regionsUptime checks from the one place where your worker runs.
Upgrades, backups and capacity done for youYours to do.
Support by e-mail on paid plansCommunity 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:

FeatureNeeds
Receiving events, replay chunks and OpenTelemetry tracesThe ingest role, reachable from browsers at your base URL.
New problems, sessions, numbers, alerts, webhooks, retentionThe worker role, or sypnia aggregate run by your own scheduler every minute.
Uptime checksThe 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 ConsoleThe api role.
The sentence in plain wordsThe 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 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.

  • Deploy with Docker

    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.

  • Configuration reference

    Every setting of the Sypnia engine: its environment variable, type, default and what it changes, with the choices for each pluggable piece.

  • Storage layout

    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.

  • The Console

    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.

  • Upgrades, backups, retention

    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.

  • Scaling and cost

    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.

  • Security checklist

    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

  1. Try it on your machine

    Follow the self-host quickstart. It takes about fifteen minutes and shows you every moving part.

  2. Deploy it where it will live

    Deploy on AWS or Deploy with Docker. Both end with sypnia doctor passing and a first project.

  3. Go through the security checklist

    The security checklist is short. Do it before you point a real app at the engine.

  4. Set up backups, then decide retention

    Upgrades, backups, retention.

  5. Connect the optional pieces

    A model key for the agent, and a webhook for alerts. Both are in the configuration reference.

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