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

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

For agents: Checklist for securing a self-hosted Sypnia engine before production: the root token, HTTPS and the proxy hop count, a private bucket with a narrow key and CORS rule, a database of its own with TLS, API tokens with the fewest scopes and an expiry, allowed origins and quotas for ingest keys, the Console and MCP server, outbound calls (uptime checks, webhooks, the AI provider), backups, logs and upgrades. Each item names the exact setting or command and how to verify it.

**\[Engine]** This page is for whoever is about to point a real app at a self-hosted engine. Go through it once before production and again after any change to the deployment. On Sypnia Cloud these are our job, and what we do is in [Security practices](https://docs.sypnia.com/privacy/security-practices).

Start with the engine's own check. Most items below show up in it:

```bash
sypnia doctor
```

**You should see:**`all checks passed`, with `0 unknown` settings and no line that warns. A webhook without a secret, or a variable with a typo, is a warning here.

> **Note: What this list is and is not**
>
> It covers the engine and the pieces around it. It is a list of practices, not a certification: following it does not make a deployment compliant with any law or standard. Your server, your cloud account and your network have their own hardening, which is not Sypnia's to describe.

## 1. The root token

The root token can do everything on every project, including deleting them.

| Do                                        | How                                                                                                          | Check                                                                                         |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| Make it long and random                   | `openssl rand -hex 32`. The engine refuses fewer than 32 characters.                                         | The engine starts.                                                                            |
| Keep it out of apps, CI and coding agents | Use it to create projects and their first tokens, then put it away. Everything else works with an API token. | Search your CI's secrets and your agents' configuration for it: it should be in neither.      |
| Never paste it in a browser               | The [Console](https://docs.sypnia.com/self-hosting/console) refuses it.                                      |                                                                                               |
| Know how to replace it                    | Change `SYPNIA_ROOT_TOKEN` and restart. The old one stops working at once.                                   | `curl -i <your base URL>/v1/whoami -H "Authorization: Bearer <the old token>"` answers `401`. |

## 2. The address

| Do                                              | How                                                                                                                                                                               | Check                                                                    |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Serve everything over HTTPS                     | A proxy or load balancer with TLS in front of the engine. `SYPNIA_BASE_URL` starts with `https://`.                                                                               | `sypnia doctor` line `address`.                                          |
| Keep the engine's port private                  | Only the proxy reaches port 8080. In the Compose file the `sypnia` service has no `ports`.                                                                                        | From outside: `curl <server address>:8080/healthz` gets no answer.       |
| Tell the engine how many proxies stand in front | `SYPNIA_TRUSTED_PROXY_HOPS`: `1` behind one proxy, `0` with none. Too low, and all visitors share one rate limit. Too high, and a caller can fake its address to dodge the limit. | Send requests from two networks: each has its own `RateLimit-Remaining`. |
| Leave the read API closed to other sites        | `SYPNIA_API_CORS_ORIGINS` empty, unless a web app of yours calls the read API from a browser.                                                                                     |                                                                          |

## 3. The bucket

| Do                                                | How                                                                                                                                                                     | Check                                                |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Keep it private                                   | Block all public access. Nothing is ever read without a link the engine signs. The AWS template does this.                                                              | Open any object's plain address in a browser: `403`. |
| Give the engine a key for this bucket only        | A key or a role that can read, write, list and delete in this one bucket. On AWS, leave the keys empty and let the engine use its role.                                 | With that key, listing another bucket is refused.    |
| Let only your address read replays from a browser | The bucket's CORS rule names your base URL, not `*`. See [the rule](https://docs.sypnia.com/self-hosting/deploy-docker#let-browsers-read-replays-from-a-hosted-bucket). |                                                      |
| Keep signed links short                           | `SYPNIA_STORAGE_PRESIGN_TTL_SECONDS` at its default of 900, or lower.                                                                                                   |                                                      |
| Encrypt it at rest                                | Your store's own setting. The AWS template turns it on.                                                                                                                 |                                                      |
| Leave versioning off, or expire old versions      | Otherwise deleted data survives in old versions. See [Storage layout](https://docs.sypnia.com/self-hosting/storage-layout#rules-on-the-bucket).                         |                                                      |

## 4. The database

| Do                                           | How                                                                                                                                                                                                                                                          | Check                                                          |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| Give Sypnia a database and a user of its own | Not the database of your app. The user needs to create tables in its own schema, nothing more.                                                                                                                                                               |                                                                |
| Encrypt the connection                       | `?sslmode=require` at the end of `SYPNIA_DATABASE_URL` whenever the database is not on the same machine.                                                                                                                                                     | `sypnia doctor` line `database`.                               |
| Limit who can reach it                       | A private network or an allow-list where you can. The database the AWS template creates is reachable from the internet, with TLS and a generated password; read [why](https://docs.sypnia.com/self-hosting/deploy-aws#what-the-template-creates) and decide. |                                                                |
| Back it up, and try a restore                | [Backups](https://docs.sypnia.com/self-hosting/upgrades-backups-retention#backups).                                                                                                                                                                          | A dump from last night exists somewhere other than the server. |

## 5. API tokens

An API token reads your project. With `replay` it reads what your users saw on their screens. With `admin` it changes settings and deletes data.

| Do                                       | How                                                                                                            | Check                                                                     |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| One token per person and per tool        | `sypnia token create --name` says who or what.                                                                 | `sypnia token list --project shop` reads like a list of people and tools. |
| The fewest scopes                        | `read` for a coding agent. `read,replay` for a person who watches replays. `admin` only for CI and for you.    |                                                                           |
| An end date                              | `--expires 90d` for people, `--expires 365d` for CI.                                                           | The `EXPIRES` column has no `never` you cannot explain.                   |
| Revoke what is not used                  | `sypnia token revoke`. It is refused within one minute.                                                        | The `LAST USED` column.                                                   |
| Keep tokens out of code and out of chats | In your CI's secrets and your agent's own configuration. Never in a repository, a ticket or a support message. |                                                                           |

## 6. Ingest keys

An ingest key is public by design: anyone who reads your page can send events with it. What protects you is what the key cannot do, and three limits you set.

| Do                                              | How                                                                                                                                      | Check                                                             |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| List the origins allowed to send from a browser | `PATCH /v1/projects/{project_ref}` with `{"settings": {"allowed_origins": ["https://shop.example.com"]}}`. Empty accepts any origin.     | A request with another `Origin` answers `403 origin_not_allowed`. |
| One key per app                                 | `sypnia key create --project shop --name "Checkout API"`, so you can revoke one without stopping the others.                             |                                                                   |
| A rate limit that fits                          | `--rate-limit` on the key, or `SYPNIA_RATE_LIMIT_INGEST_PER_MINUTE` for new keys.                                                        |                                                                   |
| A ceiling on what a project can store           | `SYPNIA_QUOTA_EVENTS_PER_MONTH` and `SYPNIA_QUOTA_REPLAYS_PER_MONTH`. They protect your storage and your bill from a loop or from abuse. | `GET /v1/usage` shows the limits.                                 |

Allowed origins stop other websites from sending with your key. They do not stop a script that fakes the header; the rate limit and the quota are for that.

## 7. The Console and the MCP server

| Do                                                      | How                                                                                                                                       | Check                                |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| Decide who can load the Console                         | A proxy rule on `/console`, or `SYPNIA_CONSOLE_ENABLED=false`. See [Protect it](https://docs.sypnia.com/self-hosting/console#protect-it). |                                      |
| Decide whether coding agents may mark problems resolved | `SYPNIA_MCP_READ_ONLY=true` removes the one MCP tool that writes. See [MCP security](https://docs.sypnia.com/mcp/security).               |                                      |
| Switch off what you do not use                          | `SYPNIA_MCP_ENABLED=false` removes the MCP server at `/mcp`.                                                                              | `<your base URL>/mcp` answers `404`. |

## 8. What the engine calls

The worker makes requests to addresses that people with an `admin` token choose. Keep the defaults unless you have a reason.

| Do                                                | How                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Keep uptime checks away from your private network | `SYPNIA_UPTIME_ALLOW_PRIVATE_ADDRESSES` stays `false`. Otherwise anyone with an `admin` token can make the engine probe addresses inside your network.                                                                                                                                                                   |
| Keep webhooks on HTTPS and public addresses       | `SYPNIA_WEBHOOKS_ALLOW_HTTP` stays `false`.                                                                                                                                                                                                                                                                              |
| Sign the alert webhook                            | Set `SYPNIA_ALERT_WEBHOOK_SECRET`, and check the signature in your receiver. See [Check the signature](https://docs.sypnia.com/api/webhooks#check-the-signature).                                                                                                                                                        |
| Decide what the AI provider may see               | With a provider set, the agent sends it stacks, traces and source lines around the failure. `SYPNIA_AI_SEND_SOURCE=false` keeps your source out. An OpenAI-compatible endpoint inside your network keeps everything in. The full list: [Models and what is sent](https://docs.sypnia.com/agent/models-and-what-is-sent). |
| Cap the model's bill                              | Leave `SYPNIA_AI_MAX_ANALYSES_PER_DAY` at 100 or lower, and set a spending limit on the key at your provider.                                                                                                                                                                                                            |

## 9. What is recorded

Securing the engine is half of it. The other half is what your app sends.

| Do                                                            | How                                                                                                                                                    |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Look at one replay of each sensitive screen before production | Typed input is always masked. Text shown on the page is recorded as shown, unless you mask it. See [Masking](https://docs.sypnia.com/privacy/masking). |
| Switch recording off where it has no place                    | `settings.replay.blocked_routes` on the project, or `SYPNIA_REPLAY_ENABLED=false` for the whole engine.                                                |
| Do not publish your source maps                               | `sypnia sourcemaps upload … --delete-after` removes them from what you deploy.                                                                         |
| Choose how long personal data lives                           | [Retention](https://docs.sypnia.com/self-hosting/upgrades-backups-retention#retention).                                                                |
| Know how to delete one person                                 | [Deleting data](https://docs.sypnia.com/privacy/deleting-data).                                                                                        |

## 10. Secrets, logs and upgrades

| Do                               | How                                                                                                                                                                                                                                                       |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Keep the settings file private   | `chmod 600 .env`, and keep it out of any repository. On AWS the settings are environment variables of the functions: anyone in the account who may read a function's configuration can read them, the root token included. Limit who has that permission. |
| Keep the log level at `info`     | The engine never logs bodies, keys or tokens at any level. `debug` logs one line per request, which is a lot to keep.                                                                                                                                     |
| Mind the proxy's logs            | They hold IP addresses, and the ingest key when a browser sends it as `?key=`. The ingest key is public; the addresses are personal data. Keep those logs as short a time as you can.                                                                     |
| Follow releases                  | Watch the engine's repository for new versions. Security fixes are marked in the [changelog](https://docs.sypnia.com/reference/changelog).                                                                                                                |
| Upgrade within a reasonable time | [Upgrades](https://docs.sypnia.com/self-hosting/upgrades-backups-retention#upgrades) are built to be boring: migrate, replace, check.                                                                                                                     |

## If something went wrong

| What happened                          | First, within minutes                                                                       | Then                                                                                                                               |
| -------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| An API token leaked                    | `sypnia token revoke <token_id>`                                                            | Create a new one. Check `LAST USED` on the others.                                                                                 |
| The root token leaked                  | Change `SYPNIA_ROOT_TOKEN` and restart                                                      | `sypnia project list` and `sypnia token list` for each project: look for anything you did not create.                              |
| An ingest key is being abused          | `sypnia key create`, deploy your app with the new key, then `sypnia key revoke` the old one | Set allowed origins and a quota. Events that were already stored stay; a project you no longer trust can be deleted and recreated. |
| A replay shows something it should not | Mask the element and deploy                                                                 | Delete the sessions that recorded it: [Deleting data](https://docs.sypnia.com/privacy/deleting-data).                              |
| You found a flaw in Sypnia itself      | Do not post it in public                                                                    | Write to the address in [Security practices](https://docs.sypnia.com/privacy/security-practices#report-a-security-problem).        |

## Related
