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

Aplica a: el motor de Sypnia (código abierto, en tu propia infraestructura). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/self-hosting/configuration/

Para agentes: Cada variable de entorno SYPNIA_ del motor alojado por ti, con tipo, valor por defecto y significado: URL base, token raíz, base de datos, almacenamiento compatible con S3, retención, cuotas, límites de peticiones, valores iniciales de grabación, disponibilidad, webhook de alertas, proveedor de IA.

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

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

Despué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:

`sypnia.toml`

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

Cuando están los dos, gana el entorno.

- Los booleanos son `true` o `false`. 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 en `sypnia 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.

| Pieza                     | Despliegue por defecto                                                                   | Alternativas que explica la documentación                                                                                      | Sypnia Cloud usa                                   |
| ------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
| Almacenamiento de objetos | El bucket que crea la plantilla.                                                         | Cualquier almacenamiento compatible con S3: Amazon S3, Cloudflare R2, MinIO.                                                   | Amazon S3.                                         |
| Base de datos             | Una URL de Postgres que das tú, o la que crea la plantilla.                              | Amazon RDS, Supabase, Neon o tu propio servidor.                                                                               | Postgres.                                          |
| Entrega de alertas        | **Ninguna.** Las alertas quedan registradas, y se envían a un webhook si configuras uno. | Recetas: correo con Amazon SES, correo con cualquier servidor SMTP, o tu propia función sobre el webhook.                      | Correo con Amazon SES, y alertas dentro de la app. |
| Proveedor de IA           | **Apagado** hasta que pongas una llave.                                                  | OpenRouter, la API de OpenAI, la API de Anthropic, Google Gemini, o cualquier endpoint compatible con OpenAI, alojado o local. | OpenRouter.                                        |
| Pull requests             | No está en el motor.                                                                     | Usa el prompt o el servidor MCP con tu propio agente de código.                                                                | La Sypnia GitHub App.                              |

## Base

Lo que el motor necesita para arrancar y para saber su propia dirección.

### `SYPNIA_BASE_URL`

- **Clave:** `base_url`
- **Tipo:** URL
- **Por defecto:** ninguno
- **Obligatorio:** sí
- \[Motor]

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`

### `SYPNIA_ROOT_TOKEN`

- **Clave:** `root_token`
- **Tipo:** string (secret)
- **Por defecto:** ninguno
- **Obligatorio:** sí
- \[Motor]

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.

### `SYPNIA_LISTEN`

- **Clave:** `listen`
- **Tipo:** address
- **Por defecto:** `0.0.0.0:8080`
- \[Motor]

La dirección y el puerto donde escucha `sypnia serve`. Ponle delante un proxy inverso o un balanceador con TLS.

### `SYPNIA_ROLE`

- **Clave:** `role`
- **Tipo:** all | ingest | api | worker
- **Por defecto:** `all`
- \[Motor]

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

### `SYPNIA_AUTO_MIGRATE`

- **Clave:** `auto_migrate`
- **Tipo:** boolean
- **Por defecto:** `false`
- \[Motor]

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

### `SYPNIA_TRUSTED_PROXY_HOPS`

- **Clave:** `trusted_proxy_hops`
- **Tipo:** integer
- **Por defecto:** `0`
- \[Motor]

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.

### `SYPNIA_LOG_LEVEL`

- **Clave:** `log.level`
- **Tipo:** error | warn | info | debug
- **Por defecto:** `info`
- \[Motor]

Cuánto registra el motor en la salida estándar. `debug` registra una línea por petición; nunca registra cuerpos, llaves ni tokens.

### `SYPNIA_LOG_FORMAT`

- **Clave:** `log.format`
- **Tipo:** json | text
- **Por defecto:** `json`
- \[Motor]

`json` es un objeto por línea, para recolectores de registros. `text` es para leer en una terminal.

### `SYPNIA_CONSOLE_ENABLED`

- **Clave:** `console.enabled`
- **Tipo:** boolean
- **Por defecto:** `true`
- \[Motor]

`false` quita la Consola (la página incluida con la lista de problemas y el visor de grabaciones) de este motor.

### `SYPNIA_MCP_ENABLED`

- **Clave:** `mcp.enabled`
- **Tipo:** boolean
- **Por defecto:** `true`
- \[Motor]

`false` quita el servidor MCP de `<URL base>/mcp`.

### `SYPNIA_MCP_READ_ONLY`

- **Clave:** `mcp.read_only`
- **Tipo:** boolean
- **Por defecto:** `false`
- \[Motor]

`true` quita la única herramienta MCP que escribe, `resolve_problem`, en todas las conexiones.

### `SYPNIA_API_CORS_ORIGINS`

- **Clave:** `api.cors_origins`
- **Tipo:** list of origins
- **Por defecto:** ninguno
- \[Motor]

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.

**Tus opciones:**

- [Amazon RDS](/es/self-hosting/deploy-aws): La plantilla de AWS la puede crear, o recibir la URL de una que ya tengas.
- [Supabase](/es/self-hosting/deploy-docker): Usa la cadena de conexión en modo sesión (puerto 5432). El motor mantiene unas pocas conexiones abiertas y corre transacciones de varias sentencias.
- [Neon](/es/self-hosting/deploy-docker): Usa la cadena de conexión directa, no la del pool.
- [Tu propio servidor](/es/self-hosting/deploy-docker): El archivo de Docker Compose arranca un Postgres junto al motor.

### `SYPNIA_DATABASE_URL`

- **Clave:** `database.url`
- **Tipo:** URL (secret)
- **Por defecto:** ninguno
- **Obligatorio:** sí
- \[Motor]

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`

### `SYPNIA_DATABASE_MAX_CONNECTIONS`

- **Clave:** `database.max_connections`
- **Tipo:** integer
- **Por defecto:** `10`
- \[Motor]

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.

**Tus opciones:**

- [Amazon S3](/es/self-hosting/deploy-aws): Define el bucket y la región. En AWS deja las llaves vacías: el motor usa el rol de la máquina o de la función.
- [Cloudflare R2](/es/self-hosting/deploy-docker): Pon el endpoint en `https://<account id>.r2.cloudflarestorage.com`, la región en `auto` y un par de llaves de acceso.
- [MinIO](/es/self-hosting/deploy-docker): Define el endpoint, `path_style` en `true`, y `public_endpoint` con la dirección a la que llegan los navegadores.

### `SYPNIA_STORAGE_BUCKET`

- **Clave:** `storage.bucket`
- **Tipo:** string
- **Por defecto:** ninguno
- **Obligatorio:** sí
- \[Motor]

El nombre del bucket. Mantenlo privado; el motor entrega enlaces de corta duración cuando algo se debe leer desde afuera.

### `SYPNIA_STORAGE_REGION`

- **Clave:** `storage.region`
- **Tipo:** string
- **Por defecto:** `us-east-1`
- \[Motor]

La región del bucket. `auto` para Cloudflare R2.

### `SYPNIA_STORAGE_ENDPOINT`

- **Clave:** `storage.endpoint`
- **Tipo:** URL
- **Por defecto:** ninguno
- \[Motor]

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`

### `SYPNIA_STORAGE_PUBLIC_ENDPOINT`

- **Clave:** `storage.public_endpoint`
- **Tipo:** URL
- **Por defecto:** `the value of storage.endpoint`
- \[Motor]

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.

### `SYPNIA_STORAGE_ACCESS_KEY_ID`

- **Clave:** `storage.access_key_id`
- **Tipo:** string (secret)
- **Por defecto:** ninguno
- \[Motor]

La llave de acceso. Vacío usa las credenciales del entorno (un rol de AWS, o las variables estándar `AWS_…`).

### `SYPNIA_STORAGE_SECRET_ACCESS_KEY`

- **Clave:** `storage.secret_access_key`
- **Tipo:** string (secret)
- **Por defecto:** ninguno
- \[Motor]

El secreto de la llave de acceso.

### `SYPNIA_STORAGE_PATH_STYLE`

- **Clave:** `storage.path_style`
- **Tipo:** boolean
- **Por defecto:** `false`
- \[Motor]

`true` pone el bucket en la ruta (`https://host/bucket/key`) y no en el nombre del host. MinIO lo necesita.

### `SYPNIA_STORAGE_PREFIX`

- **Clave:** `storage.prefix`
- **Tipo:** string
- **Por defecto:** ninguno
- \[Motor]

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

### `SYPNIA_STORAGE_PRESIGN_TTL_SECONDS`

- **Clave:** `storage.presign_ttl_seconds`
- **Tipo:** integer
- **Por defecto:** `900`
- \[Motor]

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.

### `SYPNIA_PROCESSING_INTERVAL_SECONDS`

- **Clave:** `processing.interval_seconds`
- **Tipo:** integer
- **Por defecto:** `30`
- \[Motor]

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.

### `SYPNIA_PROCESSING_CONCURRENCY`

- **Clave:** `processing.concurrency`
- **Tipo:** integer
- **Por defecto:** `2`
- \[Motor]

Cuántos proyectos procesa un trabajador al mismo tiempo. Cada uno ocupa como máximo 256 MB mientras trabaja.

### `SYPNIA_RETENTION_EVENTS_DAYS`

- **Clave:** `retention.events_days`
- **Tipo:** integer
- **Por defecto:** `90`
- \[Motor]

Días que se guardan los eventos crudos, las sesiones con sus líneas de tiempo y las trazas. De 1 a 3650.

### `SYPNIA_RETENTION_REPLAYS_DAYS`

- **Clave:** `retention.replays_days`
- **Tipo:** integer
- **Por defecto:** `30`
- \[Motor]

Días que se guardan las grabaciones. No más que `retention.events_days`.

### `SYPNIA_RETENTION_SNAPSHOTS_DAYS`

- **Clave:** `retention.snapshots_days`
- **Tipo:** integer
- **Por defecto:** `90`
- \[Motor]

Días que se guardan las capturas de página.

### `SYPNIA_RETENTION_NUMBERS_DAYS`

- **Clave:** `retention.numbers_days`
- **Tipo:** integer
- **Por defecto:** `400`
- \[Motor]

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.

### `SYPNIA_RETENTION_SOURCEMAPS_DAYS`

- **Clave:** `retention.sourcemaps_days`
- **Tipo:** integer
- **Por defecto:** `90`
- \[Motor]

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.

### `SYPNIA_QUOTA_EVENTS_PER_MONTH`

- **Clave:** `quota.events_per_month`
- **Tipo:** integer
- **Por defecto:** `0`
- \[Motor]

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

### `SYPNIA_QUOTA_REPLAYS_PER_MONTH`

- **Clave:** `quota.replays_per_month`
- **Tipo:** integer
- **Por defecto:** `0`
- \[Motor]

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.

### `SYPNIA_QUOTA_UPTIME_CHECKS`

- **Clave:** `quota.uptime_checks`
- **Tipo:** integer
- **Por defecto:** `50`
- \[Motor]

El máximo de comprobaciones de disponibilidad que puede tener un proyecto.

### `SYPNIA_RATE_LIMIT_API_PER_MINUTE`

- **Clave:** `rate_limit.api_per_minute`
- **Tipo:** integer
- **Por defecto:** `600`
- \[Motor]

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.

### `SYPNIA_RATE_LIMIT_INGEST_PER_MINUTE`

- **Clave:** `rate_limit.ingest_per_minute`
- **Tipo:** integer
- **Por defecto:** `600`
- \[Motor]

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.

### `SYPNIA_REPLAY_ENABLED`

- **Clave:** `replay.enabled`
- **Tipo:** boolean
- **Por defecto:** `true`
- \[Motor]

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

### `SYPNIA_REPLAY_SAMPLE_RATE`

- **Clave:** `replay.sample_rate`
- **Tipo:** number
- **Por defecto:** `0.1`
- \[Motor]

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.

### `SYPNIA_SNAPSHOTS_SAMPLE_RATE`

- **Clave:** `snapshots.sample_rate`
- **Tipo:** number
- **Por defecto:** `0.5`
- \[Motor]

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.

### `SYPNIA_UPTIME_ENABLED`

- **Clave:** `uptime.enabled`
- **Tipo:** boolean
- **Por defecto:** `true`
- \[Motor]

`false` detiene todas las comprobaciones de disponibilidad del motor.

### `SYPNIA_UPTIME_ALLOW_PRIVATE_ADDRESSES`

- **Clave:** `uptime.allow_private_addresses`
- **Tipo:** boolean
- **Por defecto:** `false`
- \[Motor]

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

**Tus opciones:**

- [Un webhook tuyo](/es/api/webhooks): Define `SYPNIA_ALERT_WEBHOOK_URL` para todo el motor, o registra webhooks por proyecto con la API.
- [Correo con Amazon SES](/es/guides/alert-emails-self-hosted): Una función pequeña en el webhook que envía la alerta por SES.
- [Correo con cualquier servidor SMTP](/es/guides/alert-emails-self-hosted): La misma función, enviando por SMTP.

### `SYPNIA_ALERT_WEBHOOK_URL`

- **Clave:** `alerts.webhook_url`
- **Tipo:** URL
- **Por defecto:** ninguno
- \[Motor]

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`

### `SYPNIA_ALERT_WEBHOOK_SECRET`

- **Clave:** `alerts.webhook_secret`
- **Tipo:** string (secret)
- **Por defecto:** ninguno
- \[Motor]

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.

### `SYPNIA_WEBHOOKS_ALLOW_HTTP`

- **Clave:** `webhooks.allow_http`
- **Tipo:** boolean
- **Por defecto:** `false`
- \[Motor]

`true` deja que los webhooks usen `http://` y direcciones privadas, para un receptor dentro de tu propia red.

### `SYPNIA_WEBHOOKS_TIMEOUT_SECONDS`

- **Clave:** `webhooks.timeout_seconds`
- **Tipo:** integer
- **Por defecto:** `10`
- \[Motor]

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.

**Tus opciones:**

- [OpenRouter](/es/agent/models-and-what-is-sent): Una llave, muchos modelos. Lo que usa Sypnia Cloud.
- [La API de OpenAI](/es/agent/models-and-what-is-sent): Tu llave de OpenAI y uno de sus modelos.
- [La API de Anthropic (Claude)](/es/agent/models-and-what-is-sent): Tu llave de Anthropic y uno de sus modelos.
- [Google Gemini](/es/agent/models-and-what-is-sent): Tu llave de la API de Gemini y uno de sus modelos.
- [Cualquier endpoint compatible con OpenAI](/es/agent/models-and-what-is-sent): Un modelo local u otra pasarela. Nada sale de tu red.

### `SYPNIA_AI_PROVIDER`

- **Clave:** `ai.provider`
- **Tipo:** none | openrouter | openai | anthropic | google | openai-compatible
- **Por defecto:** `none`
- \[Motor]

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.

### `SYPNIA_AI_API_KEY`

- **Clave:** `ai.api_key`
- **Tipo:** string (secret)
- **Por defecto:** ninguno
- \[Motor]

La llave del proveedor. Obligatoria para todos los proveedores salvo `none`, y salvo un endpoint `openai-compatible` que no pida llave.

### `SYPNIA_AI_MODEL`

- **Clave:** `ai.model`
- **Tipo:** string
- **Por defecto:** ninguno
- \[Motor]

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

### `SYPNIA_AI_BASE_URL`

- **Clave:** `ai.base_url`
- **Tipo:** URL
- **Por defecto:** `the provider's own address`
- \[Motor]

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`

### `SYPNIA_AI_MAX_ANALYSES_PER_DAY`

- **Clave:** `ai.max_analyses_per_day`
- **Tipo:** integer
- **Por defecto:** `100`
- \[Motor]

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.

### `SYPNIA_AI_MAX_ANALYSES_PER_PROBLEM_PER_DAY`

- **Clave:** `ai.max_analyses_per_problem_per_day`
- **Tipo:** integer
- **Por defecto:** `3`
- \[Motor]

El máximo de veces que se analiza un mismo problema en un día, por rápido que crezca.

### `SYPNIA_AI_TIMEOUT_SECONDS`

- **Clave:** `ai.timeout_seconds`
- **Tipo:** integer
- **Por defecto:** `60`
- \[Motor]

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.

### `SYPNIA_AI_MAX_OUTPUT_TOKENS`

- **Clave:** `ai.max_output_tokens`
- **Tipo:** integer
- **Por defecto:** `2000`
- \[Motor]

El máximo de tokens que el modelo puede escribir en un análisis.

### `SYPNIA_AI_SEND_SOURCE`

- **Clave:** `ai.send_source`
- **Tipo:** boolean
- **Por defecto:** `true`
- \[Motor]

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

### `SYPNIA_AI_LANGUAGE`

- **Clave:** `ai.language`
- **Tipo:** string
- **Por defecto:** `en`
- \[Motor]

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.

### `SYPNIA_AI_WEEKLY_SUGGESTIONS`

- **Clave:** `ai.weekly_suggestions`
- **Tipo:** boolean
- **Por defecto:** `true`
- \[Motor]

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

**Tus opciones:**

- [El prompt listo](/es/agent/the-prompt): Cópialo de la Consola, de la API o de `sypnia problem --prompt` a tu agente de código.
- [El servidor MCP](/es/mcp/connect): Conecta tu agente de código una vez y pídele que arregle un problema.

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