Docs

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 Engine At launch

View as Markdown
On this page
  1. 1. The root token
  2. 2. The address
  3. 3. The bucket
  4. 4. The database
  5. 5. API tokens
  6. 6. Ingest keys
  7. 7. The Console and the MCP server
  8. 8. What the engine calls
  9. 9. What is recorded
  10. 10. Secrets, logs and upgrades
  11. If something went wrong
  12. Related

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:

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

1. The root token

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

DoHowCheck
Make it long and randomopenssl rand -hex 32. The engine refuses fewer than 32 characters.The engine starts.
Keep it out of apps, CI and coding agentsUse 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 browserThe Console refuses it.
Know how to replace itChange 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

DoHowCheck
Serve everything over HTTPSA 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 privateOnly 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 frontSYPNIA_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 sitesSYPNIA_API_CORS_ORIGINS empty, unless a web app of yours calls the read API from a browser.

3. The bucket

DoHowCheck
Keep it privateBlock 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 onlyA 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 browserThe bucket’s CORS rule names your base URL, not *. See the rule.
Keep signed links shortSYPNIA_STORAGE_PRESIGN_TTL_SECONDS at its default of 900, or lower.
Encrypt it at restYour store’s own setting. The AWS template turns it on.
Leave versioning off, or expire old versionsOtherwise deleted data survives in old versions. See Storage layout.

4. The database

DoHowCheck
Give Sypnia a database and a user of its ownNot 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 itA 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 restoreBackups.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.

DoHowCheck
One token per person and per toolsypnia token create --name says who or what.sypnia token list --project shop reads like a list of people and tools.
The fewest scopesread 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 usedsypnia token revoke. It is refused within one minute.The LAST USED column.
Keep tokens out of code and out of chatsIn 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.

DoHowCheck
List the origins allowed to send from a browserPATCH /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 appsypnia 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 storeSYPNIA_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

DoHowCheck
Decide who can load the ConsoleA proxy rule on /console, or SYPNIA_CONSOLE_ENABLED=false. See Protect it.
Decide whether coding agents may mark problems resolvedSYPNIA_MCP_READ_ONLY=true removes the one MCP tool that writes. See MCP security.
Switch off what you do not useSYPNIA_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.

DoHow
Keep uptime checks away from your private networkSYPNIA_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 addressesSYPNIA_WEBHOOKS_ALLOW_HTTP stays false.
Sign the alert webhookSet SYPNIA_ALERT_WEBHOOK_SECRET, and check the signature in your receiver. See Check the signature.
Decide what the AI provider may seeWith 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 billLeave 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.

DoHow
Look at one replay of each sensitive screen before productionTyped 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 placesettings.replay.blocked_routes on the project, or SYPNIA_REPLAY_ENABLED=false for the whole engine.
Do not publish your source mapssypnia sourcemaps upload … --delete-after removes them from what you deploy.
Choose how long personal data livesRetention.
Know how to delete one personDeleting data.

10. Secrets, logs and upgrades

DoHow
Keep the settings file privatechmod 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 infoThe 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 logsThey 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 releasesWatch the engine’s repository for new versions. Security fixes are marked in the changelog.
Upgrade within a reasonable timeUpgrades are built to be boring: migrate, replace, check.

If something went wrong

What happenedFirst, within minutesThen
An API token leakedsypnia token revoke <token_id>Create a new one. Check LAST USED on the others.
The root token leakedChange SYPNIA_ROOT_TOKEN and restartsypnia project list and sypnia token list for each project: look for anything you did not create.
An ingest key is being abusedsypnia key create, deploy your app with the new key, then sypnia key revoke the old oneSet 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 notMask the element and deployDelete the sessions that recorded it: Deleting data.
You found a flaw in Sypnia itselfDo not post it in publicWrite to the address in Security practices.

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