Docs

Desplegar en AWS

Despliega el motor de Sypnia en tu propia cuenta de AWS con una sola plantilla de CloudFormation, compruébalo, crea el primer proyecto, apúntale un dominio, actualízalo y elimínalo.

Aplica a Motor Al lanzar

Ver como Markdown
En esta página
  1. Qué crea la plantilla
  2. Parámetros
  3. Desplegar
  4. Instala el comando sypnia en tu máquina
  5. Elige la región y crea el token raíz
  6. Descarga la plantilla
  7. Despliega el stack
  8. Carga la configuración del motor en tu terminal
  9. Crea las tablas
  10. Comprueba el despliegue
  11. Crea el primer proyecto y un token
  12. Envía desde tu app y mira cómo llega
  13. Apuntarle un dominio
  14. Pide un certificado en us-east-1
  15. Demuestra que el dominio es tuyo
  16. Dale el dominio al stack
  17. Apunta el registro DNS al stack
  18. Comprueba
  19. Cambiar un ajuste
  20. Actualizar el motor
  21. Lee qué cambió
  22. Actualiza el comando y la plantilla
  23. Actualiza primero las tablas
  24. Despliega la plantilla nueva
  25. Comprueba la versión que responde
  26. Eliminar todo
  27. Anota los nombres y elimina el stack
  28. Elimina el bucket y todo lo que contiene
  29. Elimina la instantánea final de la base de datos
  30. Quita lo que creaste a mano
  31. Cuando algo falla
  32. Sigue con esto

Motor Esta página es para quien despliega el motor de código abierto en su propia cuenta de AWS. No aplica a Sypnia Cloud, que es esta misma forma corrida por nosotros. Si no usas AWS, sigue Desplegar con Docker.

Al final tendrás: el motor respondiendo en una dirección HTTPS de tu cuenta de AWS, su bucket y su base de datos, un primer proyecto con una llave de ingesta y un token de API, y sypnia doctor en verde.

Necesitas: una cuenta de AWS y la AWS CLI versión 2, con una sesión que pueda crear funciones, roles, un bucket, una cola y una distribución de CloudFront; jq y openssl; unos 30 minutos, la mitad de espera.

Qué crea la plantilla

Una sola plantilla de CloudFormation, sypnia-aws.yaml, crea todo en un stack. El mismo binario sypnia corre como tres funciones; cada una es el motor con un rol.

Diagrama por dibujarEl mismo diagrama de arquitectura que la figura 1 de la página en inglés (self-hosting/deploy-aws), con los mismos nodos, flechas, llamadas numeradas 1 a 7 y el mismo elemento encendido (el camino Dirección → ingest → Cola → worker). Los nombres de funciones, rutas y servicios no se traducen. Rótulos traducidos: marco «Tu cuenta de AWS · stack: sypnia»; fuera del marco «Tu app (SDK)» y «Tú · tu agente de código · tu CI»; nodo 1 «Dirección · CloudFront · https://sypnia.example.com»; flecha inferior «todo lo demás: /v1/*, /mcp, /console»; nodo 2 «Función: ingest»; nodo 3 «Función: api»; nodo 4 «Cola (entrada)» con la flecha «lotes de eventos»; flecha fina al bucket «fragmentos de grabación, capturas de página»; flecha de la cola al worker «lo despierta, hasta 10 s de lotes»; reloj «Programación · cada minuto»; nodo 5 «Función: worker»; nodo 6 «Bucket (S3)» con la flecha «segmentos, archivos por sesión, Parquet»; nodo 7 «Postgres (RDS, o el tuyo)» con la flecha «problemas, números, sesiones» y la etiqueta «opcional: lo crea la plantilla o lo traes tú»; flechas punteadas que salen del marco: «tu webhook» y «tu proveedor de IA (apagado hasta que pongas una llave)».
Figura. El stack que crea la plantilla. Las tres funciones son el mismo binario con tres roles.
#RecursoQué haceValor por defecto de la plantilla
1Una distribución de CloudFrontLa única dirección HTTPS del motor. Envía /v1/ingest/*, /v1/otlp/* y /v1/sdk.js a la función de ingesta y todo lo demás a la función de la API. Acepta tu propio dominio si le das uno.Sin caché, salvo /v1/sdk.js
2Función sypnia-ingestSYPNIA_ROLE=ingest. Revisa cada lote y lo pone en la cola; escribe los fragmentos de grabación y las capturas de página en el bucket.256 MB, 10 s, máximo 40 copias a la vez
3Función sypnia-apiSYPNIA_ROLE=api. La API, el servidor MCP y la Consola.512 MB, 30 s, máximo 20 copias
4Una cola, y una segunda para los mensajes que fallaron cinco vecesGuarda los lotes hasta 4 días, hasta que el worker los escribe. Es el búfer que una función no puede mantener en memoria.Cola estándar
5Función sypnia-worker, y una programación que la despierta cada minutoSYPNIA_ROLE=worker. Escribe segmentos, encuentra problemas, cuenta, corre las comprobaciones de disponibilidad, el agente, las alertas, los webhooks y la retención. La despierta la cola, y la programación cuando no hay tráfico.1.024 MB, 15 min, máximo 2 copias
6Un bucket de S3Eventos crudos, grabaciones, capturas, source maps. Privado, cifrado, con el acceso público bloqueado, una regla que deja a tu dirección leer grabaciones desde un navegador, y una regla de ciclo de vida que borra las subidas sin terminar a los 7 días.Se conserva cuando se elimina el stack
7Un Postgres en RDS, solo si lo pidesLa base de datos. Postgres 16, 20 GB, cifrado, respaldos diarios guardados 7 días, con la contraseña generada y guardada en Secrets Manager.db.t4g.micro; se toma una instantánea final cuando se elimina el stack
Roles, y un grupo de logs por funciónCada función solo puede tocar el bucket y la cola de este stack: ingest puede enviar a la cola y escribir objetos, api puede leer objetos y firmar enlaces, worker puede leer y escribir en el bucket. Los logs se guardan 30 días.
Dos alarmasUna cuando un mensaje cae en la segunda cola, otra cuando el worker sigue fallando. Se ven en CloudWatch; apúntalas a una notificación tuya si quieres que te avisen.

No operas la cola ni la programación: la plantilla las crea y AWS las corre. Por qué las funciones necesitan una cola, qué despierta a cada función y qué cambia en los tiempos, está en Formas de despliegue y Flujo de datos.

Parámetros

ParámetroPor defectoQué configura
RootTokenObligatorioEl token raíz, SYPNIA_ROOT_TOKEN. Al menos 32 caracteres.
CreateDatabasetruetrue crea el Postgres en RDS. false usa DatabaseUrl.
DatabaseUrlVacíoTu propio Postgres, como SYPNIA_DATABASE_URL. Obligatorio cuando CreateDatabase es false. Termínalo con ?sslmode=require.
DatabaseInstanceClassdb.t4g.microEl tamaño de la base de datos que crea la plantilla.
DomainNameVacíoTu propio dominio para el motor, como sypnia.example.com. Vacío usa la dirección que CloudFront le da al stack.
CertificateArnVacíoEl certificado de DomainName, de AWS Certificate Manager en us-east-1. Obligatorio con DomainName.
AiProvider, AiApiKey, AiModelnone, vacío, vacíoSYPNIA_AI_PROVIDER, SYPNIA_AI_API_KEY, SYPNIA_AI_MODEL. El agente está apagado mientras el proveedor sea none.
AlertWebhookUrl, AlertWebhookSecretVacíoSYPNIA_ALERT_WEBHOOK_URL, SYPNIA_ALERT_WEBHOOK_SECRET. Vacío no envía nada; las alertas igual quedan registradas.
VersionLa versión de la propia plantillaQué versión del motor corren las funciones.
CodeBucketsypnia-releases-<region>El bucket del que se lee el paquete de las funciones. Cámbialo solo si tu región no tiene uno (ver Cuando algo falla).

La plantilla configura por su cuenta estos ajustes, y no deberías cambiarlos: SYPNIA_BASE_URL, SYPNIA_ROLE, SYPNIA_STORAGE_BUCKET, SYPNIA_STORAGE_REGION, SYPNIA_TRUSTED_PROXY_HOPS y SYPNIA_DATABASE_MAX_CONNECTIONS. Cualquier otro ajuste de la referencia de configuración queda en su valor por defecto hasta que lo cambies.

Desplegar

  1. Instala el comando sypnia en tu máquina

    Lo vas a usar para crear las tablas, comprobar el despliegue y crear el primer proyecto.

    Terminal
    curl -fsSL https://sypnia.com/install.sh | sh
    sypnia version
    Deberías ver
    Text
    sypnia 1.0.0 (a1c9e3f, 2026-03-01) schema 12
  2. Elige la región y crea el token raíz

    Terminal
    export AWS_REGION=us-east-1
    openssl rand -hex 32 > sypnia-root-token.txt
    chmod 600 sypnia-root-token.txt
    Deberías ver
    Un archivo con 64 caracteres. Guárdalo en un lugar seguro, como tu gestor de contraseñas: puede hacer todo en todos los proyectos.
  3. Descarga la plantilla

    Terminal
    curl -fsSLO https://github.com/sypnia/sypnia/releases/latest/download/sypnia-aws.yaml
    Deberías ver
    Un archivo llamado sypnia-aws.yaml en la carpeta actual. Léelo si quieres saber exactamente qué se va a crear: es el despliegue completo.
  4. Despliega el stack

    Con una base de datos creada por la plantilla:

    Terminal
    aws cloudformation deploy \
      --template-file sypnia-aws.yaml \
      --stack-name sypnia \
      --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND \
      --parameter-overrides \
        RootToken="$(cat sypnia-root-token.txt)" \
        CreateDatabase=true

    Con tu propio Postgres, reemplaza la última línea por estas dos:

    Terminal
        CreateDatabase=false \
        DatabaseUrl='postgres://sypnia:<password>@<host>:5432/sypnia?sslmode=require'
    Deberías ver
    Text
    Waiting for changeset to be created..
    Waiting for stack create/update to complete
    Successfully created/updated stack - sypnia

    Unos 15 minutos cuando la plantilla crea la base de datos, unos 5 cuando traes la tuya. La base de datos y la dirección de CloudFront son lo que más tarda.

  5. Carga la configuración del motor en tu terminal

    Las funciones guardan la configuración del motor como variables de entorno. Léelas del worker, para que los comandos que corras después usen exactamente la misma base de datos y el mismo bucket.

    Terminal
    eval "$(aws lambda get-function-configuration --function-name sypnia-worker \
      --query 'Environment.Variables' --output json \
      | jq -r 'to_entries[] | select(.key | startswith("SYPNIA_")) | "export \(.key)=\(.value | @sh)"')"
    echo "$SYPNIA_BASE_URL"
    Deberías ver
    La dirección de tu motor, como https://d2k4x7example.cloudfront.net. Tu terminal ahora guarda secretos, entre ellos el token raíz: ciérrala cuando termines.
  6. Crea las tablas

    Terminal
    sypnia migrate
    Deberías ver
    Una lista de migraciones aplicadas que termina en database is up to date. Hasta que corras esto, las funciones se niegan a arrancar y la dirección responde con un error.
  7. Comprueba el despliegue

    Terminal
    curl -i "$SYPNIA_BASE_URL/healthz"
    sypnia doctor --skip ai
    Deberías ver

    HTTP/2 200 del primer comando. Del segundo:

    Text
    config    ok    12 settings read, 0 unknown
    database  ok    postgres 16.4, schema 12 (up to date), 41 ms
    storage   ok    s3://sypnia-bucket-1a2b3c4d5e6f: put, get, delete, presign
    address   ok    https://d2k4x7example.cloudfront.net/healthz answered 200
    webhook   skip  SYPNIA_ALERT_WEBHOOK_URL is not set (alerts are recorded only)
    clock     ok    0.3 s from the database's clock
    all checks passed

    sypnia doctor corre en tu máquina con tu propia sesión de AWS. Prueba la configuración, la base de datos y el bucket. Que las funciones mismas llegan a ellos lo prueban healthz y los dos pasos siguientes.

  8. Crea el primer proyecto y un token

    Terminal
    sypnia project create --name Shop
    Deberías ver
    Text
    project     shop (prj_5k2m9x4q7w1z)
    ingest key  spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e
    
    Put the ingest key in your app. It is public: it can only send.
    Next: sypnia token create --project shop --name "My laptop" --scopes read,replay
    Terminal
    sypnia token create --project shop --name "My laptop" --scopes read,replay
    Deberías ver
    Una línea que empieza por sps_. Se muestra una sola vez: cópiala ahora.
  9. Envía desde tu app y mira cómo llega

    Apunta el SDK a tu motor con endpoint, como en el inicio rápido: init({ project: 'spk_…', endpoint: '<tu URL base>' }). Abre tu app, haz clic por ahí, y luego:

    Terminal
    SYPNIA_API_TOKEN=<tu token sps_> sypnia problems --environment development
    Deberías ver
    En menos de 2 minutos desde un primer error, un problema. Las sesiones y los números llegan en menos de 10 minutos. La Consola está en <tu URL base>/console.

Antes de recibir tráfico real, apunta tu dominio al motor, para que la dirección en tu app sea la definitiva, y recorre la lista de seguridad.

Apuntarle un dominio

Al final tendrás: el motor en https://sypnia.example.com. Hazlo antes de publicar el SDK en tu app. La dirección de CloudFront sigue funcionando después, así que nada de lo que ya le envía se rompe.

  1. Pide un certificado en us-east-1

    CloudFront solo acepta certificados de us-east-1, sea cual sea la región de tu stack.

    Terminal
    aws acm request-certificate --region us-east-1 \
      --domain-name sypnia.example.com --validation-method DNS \
      --query CertificateArn --output text
    Deberías ver
    Una dirección que empieza por arn:aws:acm:us-east-1:. Guárdala para los pasos siguientes.
  2. Demuestra que el dominio es tuyo

    Terminal
    aws acm describe-certificate --region us-east-1 --certificate-arn <el ARN> \
      --query "Certificate.DomainValidationOptions[0].ResourceRecord"

    Crea en tu proveedor de DNS el registro CNAME que imprime, y espera:

    Terminal
    aws acm wait certificate-validated --region us-east-1 --certificate-arn <el ARN>
    Deberías ver
    El comando termina sin mensaje, normalmente a los pocos minutos de existir el registro.
  3. Dale el dominio al stack

    Los parámetros que no nombras conservan su valor.

    Terminal
    aws cloudformation deploy \
      --template-file sypnia-aws.yaml \
      --stack-name sypnia \
      --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND \
      --parameter-overrides DomainName=sypnia.example.com CertificateArn=<el ARN>
    Deberías ver
    Successfully created/updated stack - sypnia, después de unos 5 minutos.
  4. Apunta el registro DNS al stack

    Terminal
    aws cloudformation describe-stacks --stack-name sypnia \
      --query "Stacks[0].Outputs[?OutputKey=='DistributionDomain'].OutputValue" --output text

    Crea un registro CNAME de sypnia.example.com hacia el nombre que imprime. Para un dominio sin subdominio, usa el registro de alias de tu proveedor de DNS.

  5. Comprueba

    Terminal
    curl -i https://sypnia.example.com/healthz
    Deberías ver
    HTTP/2 200. SYPNIA_BASE_URL ahora es https://sypnia.example.com: los enlaces de las alertas y de los prompts la usan, y la Consola también. Vuelve a cargar la configuración en tu terminal antes del siguiente comando sypnia.

Cambiar un ajuste

La configuración se lee cuando una función arranca, y un despliegue reinicia las funciones.

  • Un ajuste que tiene parámetro: despliega otra vez con el valor nuevo. Por ejemplo, para conectar un modelo:

    Terminal
    aws cloudformation deploy \
      --template-file sypnia-aws.yaml --stack-name sypnia \
      --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND \
      --parameter-overrides AiProvider=openrouter AiApiKey=<tu llave> AiModel=<model>

    Luego vuelve a cargar la configuración y corre sypnia doctor --only ai.

  • Cualquier otro ajuste: las tres funciones comparten una lista de variables de entorno cerca del inicio de la plantilla, bajo Globals. Agrega ahí la línea SYPNIA_… del ajuste, conserva el archivo editado y despliégalo. Mantén tus cambios cuando descargues una plantilla más nueva.

Actualizar el motor

Al final tendrás: las tres funciones en la versión nueva, sin detener la ingesta. Las migraciones solo agregan, así que las funciones viejas siguen funcionando contra las tablas nuevas mientras el stack se actualiza.

  1. Lee qué cambió

    El registro de cambios dice qué cambia cada versión y si te pide algo.

  2. Actualiza el comando y la plantilla

    Terminal
    curl -fsSL https://sypnia.com/install.sh | sh
    curl -fsSLO https://github.com/sypnia/sypnia/releases/latest/download/sypnia-aws.yaml
    sypnia version
    Deberías ver
    La versión nueva y el esquema que necesita, como sypnia 1.1.0 (…) schema 13.
  3. Actualiza primero las tablas

    Con la configuración cargada en tu terminal:

    Terminal
    sypnia migrate
    Deberías ver
    database is up to date.
  4. Despliega la plantilla nueva

    Terminal
    aws cloudformation deploy \
      --template-file sypnia-aws.yaml \
      --stack-name sypnia \
      --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND
    Deberías ver
    Successfully created/updated stack - sypnia. Cada parámetro conserva su valor.
  5. Comprueba la versión que responde

    Terminal
    curl -s -o /dev/null -D - "$SYPNIA_BASE_URL/v1/whoami" \
      -H "Authorization: Bearer $SYPNIA_ROOT_TOKEN" | grep -i sypnia-version
    Deberías ver
    sypnia-version: 1.1.0

Para volver atrás, despliega otra vez la plantilla anterior. La base de datos no necesita nada: un motor más viejo funciona contra un esquema más nuevo. Más sobre esto en Actualizaciones, respaldos y retención.

Eliminar todo

Eliminar el stack quita las funciones, la cola, la programación, la dirección, los roles y los logs. A propósito deja tus datos: el bucket se conserva, y la base de datos que creó la plantilla se elimina después de una instantánea final.

  1. Anota los nombres y elimina el stack

    Terminal
    aws cloudformation describe-stacks --stack-name sypnia --query "Stacks[0].Outputs" --output table
    aws cloudformation delete-stack --stack-name sypnia
    aws cloudformation wait stack-delete-complete --stack-name sypnia
    Deberías ver
    La tabla muestra BucketName y, si la plantilla creó la base de datos, DatabaseIdentifier. El último comando termina sin mensaje después de unos 10 minutos.
  2. Elimina el bucket y todo lo que contiene

    Esto no se puede deshacer.

    Terminal
    aws s3 rb s3://<BucketName> --force
    Deberías ver
    Una línea remove_bucket: <BucketName> al final.
  3. Elimina la instantánea final de la base de datos

    Solo si la plantilla creó la base de datos.

    Terminal
    aws rds describe-db-snapshots --db-instance-identifier <DatabaseIdentifier> \
      --query "DBSnapshots[].DBSnapshotIdentifier" --output text
    aws rds delete-db-snapshot --db-snapshot-identifier <el nombre impreso>
  4. Quita lo que creaste a mano

    Los registros DNS, el certificado (aws acm delete-certificate) y el archivo del token raíz.

Después de esto no queda nada de Sypnia en la cuenta y no se cobra nada.

Cuando algo falla

Lo que vesPor quéQué hacer
Requires capabilities : [CAPABILITY_AUTO_EXPAND]La plantilla usa una transformación de CloudFormation.Pasa las dos capacidades, como en los comandos de arriba.
El stack falla en una función con «S3 bucket does not exist» o «Access Denied»El paquete de las funciones no está publicado en tu región.Descarga sypnia-lambda-arm64.zip de la misma versión, súbelo a un bucket tuyo en esa región bajo <Version>/sypnia-lambda-arm64.zip, y despliega con CodeBucket=<tu bucket>.
El stack falla con «The specified SSL certificate doesn’t exist, isn’t in us-east-1 region»El certificado se pidió en otra región.Pídelo otra vez con --region us-east-1.
healthz responde 502 o 503 justo después del primer despliegueLas tablas todavía no existen. El motor se niega a arrancar contra un esquema más viejo que él.Corre sypnia migrate. Para ver el motivo: aws logs tail /aws/lambda/sypnia-api --since 10m.
sypnia doctor dice database FAIL desde tu máquina, con tu propio PostgresTu base de datos no acepta conexiones desde internet. Las funciones están fuera de tu red, igual que tu máquina.Permite la conexión con TLS, o usa una base de datos a la que las funciones lleguen.
sypnia doctor pasa y nunca aparece un problemaEl worker no está corriendo.aws logs tail /aws/lambda/sypnia-worker --since 10m. Una línea que nombra un ajuste faltante, o un error de base de datos, dice qué arreglar.
La API responde 503 con Retry-After bajo cargaLa base de datos no tiene conexiones libres.Ver Escalado y costo.
Los navegadores reciben 403 origin_not_allowedEl proyecto tiene una lista de orígenes permitidos, y el de tu app no está.Agrégalo con PATCH /v1/projects/{project_ref}. Ver la referencia de la API.
Llegan eventos y la Consola no reproduce una grabaciónTu navegador lee la grabación directo del bucket, con un enlace de corta duración. Un proxy o una extensión que bloquea amazonaws.com lo rompe.Prueba con otro perfil del navegador. Ver La Consola.

Sigue con esto

Secciones

Empieza aquíQué es Sypnia, cómo funciona, qué es código abierto y qué es la nube de pago, y las dos maneras de recibir tu primer problema en palabras claras.ConceptosLas diez ideas de las que está hecho Sypnia, cada una definida con precisión, desde un proyecto y sus llaves hasta los problemas, las trazas y las alertas.SDKCómo envía tu app los datos a Sypnia. Un SDK para el navegador, uno para Node, uno para Next.js, y la entrada de OpenTelemetry para cualquier otro backend.El agenteCómo analiza Sypnia un problema, qué escribe, qué le envía a un modelo y qué nunca hace.MCP y skillsConecta tu agente de código a Sypnia para que pregunte qué está fallando en producción, lea lo que necesita para arreglarlo y configure Sypnia por ti.Referencia de la APILa API HTTP de Sypnia: una sola API para el motor de código abierto y para Sypnia Cloud, con cada endpoint, parámetro, respuesta y error.Referencia de la CLIEl comando sypnia: cómo instalarlo, qué variables lee, qué significan sus códigos de salida y dónde está documentado cada comando.Alojamiento propioQué corres cuando alojas tú mismo el motor de Sypnia, qué necesitas, cuánto cuesta y qué no tienes frente a Sypnia Cloud.Cómo está construido el motorTodo el motor de Sypnia en una página, desde un clic en tu app hasta la frase que lee tu agente de código, con las reglas de diseño y el código que las sostiene.Sypnia CloudCómo funciona el servicio pago, desde las organizaciones y los roles hasta los planes, los límites, la facturación, dónde viven tus datos, la GitHub App y el soporte.Privacidad y seguridadQué recoge Sypnia de tu app y de sus usuarios, qué no recoge nunca, cómo funciona el enmascarado, cómo eliminar datos y cómo se protege el servicio.LicenciasQué licencia cubre cada parte de Sypnia, qué puedes hacer con ella, cómo se puede usar el nombre, y los términos de una contribución.GuíasRecetas paso a paso para las formas comunes de usar Sypnia, desde apps hechas con constructores de IA y Next.js en Vercel hasta Supabase, source maps en CI, correos de alerta desde tu propio motor, y venir desde Sentry.ReferenciaLas páginas donde se consulta, desde el esquema de eventos y el glosario hasta lo planeado, el registro de cambios y las preguntas frecuentes.
↑↓ para moverte↵ para abrirEsc para cerrar