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.
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.
Start with the engine’s own check. Most items below show up in it:
sypnia doctorall 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.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 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. | |
| 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. |
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 and decide. | |
| Back it up, and try a restore | 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. | |
| Decide whether coding agents may mark problems resolved | SYPNIA_MCP_READ_ONLY=true removes the one MCP tool that writes. See 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. |
| 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. |
| 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. |
| 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. |
| Know how to delete one person | 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. |
| Upgrade within a reasonable time | 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. |
| You found a flaw in Sypnia itself | Do not post it in public | Write to the address in Security practices. |
Related
- How the engine is built to be safe, and what Sypnia Cloud does.
- Every setting named here.
- What a coding agent can and cannot do.