# 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: the Sypnia engine (open source, self-hosted). Status: at launch.  
Source: https://docs.sypnia.com/self-hosting/

For agents: Overview of self-hosting the open-source Sypnia engine: the three things you run (the sypnia binary, Postgres 15+, an S3-compatible bucket), the two deployment shapes (AWS template, Docker Compose), requirements, cost summary, what must run for uptime checks, and what only Sypnia Cloud has.

**\[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](https://docs.sypnia.com/start/quickstart-self-host) and come back here before you put real traffic on it.

> **In plain words**
>
> Self-hosting means Sypnia runs on servers you pay for and look after. Your data never leaves them. In exchange, the work a service would do for you is yours: installing, upgrading, backing up, and connecting the pieces that send you an e-mail or write the sentence in plain words.

> **Note: The engine is not released yet**
>
> These pages are the engine's contract, written before its code. The names used here (the `sypnia` binary, the image `ghcr.io/sypnia/sypnia:1`, the AWS template `sypnia-aws.yaml`) are the planned ones. Costs, sizes and times are estimates with their arithmetic, or figures measured on the system this engine comes from, and each one says which.

## 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](https://docs.sypnia.com/self-hosting/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](https://docs.sypnia.com/architecture), and the two shapes side by side are in [Deployment shapes](https://docs.sypnia.com/architecture/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:

| Piece          | Default deployment                                                   | Alternatives the docs explain                                                                                     | Sypnia Cloud uses                                     |
| -------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| Object storage | The bucket the template creates.                                     | Any S3-compatible store: Amazon S3, Cloudflare R2, MinIO.                                                         | Amazon S3.                                            |
| Database       | A Postgres URL you provide, or the one the template creates.         | Amazon RDS, Supabase, Neon, or your own server.                                                                   | Postgres.                                             |
| Alert delivery | **None.** Alerts are recorded, and sent to a webhook if you set one. | Recipes: e-mail with Amazon SES, e-mail with any SMTP server, or your own function on the webhook.                | E-mail through Amazon SES, and alerts inside the app. |
| AI provider    | **Off** until you set a key.                                         | OpenRouter, the OpenAI API, the Anthropic API, Google Gemini, or any OpenAI-compatible endpoint, hosted or local. | OpenRouter.                                           |
| Pull requests  | Not in the engine.                                                   | Use the prompt or the MCP server with your own coding agent.                                                      | The Sypnia GitHub App.                                |

## Two ways to deploy

The same binary runs in two shapes. Pick by what you already operate.

|                         | [Deploy on AWS](https://docs.sypnia.com/self-hosting/deploy-aws)                                                                                                                           | [Deploy with Docker](https://docs.sypnia.com/self-hosting/deploy-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](https://docs.sypnia.com/self-hosting/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](https://docs.sypnia.com/self-hosting/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](https://docs.sypnia.com/agent/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](https://docs.sypnia.com/self-hosting/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](https://docs.sypnia.com/self-hosting/console): the problems list and the session replay viewer. Everything else is data you read through the [API](https://docs.sypnia.com/api), the [CLI](https://docs.sypnia.com/cli) or the [MCP server](https://docs.sypnia.com/mcp). |
| 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](https://docs.sypnia.com/guides/alert-emails-self-hosted).                                                                              |
| 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](https://docs.sypnia.com/agent/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`](https://docs.sypnia.com/cli/commands). The default, `all`, is every row of this table in one process.

## The pages of this section

- [Deploy on AWS](/self-hosting/deploy-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](/self-hosting/deploy-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](/self-hosting/configuration/): Every setting of the Sypnia engine: its environment variable, type, default and what it changes, with the choices for each pluggable piece.
- [Storage layout](/self-hosting/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](/self-hosting/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](/self-hosting/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](/self-hosting/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](/self-hosting/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](https://docs.sypnia.com/start/quickstart-self-host). It takes about fifteen minutes and shows you every moving part.

### 2. Deploy it where it will live

[Deploy on AWS](https://docs.sypnia.com/self-hosting/deploy-aws) or [Deploy with Docker](https://docs.sypnia.com/self-hosting/deploy-docker). Both end with `sypnia doctor` passing and a first project.

### 3. Go through the security checklist

The [security checklist](https://docs.sypnia.com/self-hosting/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](https://docs.sypnia.com/self-hosting/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](https://docs.sypnia.com/self-hosting/configuration).
