Configuration reference
Every setting of the Sypnia engine: its environment variable, type, default and what it changes, with the choices for each pluggable piece.
On this page
- How settings are read
- The pieces you choose
- Core
- SYPNIA_BASE_URL
- SYPNIA_ROOT_TOKEN
- SYPNIA_LISTEN
- SYPNIA_ROLE
- SYPNIA_AUTO_MIGRATE
- SYPNIA_TRUSTED_PROXY_HOPS
- SYPNIA_LOG_LEVEL
- SYPNIA_LOG_FORMAT
- SYPNIA_CONSOLE_ENABLED
- SYPNIA_MCP_ENABLED
- SYPNIA_MCP_READ_ONLY
- SYPNIA_API_CORS_ORIGINS
- Database
- SYPNIA_DATABASE_URL
- SYPNIA_DATABASE_MAX_CONNECTIONS
- Object storage
- SYPNIA_STORAGE_BUCKET
- SYPNIA_STORAGE_REGION
- SYPNIA_STORAGE_ENDPOINT
- SYPNIA_STORAGE_PUBLIC_ENDPOINT
- SYPNIA_STORAGE_ACCESS_KEY_ID
- SYPNIA_STORAGE_SECRET_ACCESS_KEY
- SYPNIA_STORAGE_PATH_STYLE
- SYPNIA_STORAGE_PREFIX
- SYPNIA_STORAGE_PRESIGN_TTL_SECONDS
- Processing and retention
- SYPNIA_PROCESSING_INTERVAL_SECONDS
- SYPNIA_PROCESSING_CONCURRENCY
- SYPNIA_RETENTION_EVENTS_DAYS
- SYPNIA_RETENTION_REPLAYS_DAYS
- SYPNIA_RETENTION_SNAPSHOTS_DAYS
- SYPNIA_RETENTION_NUMBERS_DAYS
- SYPNIA_RETENTION_SOURCEMAPS_DAYS
- Quotas and rate limits
- SYPNIA_QUOTA_EVENTS_PER_MONTH
- SYPNIA_QUOTA_REPLAYS_PER_MONTH
- SYPNIA_QUOTA_UPTIME_CHECKS
- SYPNIA_RATE_LIMIT_API_PER_MINUTE
- SYPNIA_RATE_LIMIT_INGEST_PER_MINUTE
- Recording defaults
- SYPNIA_REPLAY_ENABLED
- SYPNIA_REPLAY_SAMPLE_RATE
- SYPNIA_SNAPSHOTS_SAMPLE_RATE
- Uptime checks
- SYPNIA_UPTIME_ENABLED
- SYPNIA_UPTIME_ALLOW_PRIVATE_ADDRESSES
- Alert delivery
- SYPNIA_ALERT_WEBHOOK_URL
- SYPNIA_ALERT_WEBHOOK_SECRET
- SYPNIA_WEBHOOKS_ALLOW_HTTP
- SYPNIA_WEBHOOKS_TIMEOUT_SECONDS
- AI provider
- SYPNIA_AI_PROVIDER
- SYPNIA_AI_API_KEY
- SYPNIA_AI_MODEL
- SYPNIA_AI_BASE_URL
- SYPNIA_AI_MAX_ANALYSES_PER_DAY
- SYPNIA_AI_MAX_ANALYSES_PER_PROBLEM_PER_DAY
- SYPNIA_AI_TIMEOUT_SECONDS
- SYPNIA_AI_MAX_OUTPUT_TOKENS
- SYPNIA_AI_SEND_SOURCE
- SYPNIA_AI_LANGUAGE
- SYPNIA_AI_WEEKLY_SUGGESTIONS
- Pull requests
- What the engine never sends
Engine This page lists every setting of a self-hosted engine. Sypnia Cloud is run by us: there, none of these is yours to set.
The smallest configuration that starts is five settings: the engine’s address, the root token, the database and the bucket. Everything else has a default.
SYPNIA_BASE_URL=https://sypnia.example.com
SYPNIA_ROOT_TOKEN=<a long random string>
SYPNIA_DATABASE_URL=postgres://sypnia:<password>@db.internal:5432/sypnia
SYPNIA_STORAGE_BUCKET=sypnia-shop
SYPNIA_STORAGE_REGION=us-east-1Then run sypnia migrate, sypnia doctor and sypnia serve. The machine-readable list of settings is spec/config.yaml in the docs repository.
How settings are read
Each setting has an environment variable (SYPNIA_…) and a key for a configuration file in TOML, given with --config or SYPNIA_CONFIG. The key ai.provider is written like this in the file:
[ai]
provider = "openrouter"
model = "<model>"When both are set, the environment wins.
- Booleans are
trueorfalse. Lists are comma-separated in the environment and arrays in the file. - A setting marked required stops the engine at start, with exit code 3 and a message that names it, when it is missing.
- An unknown
SYPNIA_…variable is a warning insypnia doctor, not an error, so a typo is found and an old setting does not stop an upgrade. - Secrets (the root token, storage keys, the AI key, the webhook secret) are never printed, logged or returned by the API.
- Settings are read at start. Change one, then restart the engine.
The pieces you choose
The default deployment holds only what cannot be left out. Everything that depends on a provider is your choice. Each one is set in its section below.
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.
Core
What the engine needs to start and to know its own address.
- Key
base_url- Type
- URL
- Default
- none
- Required
- yes
The public address of the engine, as browsers and your CI reach it, with https:// and without a slash at the end. SDKs send to it, links in alerts and prompts start with it, and the Console is at <base URL>/console.
Example: SYPNIA_BASE_URL=https://sypnia.example.com
- Key
root_token- Type
- string (secret)
- Default
- none
- Required
- yes
The root token. It can do everything on every project, and it is how you create the first project and the first tokens. At least 32 characters; generate it with openssl rand -hex 32. To change it, set a new value and restart; the old one stops working at once.
- Key
listen- Type
- address
- Default
0.0.0.0:8080
The address and port sypnia serve listens on. Put a reverse proxy or a load balancer with TLS in front of it.
- Key
role- Type
- all | ingest | api | worker
- Default
all
Which part of the engine this process runs. all is the whole engine in one process (Docker). The AWS template runs one function per role. See sypnia serve.
- Key
auto_migrate- Type
- boolean
- Default
false
true makes sypnia serve apply pending database migrations when it starts. Leave it false when more than one process starts at the same time, and run sypnia migrate as a deploy step.
- Key
trusted_proxy_hops- Type
- integer
- Default
0
How many reverse proxies you run in front of the engine. The engine takes the caller’s address from that many steps back in X-Forwarded-For, for rate limits. 0 uses the address of the connection. A wrong number lets callers fake their address or makes everyone share one limit.
- Key
log.level- Type
- error | warn | info | debug
- Default
info
How much the engine logs to standard output. debug logs one line per request; it never logs bodies, keys or tokens.
- Key
log.format- Type
- json | text
- Default
json
json is one object per line, for log collectors. text is for reading in a terminal.
- Key
console.enabled- Type
- boolean
- Default
true
false removes the Console (the built-in page with the problems list and the replay viewer) from this engine.
- Key
mcp.enabled- Type
- boolean
- Default
true
false removes the MCP server at <base URL>/mcp.
- Key
mcp.read_only- Type
- boolean
- Default
false
true removes the one MCP tool that writes, resolve_problem, for every connection.
- Key
api.cors_origins- Type
- list of origins
- Default
- none
Origins of your own web apps that may call the read API from a browser. Empty allows none; the Console is on the engine’s own origin and needs nothing. Ingest has its own rule, per project (allowed_origins).
Database
One Postgres, version 15 or later. It holds the numbers, the session index, problems and configuration. Raw events never go into it.
A piece you choose
Database
Holds the aggregates, the session index, problems and configuration.
- Default deployment
- A Postgres URL you provide, or the one the template creates.
- Sypnia Cloud uses
- Postgres.
- Key
database.url- Type
- URL (secret)
- Default
- none
- Required
- yes
The connection string, postgres://user:password@host:5432/database. Add ?sslmode=require when the database is not on the same machine. The user must be able to create tables in its schema; sypnia migrate does the rest.
Example: SYPNIA_DATABASE_URL=postgres://sypnia:<password>@db.internal:5432/sypnia?sslmode=require
- Key
database.max_connections- Type
- integer
- Default
10
The most connections one process keeps open. With several processes, or functions, the total is this number times how many run at once. When the database refuses a connection the API answers 503 with Retry-After.
Object storage
One bucket in any S3-compatible store. It holds the raw events, replay chunks, page snapshots and source maps. Every key starts with the project’s id.
A piece you choose
Object storage
Holds raw events, replay chunks, page snapshots and source maps.
- Default deployment
- The bucket the template creates.
- Sypnia Cloud uses
- Amazon S3.
- Key
storage.bucket- Type
- string
- Default
- none
- Required
- yes
The bucket’s name. Keep it private; the engine hands out short-lived links when something must be read from outside.
- Key
storage.region- Type
- string
- Default
us-east-1
The bucket’s region. auto for Cloudflare R2.
- Key
storage.endpoint- Type
- URL
- Default
- none
The address of the store’s S3 API. Empty means Amazon S3. Set it for any other store.
Example: SYPNIA_STORAGE_ENDPOINT=https://<account id>.r2.cloudflarestorage.com
- Key
storage.public_endpoint- Type
- URL
- Default
the value of storage.endpoint
The address that browsers and your CI use to reach the store, when it differs from the one the engine uses. Replay links and source-map upload links are signed for this address. You need it when the store is on a private network, such as MinIO in Docker.
- Key
storage.access_key_id- Type
- string (secret)
- Default
- none
The access key. Empty uses the credentials of the environment (an AWS role, or the standard AWS_… variables).
- Key
storage.secret_access_key- Type
- string (secret)
- Default
- none
The secret of the access key.
- Key
storage.path_style- Type
- boolean
- Default
false
true puts the bucket in the path (https://host/bucket/key) instead of the host name. MinIO needs it.
- Key
storage.prefix- Type
- string
- Default
- none
A prefix for every key, to share a bucket with something else. No slash at the start; one at the end.
Example: SYPNIA_STORAGE_PREFIX=sypnia/
- Key
storage.presign_ttl_seconds- Type
- integer
- Default
900
How long a link to a replay chunk, a page snapshot or a source-map upload works, in seconds. 60 to 3600.
Processing and retention
How fast the worker turns what arrives into problems, sessions and numbers, and how long data is kept. The engine deletes expired data itself, once a day; you do not need lifecycle rules on the bucket.
- Key
processing.interval_seconds- Type
- integer
- Default
30
How often the worker looks for new data, in seconds. 10 to 60. A new problem appears within 2 minutes of its first event with the default; a longer interval breaks that promise.
- Key
processing.concurrency- Type
- integer
- Default
2
How many projects one worker processes at the same time. Each one holds at most 256 MB while it works.
- Key
retention.events_days- Type
- integer
- Default
90
Days that raw events, sessions with their timelines and traces are kept. 1 to 3650.
- Key
retention.replays_days- Type
- integer
- Default
30
Days that replay recordings are kept. Not more than retention.events_days.
- Key
retention.snapshots_days- Type
- integer
- Default
90
Days that page snapshots are kept.
- Key
retention.numbers_days- Type
- integer
- Default
400
Days that hourly and daily numbers are kept (performance, usage, click maps, uptime). They are small. Problems, with their sentence, status and daily counts, are kept for as long as the project exists.
- Key
retention.sourcemaps_days- Type
- integer
- Default
90
Days that a release’s source maps are kept after the release was last seen.
Quotas and rate limits
A self-hosted engine has no limits set by us. These settings let you set your own, to protect your storage and your bill. 0 always means no limit.
- Key
quota.events_per_month- Type
- integer
- Default
0
The most counted events (errors, traces, performance samples) a project may store in a calendar month, in UTC. When a project reaches it, its SDKs are told to send only failures until the month ends, and an alert is created at 80 % and at 100 %.
- Key
quota.replays_per_month- Type
- integer
- Default
0
The most sessions with a recording a project may store in a calendar month. When a project reaches it, its SDKs stop recording until the month ends.
- Key
quota.uptime_checks- Type
- integer
- Default
50
The most uptime checks a project may have.
- Key
rate_limit.api_per_minute- Type
- integer
- Default
600
Requests a minute one API token may make. Counted per process, so with several processes the real limit is higher.
- Key
rate_limit.ingest_per_minute- Type
- integer
- Default
600
The limit a new ingest key gets, in requests a minute from one address. Each key can be given its own with the API or sypnia key create --rate-limit.
Recording defaults
What a new project starts with. Each project’s own settings are changed with the API (PATCH /v1/projects/{project_ref}), and reach browsers with their next session.
- Key
replay.enabled- Type
- boolean
- Default
true
false switches session replay off for the whole engine: no project can record, and the ingest refuses replay chunks and page snapshots.
- Key
replay.sample_rate- Type
- number
- Default
0.1
For new projects, the share of sessions recorded from their first moment, 0 to 1. Whatever the share, a session with an error, a rage click or a dead click is recorded from 30 seconds before it.
- Key
snapshots.sample_rate- Type
- number
- Default
0.5
For new projects, the share of sessions that take page snapshots, 0 to 1. Click maps are drawn over them.
Uptime checks
The worker makes the checks, from wherever it runs.
- Key
uptime.enabled- Type
- boolean
- Default
true
false stops every uptime check of the engine.
- Key
uptime.allow_private_addresses- Type
- boolean
- Default
false
true lets checks reach private and loopback addresses, to watch services inside your own network. Leave it false when people you do not fully trust hold admin tokens.
Alert delivery
The engine records every alert and shows it in the API, the MCP server, the CLI and the Console. It has no e-mail sender. To get an alert to a person, point a webhook at something of yours that sends it.
A piece you choose
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.
- Sypnia Cloud uses
- E-mail through Amazon SES, and alerts inside the app.
- Key
alerts.webhook_url- Type
- URL
- Default
- none
A URL that receives every alert of every project, as an alert.created webhook event. Empty sends nothing; alerts are still recorded. For one project, or other event types, register webhooks with the API instead.
Example: SYPNIA_ALERT_WEBHOOK_URL=https://ops.example.com/hooks/sypnia
- Key
alerts.webhook_secret- Type
- string (secret)
- Default
- none
The secret that signs deliveries to alerts.webhook_url, so your receiver can check they come from your engine. Deliveries are not signed when it is empty, and sypnia doctor warns.
- Key
webhooks.allow_http- Type
- boolean
- Default
false
true lets webhooks use http:// and private addresses, for a receiver inside your own network.
- Key
webhooks.timeout_seconds- Type
- integer
- Default
10
How long the engine waits for a receiver to answer before it counts the delivery as failed and retries. 1 to 30.
AI provider
The agent needs a model. The engine ships with none, so the agent is off until you set a provider, and nothing is ever sent to one before that. Each way to connect it, with an example and how to check it, is on the page «Models and what is sent».
A piece you choose
AI provider
Runs the model behind the agent’s analysis and the ready prompt.
- Default deployment
- Off until you set a key.
- Sypnia Cloud uses
- OpenRouter.
- Key
ai.provider- Type
- none | openrouter | openai | anthropic | google | openai-compatible
- Default
none
Which way the engine reaches a model. none switches the agent off: problems keep their technical title, the prompt carries the evidence without a cause, and weekly suggestions come only from fixed rules.
- Key
ai.api_key- Type
- string (secret)
- Default
- none
The key of the provider. Required for every provider except none, and except an openai-compatible endpoint that needs no key.
- Key
ai.model- Type
- string
- Default
- none
The model to use, written as your provider names it. Required when a provider is set: the engine has no default model, on purpose. Any model your provider offers that can follow instructions and return JSON works; a small, fast one is enough for most problems.
Example: SYPNIA_AI_MODEL=<model>
- Key
ai.base_url- Type
- URL
- Default
the provider's own address
The address of the provider’s API. Required for openai-compatible. For the others it defaults to the provider’s own: https://openrouter.ai/api/v1, https://api.openai.com/v1, https://api.anthropic.com, https://generativelanguage.googleapis.com/v1beta/openai. Set it to go through a proxy of yours.
Example: SYPNIA_AI_BASE_URL=http://localhost:11434/v1
- Key
ai.max_analyses_per_day- Type
- integer
- Default
100
The most analyses one project may run in a day, in UTC. It is your guard against a bad day costing money: when it is reached, new problems get analysis.status limit_reached and are analysed the next day if still open. 0 means no limit.
- Key
ai.max_analyses_per_problem_per_day- Type
- integer
- Default
3
The most times one problem is analysed in a day, however fast it grows.
- Key
ai.timeout_seconds- Type
- integer
- Default
60
How long the engine waits for the model. A call that fails or times out is tried again twice, then the analysis is failed until the problem grows. Raise it for a slow local model.
- Key
ai.max_output_tokens- Type
- integer
- Default
2000
The most tokens the model may write for one analysis.
- Key
ai.send_source- Type
- boolean
- Default
true
false keeps your source code out of what is sent to the provider: no source lines around stack frames and no diffs of the release. The analysis still gets file names, line numbers and function names, and is less sure of the cause.
- Key
ai.language- Type
- string
- Default
en
For new projects, the language the agent writes in, as a BCP 47 tag (en, es). Each project can change its own with the API.
- Key
ai.weekly_suggestions- Type
- boolean
- Default
true
false keeps the weekly suggestions to the fixed rules and makes no model call for them.
Pull requests
The engine does not open pull requests and has no setting for it.
A piece you choose
Pull requests
Opens the pull request with the fix.
- Default deployment
- Not in the engine.
- Sypnia Cloud uses
- The Sypnia GitHub App.
What the engine never sends
A self-hosted engine talks to four places and no others: your database, your bucket, the AI provider you configured (never before you configure one), and the webhooks you registered. It does not report usage, versions or errors to Sypnia, and it does not check for updates.