Referencia de configuración
Cada ajuste del motor de Sypnia: su variable de entorno, su tipo, su valor por defecto y qué cambia, con las opciones de cada pieza que tú eliges.
En esta página
- Cómo se leen los ajustes
- Las piezas que tú eliges
- Base
- 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
- Base de datos
- SYPNIA_DATABASE_URL
- SYPNIA_DATABASE_MAX_CONNECTIONS
- Almacenamiento de objetos
- 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
- Procesamiento y retención
- 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
- Cuotas y límites de peticiones
- 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
- Valores iniciales de grabación
- SYPNIA_REPLAY_ENABLED
- SYPNIA_REPLAY_SAMPLE_RATE
- SYPNIA_SNAPSHOTS_SAMPLE_RATE
- Comprobaciones de disponibilidad
- SYPNIA_UPTIME_ENABLED
- SYPNIA_UPTIME_ALLOW_PRIVATE_ADDRESSES
- Entrega de alertas
- SYPNIA_ALERT_WEBHOOK_URL
- SYPNIA_ALERT_WEBHOOK_SECRET
- SYPNIA_WEBHOOKS_ALLOW_HTTP
- SYPNIA_WEBHOOKS_TIMEOUT_SECONDS
- Proveedor de IA
- 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
- Lo que el motor nunca envía
Motor Esta página lista cada ajuste de un motor alojado por ti. Sypnia Cloud la corremos nosotros: ahí, ninguno de estos lo defines tú.
La configuración más pequeña que arranca son cinco ajustes: la dirección del motor, el token raíz, la base de datos y el bucket. Todo lo demás tiene un valor por defecto.
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-1Después corre sypnia migrate, sypnia doctor y sypnia serve. La lista de ajustes legible por máquinas es spec/config.yaml, en el repositorio de la documentación.
Cómo se leen los ajustes
Cada ajuste tiene una variable de entorno (SYPNIA_…) y una clave para un archivo de configuración en TOML, que se pasa con --config o SYPNIA_CONFIG. La clave ai.provider se escribe así en el archivo:
[ai]
provider = "openrouter"
model = "<model>"Cuando están los dos, gana el entorno.
- Los booleanos son
trueofalse. Las listas van separadas por comas en el entorno y como arreglos en el archivo. - Un ajuste marcado como obligatorio detiene el motor al arrancar, con código de salida 3 y un mensaje que lo nombra, cuando falta.
- Una variable
SYPNIA_…desconocida es una advertencia ensypnia doctor, no un error, así un error de escritura se encuentra y un ajuste viejo no detiene una actualización. - Los secretos (el token raíz, las llaves del almacenamiento, la llave de IA, el secreto del webhook) nunca se imprimen, ni se registran, ni los devuelve la API.
- Los ajustes se leen al arrancar. Cambia uno y reinicia el motor.
Las piezas que tú eliges
El despliegue por defecto trae solo lo que no se puede dejar por fuera. Todo lo que depende de un proveedor lo eliges tú. Cada pieza se configura en su sección, abajo.
Almacenamiento de objetos
Guarda los eventos crudos, los fragmentos de grabación, las capturas de página y los source maps.
- Despliegue por defecto
- El bucket que crea la plantilla.
- Alternativas que explica la documentación
- Cualquier almacenamiento compatible con S3: Amazon S3, Cloudflare R2, MinIO.
- Sypnia Cloud usa
- Amazon S3.
Base de datos
Guarda los agregados, el índice de sesiones, los problemas y la configuración.
- Despliegue por defecto
- Una URL de Postgres que das tú, o la que crea la plantilla.
- Alternativas que explica la documentación
- Amazon RDS, Supabase, Neon o tu propio servidor.
- Sypnia Cloud usa
- Postgres.
Entrega de alertas
Lleva una alerta del motor a una persona.
- Despliegue por defecto
- Ninguna. Las alertas quedan registradas, y se envían a un webhook si configuras uno.
- Alternativas que explica la documentación
- Recetas: correo con Amazon SES, correo con cualquier servidor SMTP, o tu propia función sobre el webhook.
- Sypnia Cloud usa
- Correo con Amazon SES, y alertas dentro de la app.
Proveedor de IA
Corre el modelo detrás del análisis del agente y del prompt listo.
- Despliegue por defecto
- Apagado hasta que pongas una llave.
- Alternativas que explica la documentación
- OpenRouter, la API de OpenAI, la API de Anthropic, Google Gemini, o cualquier endpoint compatible con OpenAI, alojado o local.
- Sypnia Cloud usa
- OpenRouter.
Pull requests
Abre el pull request con el arreglo.
- Despliegue por defecto
- No está en el motor.
- Alternativas que explica la documentación
- Usa el prompt o el servidor MCP con tu propio agente de código.
- Sypnia Cloud usa
- La Sypnia GitHub App.
Base
Lo que el motor necesita para arrancar y para saber su propia dirección.
- Clave
base_url- Tipo
- URL
- Por defecto
- ninguno
- Obligatorio
- sí
La dirección pública del motor, tal como llegan a ella los navegadores y tu CI, con https:// y sin barra al final. Los SDK envían a ella, los enlaces de las alertas y de los prompts empiezan con ella, y la Consola está en <URL base>/console.
Ejemplo: SYPNIA_BASE_URL=https://sypnia.example.com
- Clave
root_token- Tipo
- string (secret)
- Por defecto
- ninguno
- Obligatorio
- sí
El token raíz. Puede hacer todo en todos los proyectos, y con él creas el primer proyecto y los primeros tokens. Mínimo 32 caracteres; genéralo con openssl rand -hex 32. Para cambiarlo, define un valor nuevo y reinicia; el anterior deja de funcionar de inmediato.
- Clave
listen- Tipo
- address
- Por defecto
0.0.0.0:8080
La dirección y el puerto donde escucha sypnia serve. Ponle delante un proxy inverso o un balanceador con TLS.
- Clave
role- Tipo
- all | ingest | api | worker
- Por defecto
all
Qué parte del motor corre este proceso. all es el motor completo en un proceso (Docker). La plantilla de AWS corre una función por rol. Mira sypnia serve.
- Clave
auto_migrate- Tipo
- boolean
- Por defecto
false
true hace que sypnia serve aplique las migraciones pendientes de la base de datos al arrancar. Déjalo en false cuando más de un proceso arranca al mismo tiempo, y corre sypnia migrate como un paso del despliegue.
- Clave
trusted_proxy_hops- Tipo
- integer
- Por defecto
0
Cuántos proxies inversos tienes delante del motor. El motor toma la dirección de quien llama de esa cantidad de pasos hacia atrás en X-Forwarded-For, para los límites de peticiones. 0 usa la dirección de la conexión. Un número equivocado deja que alguien finja su dirección, o hace que todos compartan un mismo límite.
- Clave
log.level- Tipo
- error | warn | info | debug
- Por defecto
info
Cuánto registra el motor en la salida estándar. debug registra una línea por petición; nunca registra cuerpos, llaves ni tokens.
- Clave
log.format- Tipo
- json | text
- Por defecto
json
json es un objeto por línea, para recolectores de registros. text es para leer en una terminal.
- Clave
console.enabled- Tipo
- boolean
- Por defecto
true
false quita la Consola (la página incluida con la lista de problemas y el visor de grabaciones) de este motor.
- Clave
mcp.enabled- Tipo
- boolean
- Por defecto
true
false quita el servidor MCP de <URL base>/mcp.
- Clave
mcp.read_only- Tipo
- boolean
- Por defecto
false
true quita la única herramienta MCP que escribe, resolve_problem, en todas las conexiones.
- Clave
api.cors_origins- Tipo
- list of origins
- Por defecto
- ninguno
Orígenes de tus propias apps web que pueden llamar a la API de lectura desde un navegador. Vacío no permite ninguno; la Consola está en el mismo origen del motor y no necesita nada. La ingesta tiene su propia regla, por proyecto (allowed_origins).
Base de datos
Un Postgres, versión 15 o posterior. Guarda los números, el índice de sesiones, los problemas y la configuración. Los eventos crudos nunca entran en él.
Una pieza que eliges tú
Base de datos
Guarda los agregados, el índice de sesiones, los problemas y la configuración.
- Despliegue por defecto
- Una URL de Postgres que das tú, o la que crea la plantilla.
- Sypnia Cloud usa
- Postgres.
- Clave
database.url- Tipo
- URL (secret)
- Por defecto
- ninguno
- Obligatorio
- sí
La cadena de conexión, postgres://user:password@host:5432/database. Agrega ?sslmode=require cuando la base de datos no está en la misma máquina. El usuario debe poder crear tablas en su esquema; sypnia migrate hace el resto.
Ejemplo: SYPNIA_DATABASE_URL=postgres://sypnia:<password>@db.internal:5432/sypnia?sslmode=require
- Clave
database.max_connections- Tipo
- integer
- Por defecto
10
El máximo de conexiones que un proceso mantiene abiertas. Con varios procesos, o funciones, el total es este número por cuántos corren a la vez. Cuando la base de datos rechaza una conexión, la API responde 503 con Retry-After.
Almacenamiento de objetos
Un bucket en cualquier almacenamiento compatible con S3. Guarda los eventos crudos, los trozos de grabación, las capturas de página y los source maps. Cada clave empieza con el id del proyecto.
Una pieza que eliges tú
Almacenamiento de objetos
Guarda los eventos crudos, los fragmentos de grabación, las capturas de página y los source maps.
- Despliegue por defecto
- El bucket que crea la plantilla.
- Sypnia Cloud usa
- Amazon S3.
- Clave
storage.bucket- Tipo
- string
- Por defecto
- ninguno
- Obligatorio
- sí
El nombre del bucket. Mantenlo privado; el motor entrega enlaces de corta duración cuando algo se debe leer desde afuera.
- Clave
storage.region- Tipo
- string
- Por defecto
us-east-1
La región del bucket. auto para Cloudflare R2.
- Clave
storage.endpoint- Tipo
- URL
- Por defecto
- ninguno
La dirección de la API S3 del almacenamiento. Vacío significa Amazon S3. Defínelo para cualquier otro.
Ejemplo: SYPNIA_STORAGE_ENDPOINT=https://<account id>.r2.cloudflarestorage.com
- Clave
storage.public_endpoint- Tipo
- URL
- Por defecto
the value of storage.endpoint
La dirección con la que los navegadores y tu CI llegan al almacenamiento, cuando es distinta de la que usa el motor. Los enlaces de grabaciones y de subida de source maps se firman para esta dirección. Lo necesitas cuando el almacenamiento está en una red privada, como MinIO en Docker.
- Clave
storage.access_key_id- Tipo
- string (secret)
- Por defecto
- ninguno
La llave de acceso. Vacío usa las credenciales del entorno (un rol de AWS, o las variables estándar AWS_…).
- Clave
storage.secret_access_key- Tipo
- string (secret)
- Por defecto
- ninguno
El secreto de la llave de acceso.
- Clave
storage.path_style- Tipo
- boolean
- Por defecto
false
true pone el bucket en la ruta (https://host/bucket/key) y no en el nombre del host. MinIO lo necesita.
- Clave
storage.prefix- Tipo
- string
- Por defecto
- ninguno
Un prefijo para todas las claves, para compartir un bucket con otra cosa. Sin barra al comienzo; con una al final.
Ejemplo: SYPNIA_STORAGE_PREFIX=sypnia/
- Clave
storage.presign_ttl_seconds- Tipo
- integer
- Por defecto
900
Cuánto dura un enlace a un trozo de grabación, a una captura de página o a una subida de source maps, en segundos. De 60 a 3600.
Procesamiento y retención
Qué tan rápido convierte el trabajador lo que llega en problemas, sesiones y números, y cuánto tiempo se guardan los datos. El motor borra los datos vencidos por su cuenta, una vez al día; no necesitas reglas de ciclo de vida en el bucket.
- Clave
processing.interval_seconds- Tipo
- integer
- Por defecto
30
Cada cuánto busca datos nuevos el trabajador, en segundos. De 10 a 60. Con el valor por defecto, un problema nuevo aparece a menos de 2 minutos de su primer evento; un intervalo más largo rompe esa promesa.
- Clave
processing.concurrency- Tipo
- integer
- Por defecto
2
Cuántos proyectos procesa un trabajador al mismo tiempo. Cada uno ocupa como máximo 256 MB mientras trabaja.
- Clave
retention.events_days- Tipo
- integer
- Por defecto
90
Días que se guardan los eventos crudos, las sesiones con sus líneas de tiempo y las trazas. De 1 a 3650.
- Clave
retention.replays_days- Tipo
- integer
- Por defecto
30
Días que se guardan las grabaciones. No más que retention.events_days.
- Clave
retention.snapshots_days- Tipo
- integer
- Por defecto
90
Días que se guardan las capturas de página.
- Clave
retention.numbers_days- Tipo
- integer
- Por defecto
400
Días que se guardan los números por hora y por día (rendimiento, uso, mapas de clics, disponibilidad). Son pequeños. Los problemas, con su frase, su estado y sus conteos diarios, se guardan mientras exista el proyecto.
- Clave
retention.sourcemaps_days- Tipo
- integer
- Por defecto
90
Días que se guardan los source maps de una versión después de la última vez que se vio la versión.
Cuotas y límites de peticiones
Un motor alojado por ti no tiene límites puestos por nosotros. Estos ajustes te dejan poner los tuyos, para cuidar tu almacenamiento y tu cuenta. 0 siempre significa sin límite.
- Clave
quota.events_per_month- Tipo
- integer
- Por defecto
0
El máximo de eventos contados (errores, trazas, muestras de rendimiento) que un proyecto puede guardar en un mes calendario, en UTC. Cuando un proyecto llega, a sus SDK se les dice que envíen solo fallas hasta que termine el mes, y se crea una alerta al 80 % y al 100 %.
- Clave
quota.replays_per_month- Tipo
- integer
- Por defecto
0
El máximo de sesiones con grabación que un proyecto puede guardar en un mes calendario. Cuando un proyecto llega, sus SDK dejan de grabar hasta que termine el mes.
- Clave
quota.uptime_checks- Tipo
- integer
- Por defecto
50
El máximo de comprobaciones de disponibilidad que puede tener un proyecto.
- Clave
rate_limit.api_per_minute- Tipo
- integer
- Por defecto
600
Peticiones por minuto que puede hacer un token de API. Se cuentan por proceso, así que con varios procesos el límite real es más alto.
- Clave
rate_limit.ingest_per_minute- Tipo
- integer
- Por defecto
600
El límite que recibe una llave de ingesta nueva, en peticiones por minuto desde una misma dirección. A cada llave se le puede dar el suyo con la API o con sypnia key create --rate-limit.
Valores iniciales de grabación
Con qué empieza un proyecto nuevo. Los ajustes de cada proyecto se cambian con la API (PATCH /v1/projects/{project_ref}) y llegan a los navegadores con su siguiente sesión.
- Clave
replay.enabled- Tipo
- boolean
- Por defecto
true
false apaga la grabación de sesiones en todo el motor: ningún proyecto puede grabar, y la ingesta rechaza trozos de grabación y capturas de página.
- Clave
replay.sample_rate- Tipo
- number
- Por defecto
0.1
Para proyectos nuevos, la parte de las sesiones que se graba desde su primer momento, de 0 a 1. Sea cual sea, una sesión con un error, un clic de rabia o un clic muerto se graba desde 30 segundos antes.
- Clave
snapshots.sample_rate- Tipo
- number
- Por defecto
0.5
Para proyectos nuevos, la parte de las sesiones que toma capturas de página, de 0 a 1. Sobre ellas se dibujan los mapas de clics.
Comprobaciones de disponibilidad
El trabajador hace las comprobaciones, desde donde corra.
- Clave
uptime.enabled- Tipo
- boolean
- Por defecto
true
false detiene todas las comprobaciones de disponibilidad del motor.
- Clave
uptime.allow_private_addresses- Tipo
- boolean
- Por defecto
false
true deja que las comprobaciones lleguen a direcciones privadas y locales, para vigilar servicios dentro de tu propia red. Déjalo en false cuando personas en las que no confías del todo tienen tokens admin.
Entrega de alertas
El motor registra cada alerta y la muestra en la API, el servidor MCP, la CLI y la Consola. No tiene cómo enviar correos. Para que una alerta le llegue a una persona, apunta un webhook a algo tuyo que la envíe.
Una pieza que eliges tú
Entrega de alertas
Lleva una alerta del motor a una persona.
- Despliegue por defecto
- Ninguna. Las alertas quedan registradas, y se envían a un webhook si configuras uno.
- Sypnia Cloud usa
- Correo con Amazon SES, y alertas dentro de la app.
- Clave
alerts.webhook_url- Tipo
- URL
- Por defecto
- ninguno
Una URL que recibe cada alerta de cada proyecto, como un evento de webhook alert.created. Vacío no envía nada; las alertas igual se registran. Para un solo proyecto, u otros tipos de eventos, registra webhooks con la API.
Ejemplo: SYPNIA_ALERT_WEBHOOK_URL=https://ops.example.com/hooks/sypnia
- Clave
alerts.webhook_secret- Tipo
- string (secret)
- Por defecto
- ninguno
El secreto que firma las entregas a alerts.webhook_url, para que tu receptor compruebe que vienen de tu motor. Cuando está vacío las entregas no van firmadas, y sypnia doctor avisa.
- Clave
webhooks.allow_http- Tipo
- boolean
- Por defecto
false
true deja que los webhooks usen http:// y direcciones privadas, para un receptor dentro de tu propia red.
- Clave
webhooks.timeout_seconds- Tipo
- integer
- Por defecto
10
Cuánto espera el motor la respuesta de un receptor antes de contar la entrega como fallida y reintentar. De 1 a 30.
Proveedor de IA
El agente necesita un modelo. El motor no trae ninguno, así que el agente está apagado hasta que definas un proveedor, y antes de eso nunca se envía nada a ninguno. Cada forma de conectarlo, con un ejemplo y cómo comprobarlo, está en la página «Modelos y qué se envía».
Una pieza que eliges tú
Proveedor de IA
Corre el modelo detrás del análisis del agente y del prompt listo.
- Despliegue por defecto
- Apagado hasta que pongas una llave.
- Sypnia Cloud usa
- OpenRouter.
- Clave
ai.provider- Tipo
- none | openrouter | openai | anthropic | google | openai-compatible
- Por defecto
none
Por dónde llega el motor a un modelo. none apaga el agente: los problemas conservan su título técnico, el prompt lleva la evidencia sin causa, y las sugerencias semanales salen solo de reglas fijas.
- Clave
ai.api_key- Tipo
- string (secret)
- Por defecto
- ninguno
La llave del proveedor. Obligatoria para todos los proveedores salvo none, y salvo un endpoint openai-compatible que no pida llave.
- Clave
ai.model- Tipo
- string
- Por defecto
- ninguno
El modelo que se usa, escrito como lo nombra tu proveedor. Obligatorio cuando hay proveedor: el motor no tiene modelo por defecto, a propósito. Sirve cualquier modelo de tu proveedor que siga instrucciones y devuelva JSON; uno pequeño y rápido basta para la mayoría de los problemas.
Ejemplo: SYPNIA_AI_MODEL=<model>
- Clave
ai.base_url- Tipo
- URL
- Por defecto
the provider's own address
La dirección de la API del proveedor. Obligatoria para openai-compatible. Para los demás toma la del proveedor: https://openrouter.ai/api/v1, https://api.openai.com/v1, https://api.anthropic.com, https://generativelanguage.googleapis.com/v1beta/openai. Defínela para pasar por un proxy tuyo.
Ejemplo: SYPNIA_AI_BASE_URL=http://localhost:11434/v1
- Clave
ai.max_analyses_per_day- Tipo
- integer
- Por defecto
100
El máximo de análisis que un proyecto puede correr en un día, en UTC. Es tu protección para que un mal día no cueste dinero: cuando se llega, los problemas nuevos quedan con analysis.status en limit_reached y se analizan al día siguiente si siguen abiertos. 0 significa sin límite.
- Clave
ai.max_analyses_per_problem_per_day- Tipo
- integer
- Por defecto
3
El máximo de veces que se analiza un mismo problema en un día, por rápido que crezca.
- Clave
ai.timeout_seconds- Tipo
- integer
- Por defecto
60
Cuánto espera el motor al modelo. Una llamada que falla o se vence se intenta dos veces más; después el análisis queda en failed hasta que el problema crezca. Súbelo para un modelo local lento.
- Clave
ai.max_output_tokens- Tipo
- integer
- Por defecto
2000
El máximo de tokens que el modelo puede escribir en un análisis.
- Clave
ai.send_source- Tipo
- boolean
- Por defecto
true
false deja tu código fuera de lo que se envía al proveedor: sin líneas de código alrededor de los marcos de la pila y sin diffs de la versión. El análisis igual recibe nombres de archivos, números de línea y nombres de funciones, y queda menos seguro de la causa.
- Clave
ai.language- Tipo
- string
- Por defecto
en
Para proyectos nuevos, el idioma en el que escribe el agente, como etiqueta BCP 47 (en, es). Cada proyecto puede cambiar el suyo con la API.
- Clave
ai.weekly_suggestions- Tipo
- boolean
- Por defecto
true
false deja las sugerencias semanales solo con las reglas fijas y no hace ninguna llamada a un modelo para ellas.
Pull requests
El motor no abre pull requests y no tiene ningún ajuste para eso.
Una pieza que eliges tú
Pull requests
Abre el pull request con el arreglo.
- Despliegue por defecto
- No está en el motor.
- Sypnia Cloud usa
- La Sypnia GitHub App.
Lo que el motor nunca envía
Un motor alojado por ti habla con cuatro lugares y ningún otro: tu base de datos, tu bucket, el proveedor de IA que configuraste (nunca antes de que configures uno) y los webhooks que registraste. No le reporta uso, versiones ni errores a Sypnia, y no busca actualizaciones.