Docs

Inicio rápido: alojamiento propio

Corre el motor de código abierto de Sypnia en tu propia máquina con Docker, crea un proyecto y mira tu primera sesión y tu primer problema.

Aplica a Motor Al lanzar

Ver como Markdown
En esta página
  1. Escribe el archivo de Compose
  2. Arráncalo
  3. Revisa la instalación
  4. Crea un proyecto y un token
  5. Agrega el SDK a tu app
  6. Abre tu app y comprueba que envía
  7. Causa tu primer problema, y míralo
  8. Lo que tienes, y lo que no
  9. Sigue con esto

Motor Esta página es para quien quiere correr Sypnia por su cuenta. Arranca el motor de código abierto en tu propia máquina con Docker, junto a su base de datos y su almacenamiento, para que pruebes todo antes de elegir dónde va a vivir. Si prefieres no correr servidores, usa el inicio rápido de Sypnia Cloud; el fragmento en tu app es el mismo.

Al final tendrás: el motor corriendo en http://localhost:8080, un proyecto con sus llaves, tu app enviándole datos, y tu primera sesión y tu primer problema en la Consola.

Necesitas: Docker con Compose, una app web que puedas editar y correr en la misma máquina, y unos quince minutos.

  1. Escribe el archivo de Compose

    En una carpeta vacía, crea este archivo. Arranca tres cosas: el motor, un Postgres para los números, y MinIO como bucket compatible con S3 para los eventos crudos y las grabaciones.

    compose.yaml
    services:
      sypnia:
        image: ghcr.io/sypnia/sypnia:1
        ports: ["8080:8080"]
        environment:
          SYPNIA_BASE_URL: http://localhost:8080
          SYPNIA_ROOT_TOKEN: change-me-to-a-long-random-string
          SYPNIA_AUTO_MIGRATE: "true"
          SYPNIA_DATABASE_URL: postgres://sypnia:sypnia@db:5432/sypnia
          SYPNIA_STORAGE_BUCKET: sypnia
          SYPNIA_STORAGE_ENDPOINT: http://minio:9000
          SYPNIA_STORAGE_PUBLIC_ENDPOINT: http://localhost:9000
          SYPNIA_STORAGE_PATH_STYLE: "true"
          SYPNIA_STORAGE_ACCESS_KEY_ID: sypnia
          SYPNIA_STORAGE_SECRET_ACCESS_KEY: sypnia-secret
        depends_on:
          db: { condition: service_healthy }
          bucket: { condition: service_completed_successfully }
    
      db:
        image: postgres:16
        environment:
          POSTGRES_USER: sypnia
          POSTGRES_PASSWORD: sypnia
          POSTGRES_DB: sypnia
        volumes: ["db:/var/lib/postgresql/data"]
        healthcheck:
          test: ["CMD-SHELL", "pg_isready -U sypnia"]
          interval: 2s
          retries: 30
    
      minio:
        image: minio/minio
        command: server /data
        ports: ["9000:9000"]
        environment:
          MINIO_ROOT_USER: sypnia
          MINIO_ROOT_PASSWORD: sypnia-secret
        volumes: ["bucket:/data"]
    
      bucket:
        image: minio/mc
        depends_on: [minio]
        entrypoint: >
          sh -c "until mc alias set local http://minio:9000 sypnia sypnia-secret; do sleep 1; done;
                 mc mb --ignore-existing local/sypnia"
    
    volumes:
      db:
      bucket:

    Cada línea SYPNIA_… es un ajuste del motor, explicado en la referencia de configuración. El motor no necesita nada más: ni cola, ni caché, ni servidor de búsqueda.

  2. Arráncalo

    Terminal
    docker compose up -d
    curl -i http://localhost:8080/healthz
    Deberías ver
    HTTP/1.1 200 OK. El primer arranque tarda hasta un minuto mientras bajan las imágenes y el motor crea sus tablas.
  3. Revisa la instalación

    Terminal
    docker compose exec sypnia sypnia doctor --skip ai
    Deberías ver
    Text
    config    ok    10 settings read, 0 unknown
    database  ok    postgres 16.4, schema 12 (up to date), 2 ms
    storage   ok    s3://sypnia: put, get, delete, presign
    address   ok    http://localhost:8080/healthz answered 200
    webhook   skip  SYPNIA_ALERT_WEBHOOK_URL is not set (alerts are recorded only)
    clock     ok    0.1 s from the database's clock
    all checks passed

    Una línea que dice FAIL nombra el ajuste que hay que cambiar. El chequeo de IA se omite porque todavía no hay una llave de modelo: el motor funciona sin ella, y los problemas conservan entonces su título técnico. Cómo conectar un modelo está en Modelos y qué se envía.

  4. Crea un proyecto y un token

    Terminal
    docker compose exec sypnia 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

    La llave de ingesta va en tu app. Para leer lo que llega necesitas un token de API:

    Terminal
    docker compose exec sypnia 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. Es un secreto.
  5. Agrega el SDK a tu app

    npm

    npm install @sypnia/browser
    import { init } from '@sypnia/browser';
    
    init({ project: 'YOUR_PROJECT_KEY' });

    Pon la llamada a init donde arranca tu app, antes de que pinte. Usa tu propia llave de ingesta, y apunta el SDK a tu motor con endpoint:

    src/main.ts
    import { init } from '@sypnia/browser';
    
    init({
      project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e',
      endpoint: 'http://localhost:8080',
      environment: location.hostname === 'localhost' ? 'development' : 'production',
    });

    Con la etiqueta script, cárgala desde tu motor: src="http://localhost:8080/v1/sdk.js" y data-endpoint="http://localhost:8080".

    endpoint es la única diferencia con Sypnia Cloud. El SDK es el mismo paquete.

  6. Abre tu app y comprueba que envía

    Corre tu app, ábrela en un navegador y haz clic en varias cosas. Abre las herramientas de desarrollo, pestaña Network, y escribe ingest en el filtro.

    Deberías ver
    En menos de 10 segundos, un POST a http://localhost:8080/v1/ingest/events con estado 200 y una respuesta como {"accepted": 5, "dropped": 0}.
  7. Causa tu primer problema, y míralo

    Agrega una línea después de init, guarda y recarga tu app una vez. Luego quítala.

    src/main.ts
    import { init, reportError } from '@sypnia/browser';
    
    // después de init({ … })
    reportError(new Error('Sypnia test: the cart total is missing'));

    Abre la Consola en http://localhost:8080/console, pega tu token de API y elige el entorno development.

    Deberías ver
    En menos de 2 minutos, un problema: Error: Sypnia test: the cart total is missing, 1 persona, 1 ocurrencia. En menos de 10 minutos, tu sesión, con las páginas que abriste y en qué hiciste clic. Cuando la sesión lleve 2 minutos inactiva, su grabación se reproduce en la Consola: el error inició la grabación.

    Lo mismo desde la línea de comandos:

    Terminal
    docker compose exec -e SYPNIA_API_TOKEN=<tu token sps_> sypnia sypnia problems --environment development

Lo que tienes, y lo que no

El motor de Sypnia y Sypnia Cloud, comparados
Motor de SypniaCódigo abierto, en tu propia infraestructuraSypnia CloudServicio pago, con un plan gratis
Recibir, guardar, agrupar en problemas, sesiones, grabacionesCorriendo en tu máquina.El mismo motor, que corremos nosotros.
Dónde lo leesLa Consola (problemas y grabaciones), la API, el CLI y el servidor MCP.La app completa.
La frase en palabras simples y el promptDespués de que pones tu propia llave de modelo.Incluidos.
AlertasSe registran, y se envían a un webhook si pones uno. Sin correo en el despliegue por defecto.Correo y dentro de la app.
Pull requestsNo están en el motor. Usa el prompt o MCP con tu propio agente de código.Los abre la GitHub App de Sypnia.

La comparación completa está en Código abierto y Sypnia Cloud.

Sigue con esto

Para tenerHaz
Un despliegue al que otros puedan llegar, con HTTPSDesplegar con Docker o Desplegar en AWS
La frase en palabras simplesPon una llave de modelo: Modelos y qué se envía
Un correo cuando algo se rompeCorreos de alerta desde un motor con alojamiento propio
Tu agente de código leyendo los problemasInstalar con tu agente de código
El ciclo completo una vez, con un clic de rabia y una grabaciónTu primer problema
Los nombres de tus archivos en las pilasSource maps en CI

Para detener la prueba: docker compose down. Agrega -v para borrar también sus datos.

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