# Configuration reference

> Every setting of the Sypnia engine: its environment variable, type, default and what it changes, with the choices for each pluggable piece.

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

For agents: Every SYPNIA_ environment variable of the self-hosted engine with type, default and meaning: base URL, root token, database, S3-compatible storage, retention, quotas, rate limits, recording defaults, uptime, alert webhook, AI provider.

**\[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.

`.env`

```bash
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-1
```

Then 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:

`sypnia.toml`

```toml
[ai]
provider = "openrouter"
model = "<model>"
```

When both are set, the environment wins.

- Booleans are `true` or `false`. 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 in `sypnia 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.

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

## Core

What the engine needs to start and to know its own address.

### `SYPNIA_BASE_URL`

- **Key:** `base_url`
- **Type:** URL
- **Default:** none
- **Required:** yes
- \[Engine]

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`

### `SYPNIA_ROOT_TOKEN`

- **Key:** `root_token`
- **Type:** string (secret)
- **Default:** none
- **Required:** yes
- \[Engine]

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.

### `SYPNIA_LISTEN`

- **Key:** `listen`
- **Type:** address
- **Default:** `0.0.0.0:8080`
- \[Engine]

The address and port `sypnia serve` listens on. Put a reverse proxy or a load balancer with TLS in front of it.

### `SYPNIA_ROLE`

- **Key:** `role`
- **Type:** all | ingest | api | worker
- **Default:** `all`
- \[Engine]

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

### `SYPNIA_AUTO_MIGRATE`

- **Key:** `auto_migrate`
- **Type:** boolean
- **Default:** `false`
- \[Engine]

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

### `SYPNIA_TRUSTED_PROXY_HOPS`

- **Key:** `trusted_proxy_hops`
- **Type:** integer
- **Default:** `0`
- \[Engine]

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.

### `SYPNIA_LOG_LEVEL`

- **Key:** `log.level`
- **Type:** error | warn | info | debug
- **Default:** `info`
- \[Engine]

How much the engine logs to standard output. `debug` logs one line per request; it never logs bodies, keys or tokens.

### `SYPNIA_LOG_FORMAT`

- **Key:** `log.format`
- **Type:** json | text
- **Default:** `json`
- \[Engine]

`json` is one object per line, for log collectors. `text` is for reading in a terminal.

### `SYPNIA_CONSOLE_ENABLED`

- **Key:** `console.enabled`
- **Type:** boolean
- **Default:** `true`
- \[Engine]

`false` removes the Console (the built-in page with the problems list and the replay viewer) from this engine.

### `SYPNIA_MCP_ENABLED`

- **Key:** `mcp.enabled`
- **Type:** boolean
- **Default:** `true`
- \[Engine]

`false` removes the MCP server at `<base URL>/mcp`.

### `SYPNIA_MCP_READ_ONLY`

- **Key:** `mcp.read_only`
- **Type:** boolean
- **Default:** `false`
- \[Engine]

`true` removes the one MCP tool that writes, `resolve_problem`, for every connection.

### `SYPNIA_API_CORS_ORIGINS`

- **Key:** `api.cors_origins`
- **Type:** list of origins
- **Default:** none
- \[Engine]

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.

**Your options:**

- [Amazon RDS](/self-hosting/deploy-aws): The AWS template can create it, or take the URL of one you have.
- [Supabase](/self-hosting/deploy-docker): Use the session-mode connection string (port 5432). The engine keeps a few connections open and runs transactions of several statements.
- [Neon](/self-hosting/deploy-docker): Use the direct connection string, not the pooled one.
- [Your own server](/self-hosting/deploy-docker): The Docker Compose file starts a Postgres next to the engine.

### `SYPNIA_DATABASE_URL`

- **Key:** `database.url`
- **Type:** URL (secret)
- **Default:** none
- **Required:** yes
- \[Engine]

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`

### `SYPNIA_DATABASE_MAX_CONNECTIONS`

- **Key:** `database.max_connections`
- **Type:** integer
- **Default:** `10`
- \[Engine]

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.

**Your options:**

- [Amazon S3](/self-hosting/deploy-aws): Set the bucket and the region. On AWS leave the keys empty: the engine uses the role of the machine or function.
- [Cloudflare R2](/self-hosting/deploy-docker): Set the endpoint to `https://<account id>.r2.cloudflarestorage.com`, the region to `auto`, and an access key pair.
- [MinIO](/self-hosting/deploy-docker): Set the endpoint, `path_style` to `true`, and `public_endpoint` to the address browsers can reach.

### `SYPNIA_STORAGE_BUCKET`

- **Key:** `storage.bucket`
- **Type:** string
- **Default:** none
- **Required:** yes
- \[Engine]

The bucket's name. Keep it private; the engine hands out short-lived links when something must be read from outside.

### `SYPNIA_STORAGE_REGION`

- **Key:** `storage.region`
- **Type:** string
- **Default:** `us-east-1`
- \[Engine]

The bucket's region. `auto` for Cloudflare R2.

### `SYPNIA_STORAGE_ENDPOINT`

- **Key:** `storage.endpoint`
- **Type:** URL
- **Default:** none
- \[Engine]

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`

### `SYPNIA_STORAGE_PUBLIC_ENDPOINT`

- **Key:** `storage.public_endpoint`
- **Type:** URL
- **Default:** `the value of storage.endpoint`
- \[Engine]

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.

### `SYPNIA_STORAGE_ACCESS_KEY_ID`

- **Key:** `storage.access_key_id`
- **Type:** string (secret)
- **Default:** none
- \[Engine]

The access key. Empty uses the credentials of the environment (an AWS role, or the standard `AWS_…` variables).

### `SYPNIA_STORAGE_SECRET_ACCESS_KEY`

- **Key:** `storage.secret_access_key`
- **Type:** string (secret)
- **Default:** none
- \[Engine]

The secret of the access key.

### `SYPNIA_STORAGE_PATH_STYLE`

- **Key:** `storage.path_style`
- **Type:** boolean
- **Default:** `false`
- \[Engine]

`true` puts the bucket in the path (`https://host/bucket/key`) instead of the host name. MinIO needs it.

### `SYPNIA_STORAGE_PREFIX`

- **Key:** `storage.prefix`
- **Type:** string
- **Default:** none
- \[Engine]

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/`

### `SYPNIA_STORAGE_PRESIGN_TTL_SECONDS`

- **Key:** `storage.presign_ttl_seconds`
- **Type:** integer
- **Default:** `900`
- \[Engine]

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.

### `SYPNIA_PROCESSING_INTERVAL_SECONDS`

- **Key:** `processing.interval_seconds`
- **Type:** integer
- **Default:** `30`
- \[Engine]

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.

### `SYPNIA_PROCESSING_CONCURRENCY`

- **Key:** `processing.concurrency`
- **Type:** integer
- **Default:** `2`
- \[Engine]

How many projects one worker processes at the same time. Each one holds at most 256 MB while it works.

### `SYPNIA_RETENTION_EVENTS_DAYS`

- **Key:** `retention.events_days`
- **Type:** integer
- **Default:** `90`
- \[Engine]

Days that raw events, sessions with their timelines and traces are kept. 1 to 3650.

### `SYPNIA_RETENTION_REPLAYS_DAYS`

- **Key:** `retention.replays_days`
- **Type:** integer
- **Default:** `30`
- \[Engine]

Days that replay recordings are kept. Not more than `retention.events_days`.

### `SYPNIA_RETENTION_SNAPSHOTS_DAYS`

- **Key:** `retention.snapshots_days`
- **Type:** integer
- **Default:** `90`
- \[Engine]

Days that page snapshots are kept.

### `SYPNIA_RETENTION_NUMBERS_DAYS`

- **Key:** `retention.numbers_days`
- **Type:** integer
- **Default:** `400`
- \[Engine]

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.

### `SYPNIA_RETENTION_SOURCEMAPS_DAYS`

- **Key:** `retention.sourcemaps_days`
- **Type:** integer
- **Default:** `90`
- \[Engine]

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.

### `SYPNIA_QUOTA_EVENTS_PER_MONTH`

- **Key:** `quota.events_per_month`
- **Type:** integer
- **Default:** `0`
- \[Engine]

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

### `SYPNIA_QUOTA_REPLAYS_PER_MONTH`

- **Key:** `quota.replays_per_month`
- **Type:** integer
- **Default:** `0`
- \[Engine]

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.

### `SYPNIA_QUOTA_UPTIME_CHECKS`

- **Key:** `quota.uptime_checks`
- **Type:** integer
- **Default:** `50`
- \[Engine]

The most uptime checks a project may have.

### `SYPNIA_RATE_LIMIT_API_PER_MINUTE`

- **Key:** `rate_limit.api_per_minute`
- **Type:** integer
- **Default:** `600`
- \[Engine]

Requests a minute one API token may make. Counted per process, so with several processes the real limit is higher.

### `SYPNIA_RATE_LIMIT_INGEST_PER_MINUTE`

- **Key:** `rate_limit.ingest_per_minute`
- **Type:** integer
- **Default:** `600`
- \[Engine]

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.

### `SYPNIA_REPLAY_ENABLED`

- **Key:** `replay.enabled`
- **Type:** boolean
- **Default:** `true`
- \[Engine]

`false` switches session replay off for the whole engine: no project can record, and the ingest refuses replay chunks and page snapshots.

### `SYPNIA_REPLAY_SAMPLE_RATE`

- **Key:** `replay.sample_rate`
- **Type:** number
- **Default:** `0.1`
- \[Engine]

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.

### `SYPNIA_SNAPSHOTS_SAMPLE_RATE`

- **Key:** `snapshots.sample_rate`
- **Type:** number
- **Default:** `0.5`
- \[Engine]

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.

### `SYPNIA_UPTIME_ENABLED`

- **Key:** `uptime.enabled`
- **Type:** boolean
- **Default:** `true`
- \[Engine]

`false` stops every uptime check of the engine.

### `SYPNIA_UPTIME_ALLOW_PRIVATE_ADDRESSES`

- **Key:** `uptime.allow_private_addresses`
- **Type:** boolean
- **Default:** `false`
- \[Engine]

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

**Your options:**

- [A webhook of your own](/api/webhooks): Set `SYPNIA_ALERT_WEBHOOK_URL` for the whole engine, or register webhooks per project with the API.
- [E-mail with Amazon SES](/guides/alert-emails-self-hosted): A small function on the webhook that sends the alert through SES.
- [E-mail with any SMTP server](/guides/alert-emails-self-hosted): The same function, sending through SMTP.

### `SYPNIA_ALERT_WEBHOOK_URL`

- **Key:** `alerts.webhook_url`
- **Type:** URL
- **Default:** none
- \[Engine]

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`

### `SYPNIA_ALERT_WEBHOOK_SECRET`

- **Key:** `alerts.webhook_secret`
- **Type:** string (secret)
- **Default:** none
- \[Engine]

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.

### `SYPNIA_WEBHOOKS_ALLOW_HTTP`

- **Key:** `webhooks.allow_http`
- **Type:** boolean
- **Default:** `false`
- \[Engine]

`true` lets webhooks use `http://` and private addresses, for a receiver inside your own network.

### `SYPNIA_WEBHOOKS_TIMEOUT_SECONDS`

- **Key:** `webhooks.timeout_seconds`
- **Type:** integer
- **Default:** `10`
- \[Engine]

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.

**Your options:**

- [OpenRouter](/agent/models-and-what-is-sent): One key, many models. What Sypnia Cloud uses.
- [The OpenAI API](/agent/models-and-what-is-sent): Your OpenAI key and one of its models.
- [The Anthropic (Claude) API](/agent/models-and-what-is-sent): Your Anthropic key and one of its models.
- [Google Gemini](/agent/models-and-what-is-sent): Your Gemini API key and one of its models.
- [Any OpenAI-compatible endpoint](/agent/models-and-what-is-sent): A local model or another gateway. Nothing leaves your network.

### `SYPNIA_AI_PROVIDER`

- **Key:** `ai.provider`
- **Type:** none | openrouter | openai | anthropic | google | openai-compatible
- **Default:** `none`
- \[Engine]

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.

### `SYPNIA_AI_API_KEY`

- **Key:** `ai.api_key`
- **Type:** string (secret)
- **Default:** none
- \[Engine]

The key of the provider. Required for every provider except `none`, and except an `openai-compatible` endpoint that needs no key.

### `SYPNIA_AI_MODEL`

- **Key:** `ai.model`
- **Type:** string
- **Default:** none
- \[Engine]

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>`

### `SYPNIA_AI_BASE_URL`

- **Key:** `ai.base_url`
- **Type:** URL
- **Default:** `the provider's own address`
- \[Engine]

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`

### `SYPNIA_AI_MAX_ANALYSES_PER_DAY`

- **Key:** `ai.max_analyses_per_day`
- **Type:** integer
- **Default:** `100`
- \[Engine]

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.

### `SYPNIA_AI_MAX_ANALYSES_PER_PROBLEM_PER_DAY`

- **Key:** `ai.max_analyses_per_problem_per_day`
- **Type:** integer
- **Default:** `3`
- \[Engine]

The most times one problem is analysed in a day, however fast it grows.

### `SYPNIA_AI_TIMEOUT_SECONDS`

- **Key:** `ai.timeout_seconds`
- **Type:** integer
- **Default:** `60`
- \[Engine]

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.

### `SYPNIA_AI_MAX_OUTPUT_TOKENS`

- **Key:** `ai.max_output_tokens`
- **Type:** integer
- **Default:** `2000`
- \[Engine]

The most tokens the model may write for one analysis.

### `SYPNIA_AI_SEND_SOURCE`

- **Key:** `ai.send_source`
- **Type:** boolean
- **Default:** `true`
- \[Engine]

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

### `SYPNIA_AI_LANGUAGE`

- **Key:** `ai.language`
- **Type:** string
- **Default:** `en`
- \[Engine]

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.

### `SYPNIA_AI_WEEKLY_SUGGESTIONS`

- **Key:** `ai.weekly_suggestions`
- **Type:** boolean
- **Default:** `true`
- \[Engine]

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

**Your options:**

- [The ready prompt](/agent/the-prompt): Copy it from the Console, the API or `sypnia problem --prompt` into your coding agent.
- [The MCP server](/mcp/connect): Connect your coding agent once and ask it to fix a problem.

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