Cipi Agente

Instalación del agente Cipi

Cipi Agente (cipi/agent en empaquetador) es el acompañante oficial Laravel de Cipi. Une su aplicación y el panel de control del servidor con:

• Implementaciones activadas por Webhook desde GitHub y GitLab
• Monitoreo de salud (aplicación, base de datos, caché, cola, confirmación de implementación)
• Una aplicación MCP servidor para asistentes de IA (Cursor, VS Code, Claude Desktop)
• Un orientado al RGPD anonimizador de base de datos

En un servidor administrado por Cipi, cipi app create inyecta el requerido .env variables automáticamente. La verificación de estado y MCP pueden funcionar en cualquier host Laravel; implementación completa y registro el acceso espera un entorno administrado por Cipi.

Requisitos

$ composer require cipi/agent

El proveedor de servicios descubre automáticamente: no config/app.php es necesario un cambio. Después de la instalación, comprometerse y presionar; Cipi implementa la actualización en la próxima versión.

Opcional: publique el archivo de configuración (no Cipi o valores predeterminados personalizados):

$ php artisan vendor:publish --tag=cipi-config
$ php artisan cipi:status   # verify config and DB connectivity

Artisan comandos

Webhook — Implementaciones automáticas

El agente expone un punto final POST en /cipi/webhook. Cuando su proveedor de Git envía un push evento, el agente verifica la firma y escribe un .deploy-trigger archivo de bandera. Un cron trabajo que se ejecuta cada minuto a medida que el usuario de la aplicación detecta este archivo, lo elimina y ejecuta Deployer en el fondo.

Este diseño significa que la respuesta webhook es instantánea (sin tiempo de espera HTTP esperando que se implemente). completo) y Deployer se ejecuta con los permisos de usuario correctos, no sudo requerido.

Configura tu proveedor de Git

El token a utilizar se almacena en .env como CIPI_WEBHOOK_TOKEN. tu también puedes recuperarlo en cualquier momento con:

$ cipi deploy myapp --webhook

Filtrado de ramas

De forma predeterminada, cada inserción desencadena una implementación. Para restringir las implementaciones a una rama específica, agregue esto a su .env:

CIPI_DEPLOY_BRANCH=main

Los empujones a cualquier otra sucursal recibirán un skipped respuesta y no habrá despliegue desencadenado.

Control de salud

El agente también expone un punto final GET en /cipi/health que devuelve una carga útil JSON con el estado de la aplicación, la base de datos, el caché, la cola y el hash de confirmación de Git actualmente implementado. Útil para servicios de monitoreo externos como UptimeRobot. Protegido por el CIPI_HEALTH_TOKEN Token de portador: genere uno con php artisan cipi:generate-token health.

$ curl -H "Authorization: Bearer YOUR_CIPI_HEALTH_TOKEN" \
    https://yourdomain.com/cipi/health

{
  "estado": "saludable",
  "usuario_aplicación": "miaplicación",
  "php": "8.5",
  "laravel": "12.0.0",
  "medio ambiente": "producción",
  "cheques": {
    "aplicación":      { "bien": cierto, "versión": "2.1.0", "depurar": falso },
    "base de datos": { "bien": cierto, "base de datos": "miaplicación_prod" },
    "caché":    { "bien": cierto },
    "cola":    { "bien": cierto, "trabajos_pendientes": 0 },
    "implementar":   { "bien": cierto, "comprometerse": "a1b2c3d4…", "compromiso corto": "a1b2c3d" }
  },
  "marca de tiempo": "2026-06-10T14:22:01.000000Z"
}

La confirmación de implementación se resuelve desde la primera fuente disponible:

1. /home/{app_user}/.cipi/deploy.json (Cipi implementar metadatos)
2. /home/{app_user}/.cipi/last_commit
3. /home/{app_user}/logs/deploy.log
4. .git/HEAD o git rev-parse HEAD

Autenticación

La ficha de portador se resuelve en orden: CIPI_HEALTH_TOKEN (dedicado), entonces CIPI_WEBHOOK_TOKEN (retroceder). Deshabilite el punto final por completo con php artisan cipi:service health --disable o CIPI_HEALTH_CHECK=false.

Monitoreo de integraciones

El punto final de salud funciona con cualquier verificador HTTP que admita tokens de portador, p. Tiempo de actividadRobot, Mejor pila, Grafana, o personalizado cron + curl. Encuesta checks.queue.pending_jobs para alertas de acumulación de colas.

MCP Servidor

cipi-agente incluye un incorporado MCP servidor (Protocolo de contexto modelo) que expone su aplicación a asistentes de IA como Cursor, Código VS (con GitHub copiloto), y Escritorio Claude. El punto final implementa MCP 2024-11-05 sobre HTTP usando JSON-RPC 2.0 y está protegido por el CIPI_MCP_TOKEN Ficha al portador.

El punto final MCP está disponible en POST /cipi/mcp y está deshabilitado de forma predeterminada. para habilitar eso:

$ php artisan cipi:service mcp --enable
$ php artisan cipi:generate-token mcp

Herramientas disponibles

El servidor MCP expone seis herramientas que un asistente de IA puede invocar por su nombre:

logs parámetros de la herramienta

Operaciones bloqueadas (MCP seguridad)

• Artisan: serve, tinker, queue:work, queue:listen, schedule:work, horizon, octane:start, reverb:start
• SQL: DROP, TRUNCATE, GRANT, REVOKE, E/S de archivos: lectura/escritura limitada a 100 filas

Instrucciones de configuración

Ejecute el cipi:mcp Comando Artisan para obtener la URL del punto final y lista para pegar Fragmentos de configuración para su cliente AI:

$ php artisan cipi:mcp

El comando imprime las herramientas disponibles y la configuración JSON para Cursor, VS Code y Claude Escritorio.

Cursor

Agregue lo siguiente a ~/.cursor/mcp.json (o vaya a Cursor → Configuración → MCP):

{
  "mcpServidores": {
    "cipi-mi aplicación": {
      "tipo": "http",
      "URL": "https://tudominio.com/cipi/mcp",
      "encabezados": {
        "Autorización": "Portador YOUR_CIPI_MCP_TOKEN"
      }
    }
  }
}

Reemplazar cipi-myapp con el nombre de usuario de tu aplicación, yourdomain.com con tu dominio real, y YOUR_CIPI_MCP_TOKEN con la ficha de tu .env. El cursor se conecta de forma nativa a través de HTTP; no se necesita puente.

Código VS

VS Code (con GitHub Copilot) admite MCP de forma nativa desde la versión 1.102. Agregue lo siguiente a .vscode/mcp.json en su proyecto (o ejecutar MCP: Abrir configuración de usuario para una configuración global):

{
  "servidores": {
    "cipi-mi aplicación": {
      "tipo": "http",
      "URL": "https://tudominio.com/cipi/mcp",
      "encabezados": {
        "Autorización": "Portador YOUR_CIPI_MCP_TOKEN"
      }
    }
  }
}

Reemplazar cipi-myapp, yourdomain.com, y YOUR_CIPI_MCP_TOKEN como arriba. uso MCP: Agregar servidor desde la paleta de comandos para una configuración guiada. Código VS se conecta a través de HTTP: no se necesita puente.

Escritorio Claude

Claude Desktop requiere el mcp-remoto puente para convertir stdio a HTTP. Añade el siguiendo a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServidores": {
    "cipi-mi aplicación": {
      "comando": "npx",
      "argos": [
        "-y",
        "mcp-remoto",
        "https://tudominio.com/cipi/mcp",
        "-encabezado",
        "Autorización: Portador YOUR_CIPI_MCP_TOKEN"
      ]
    }
  }
}

Instalar mcp-remote globalmente una vez con:

$ npm install -g mcp-remote

¿Qué puedes hacer con él?

Una vez conectado, su asistente de IA puede interactuar con la aplicación administrada por Cipi de forma natural. idioma. Por ejemplo:

Usuario:  Is the app healthy? Any pending jobs in the queue?

Claudio: Calling health tool...
         Status: healthy — database, cache, and queue all OK.
         Queue: 0 pending jobs.

Usuario:  Show me the last errors from the log.

Claudio: Calling logs tool (lines: 100)...
         Found 2 errors in the last 100 lines:
         [2026-03-04 14:22:01] production.ERROR: Connection refused [...]
         [2026-03-04 14:23:15] production.ERROR: Redis timeout [...]

Usuario:  Clear the cache and deploy the latest version.

Claudio: Calling artisan tool (cache:clear)...
         Cache cleared successfully.
         Calling deploy tool...
         Deploy queued — Deployer will run within 1 minute.

Usuario:  What's the current migration status?

Claudio: Calling artisan tool (migrate:status)...
         All 47 migrations have been run.

Usuario:  How many users signed up in the last 7 days?

Claudio: Calling db_query tool (SELECT COUNT(*) FROM users WHERE created_at >= ...)...
         | count |
         |-------|
         | 23    |

Anonimizador de bases de datos

cipi-agenteincluye un anonimizador de base de datos incorporado que crea copias desinfectadas de su base de datos de producción: ideal para compartir con desarrolladores, equipos de control de calidad o entornos de prueba sin exponer datos reales del usuario. Es compatible con ambos MySQL y PostgreSQL, usos farsantetransformaciones basadas en JSON configuradas a través de un archivo y se ejecuta como un trabajo en segundo plano para que las bases de datos grandes no bloqueen HTTP solicitudes.

Esta característica vive dentro de tu Laravel aplicación (el cipi/agent paquete). Es independiente de la copia de seguridad de la base de datos a nivel de servidor API expuesta por cipi api — ver Agente frente a Cipi API abajo.

Casos de uso

• Desarrollo local — proporcione a cada desarrollador un conjunto de datos realista sin copiar correos electrónicos de producción, direcciones o notas de pago
• Entornos de puesta en escena/vista previa — actualizar una base de datos que no sea de producción desde estructura y volumen de producción, con PII reemplazada
• Control de calidad y demostraciones — reproducir errores que dependen de datos relacionales sin riesgo de GDPR
• Acceso de proveedor o contratista — compartir un volcado de SQL cuando una VPN + producción completa el acceso no es aceptable
• Tuberías de CI - correr cipi:anonymize en el servidor o disparador POST /cipi/db desde un paso de automatización seguro

Requisitos previos

Agente frente a Cipi API

Ambos componentes Cipi tocan bases de datos, pero resuelven problemas diferentes:

como funciona

1. Un autenticado POST /cipi/db solicitud (con un destinatario email) colas AnonymizeDatabaseJob
2. el trabajo se ejecuta php artisan cipi:anonymize, que:
   • vuelca la base de datos con mysqldump o pg_dump
   • fluye a través de INSERT declaraciones y reescribe sólo las columnas enumeradas en anonymization.json
   • escribe el resultado en storage/cipi/anonymized_{jobId}.sql
3. Si tiene éxito, Laravel envía un correo electrónico con un URL de descarga por tiempo limitado (15 minutos)
4. GET /cipi/db/{token} entrega el archivo, sin token de portador; la URL en sí es la credencial
5. En caso de error, se envía un correo electrónico de error en texto sin formato a la misma dirección.

Notificaciones por correo electrónico

HTTP API no devuelve la URL de descarga en la respuesta JSON: el correo electrónico es el único canal de entrega para POST /cipi/db. Entender quién lo recibe y lo que se debe configurar evita fallas silenciosas.

¿Quién recibe el correo electrónico?

Exactamente la dirección que pasas en el cuerpo JSON, nada más:

{ "correo electrónico": "desarrollador@ejemplo.com" }

• Éxito → HTML correo electrónico con el enlace de descarga firmado (15 minutos)
• Error → correo electrónico de texto sin formato con el error y el ID del trabajo
• Sin CC, BCC ni respaldo para el administrador Cipi, CIPI_APP_USER, o una dirección fija en .env
• Quien tenga CIPI_ANONYMIZER_TOKEN elige el destinatario en cada solicitud

Laravel el correo debe funcionar

Las notificaciones utilizan Laravel Mail fachada y sus aplicaciones MAIL_* configuración: la misma configuración que el restablecimiento de contraseña o los formularios de contacto. esto es independiente del servidor Cipi SMTP (cipi smtp configure para copia de seguridad/implementación alertas en el host).

Producción típica .env entradas:

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=...
MAIL_PASSWORD=...
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@myapp.example.com
MAIL_FROM_NAME="${APP_NAME}"

Prueba rápida de correo (como usuario de la aplicación, antes de su primera exportación):

$ php artisan tinker --execute="Mail::raw('Cipi prueba de correo anonimizador', fn (\$m) => \$m->to('you@example.com')->subject('Prueba de correo'));"

Si ese mensaje no llega, corrija primero el correo Laravel o use la ruta CLI (php artisan cipi:anonymize) que escribe el archivo directamente y omite el correo electrónico.

Configuración: paso a paso

Ejecute estos comandos en el servidor como usuario de la aplicación (SS: ssh myapp@your-server o sudo su - myapp como raíz - ver SSH como usuario de la aplicación):

1. Instale el agente (si aún no está en composer.json):

$ composer require cipi/agent
# commit, push, deploy — or run on the current release

2. Habilite el servicio y cree un token:

$ php artisan cipi:service anonymize --enable
$ php artisan cipi:generate-token anonymize

3. Armar el archivo de configuración:

$ php artisan cipi:init-anonymize

Esto crea /home/{app_user}/.db/anonymization.json (permisos 0640) desde la plantilla incorporada. El archivo vive fuera del repositorio de Git - nunca lo es implementado con su código. uso --force para sobrescribir un archivo existente.

4. Edite la configuración para que coincida con sus tablas reales y columnas confidenciales (consulte Configuración).

5. Verificar cola y correo: confirme que el trabajador ejecuta trabajos y Laravel puede enviarlos al dirección que pasarás POST /cipi/db (ver Notificaciones por correo electrónico).

$ php artisan cipi:status          # DB connectivity
$ php artisan queue:work --once   # optional: confirm worker can run jobs
# send a test email — must arrive before using POST /cipi/db
$ php artisan tinker --execute="Mail::raw('Prueba de correo', fn (\$m) => \$m->to('you@example.com')->subject('Prueba de correo'));"

6. Active su primera exportación anónima a través de HTTP o CLI (ver ejemplos a continuación).

Configuración

Rutas válidas (el primer partido gana):

• /home/{app_user}/.db/anonymization.json — recomendado
• /home/{app_user}/.cipi/anonymization.json — alternativa

El archivo JSON tiene dos claves de nivel superior: transformations (obligatorio) y options (opcional).

{
  "transformaciones": {
    "usuarios": {
      "nombre": "nombre falso",
      "correo electrónico": "correo electrónico falso",
      "contraseña": "contraseña",
      "teléfono": "número de teléfono falso",
      "dirección": "dirección falsa"
    },
    "órdenes": {
      "notas_del_cliente": "párrafo falso",
      "dirección_de_envío": "dirección falsa"
    },
    "tickets_de_soporte": {
      "mensaje_usuario": "párrafo falso",
      "respuesta_agente": "párrafo falso"
    }
  },
  "opciones": {
    "algoritmo_hash": "auto",
    "preserve_ids": cierto,
    "faker_locale": "en_US"
  }
}

bajo transformations, cada clave es una nombre de la tabla. Las claves anidadas son nombres de columnas; los valores son tipos de transformación (no nombres de métodos Faker sin formato; consulte tabla siguiente). columnas no enumerados mantienen sus valores originales, por lo que puede anonimizar la PII mientras preservar claves externas, enumeraciones y campos de lógica empresarial.

Transformaciones admitidas

Opciones

HTTP API — puntos finales

Cuando el anonimizador está desactivado (CIPI_ANONYMIZER=false), las rutas regresan 404 — los puntos finales están completamente ocultos.

Ejemplos prácticos (rizo)

Establezca las variables una vez (reemplácelas con el dominio de su aplicación y el token de .env):

exportar APP_URL="https://miaplicación.ejemplo.com"
exportar CIPI_ANONYMIZER_TOKEN="tu-token-de-env"

1. Poner en cola un trabajo de anonimización

curl -sS -X POST "${APP_URL}/cipi/db" \
  -H "Autorización: Portador ${CIPI_ANONYMIZER_TOKEN}" \
  -H "Tipo de contenido: aplicación/json" \
  -H "Aceptar: solicitud/json" \
  -d '{"correo electrónico": "desarrollador@ejemplo.com"}'

Respuesta exitosa (200):

{
  "estado": "en cola",
  "mensaje": "El trabajo de anonimización de la base de datos se ha puesto en cola. Recibirá un correo electrónico con instrucciones de descarga cuando se complete".,
  "correo electrónico": "desarrollador@ejemplo.com"
}

La llamada HTTP regresa inmediatamente con status: queued - eso hace no garantizar que se envió el correo electrónico de notificación. El procesamiento puede tardar unos minutos en bases de datos grandes (trabajo tiempo de espera: 1 hora). El mensaje de finalización va sólo al email en tu cuerpo JSON; si no llega nada, revisa storage/logs/laravel.log por errores en el transporte del correo, php artisan queue:failed por un trabajo fallido, y que MAIL_* está configurado (ver Notificaciones por correo electrónico).

2. Descargue el volcado (desde el enlace del correo electrónico)

El correo electrónico de finalización contiene una URL como:

https://myapp.example.com/cipi/db/AbCdEf...?expires=1710000000&signature=...

Guárdelo con curl (pegue la URL completa del correo electrónico, sin encabezado de portador):

curl -sS -L -o anonymized.sql "PASTE_FULL_SIGNED_URL_FROM_EMAIL"

# Import locally (MySQL example)
mysql -u root -p myapp_local < anonymized.sql

Devuelven enlaces caducados o no válidos 410 Gone o 404. Solicitar una nueva exportación con POST /cipi/db si pasó la ventana de 15 minutos.

3. Busque una identificación de usuario por correo electrónico

Después de la anonimización, los correos electrónicos son falsos, pero los ID de usuario siguen siendo los mismos. Usa esto antes anonimizar para asignar un correo electrónico de producción conocido a una identificación que puede encontrar más adelante en el volcado:

curl -sS -X POST "${APP_URL}/cipi/db/usuario" \
  -H "Autorización: Portador ${CIPI_ANONYMIZER_TOKEN}" \
  -H "Tipo de contenido: aplicación/json" \
  -d '{"correo electrónico": "cliente@producción.com"}'

{
  "id_usuario": 42,
  "correo electrónico": "cliente@producción.com",
  "encontrado_en": "2026-06-10T14:22:01+00:00"
}

Esto consulta el vivo. users tabla: ejecuta solo cuando se te permite tocar la producción datos. No modifica nada.

4. Respuestas de error (solución de problemas)

CLI — ejecutar sin HTTP

Para scripts, cron o exportaciones únicas en el servidor:

$ php artisan cipi:anonymize \
    /home/myapp/.db/anonymization.json \
    /home/myapp/anonymized_export.sql

El comando imprime tres pasos (volcar → transformar → guardar) y sale de un valor distinto de cero en caso de falla. no lo hace enviar correo electrónico: copie el archivo a través de SCP o su propio canal seguro.

Curl de comparación: Cipi API copia de seguridad sin formato

Como referencia, un no anonimizado copia de seguridad del servidor a través de Cipi API se ve así (diferente host, token y semántica):

exportar CIPI_API_URL="https://api.myserver.com"
exportar CIPI_API_TOKEN="token-sanctum-con-administración-dbs"

curl -sS -X POST "${CIPI_API_URL}/api/dbs/myapp_db/backup" \
  -H "Autorización: Portador ${CIPI_API_TOKEN}" \
  -H "Aceptar: solicitud/json"

eso regresa 202 con un job_id - encuesta GET /api/jobs/{id} para la ruta de respaldo en el servidor. El archivo contiene datos reales de producción; restringir acceder en consecuencia.

Consejos de seguridad y RGPD

• Tienda CIPI_ANONYMIZER_TOKEN en la gestión de secretos: cualquiera que lo tenga puede poner en cola los volcados y consulta /cipi/db/user
• Gire la ficha después de los cambios de equipo: php artisan cipi:generate-token anonymize
• Desactivar cuando no sea necesario: php artisan cipi:service anonymize --disable (los puntos finales devuelven 404)
• Los enlaces de descarga caducan en 15 minutos — reenviar correos electrónicos con cuidado
• Documente qué columnas se transforman para su DPA/política de privacidad
• Pruebe el volcado: grep para un correo electrónico de producción conocido; no debería aparecer si fakeEmail estaba establecido en esa columna

Seguridad

Cipi Usos del agente defensa en profundidad: cada característica tiene su propio token de portador y puede ser desactivado de forma independiente. Cuando están deshabilitadas, las rutas regresan 404 (oculto, no 403).

Aislamiento de tokens

Webhook verificación

• GitHub — X-Hub-Signature-256 HMAC-SHA256
• GitLab — X-Gitlab-Token comparación de encabezados

Código fuente y versiones: github.com/cipi-sh/agent (MIT).

Variables ENV

Estas variables son inyectadas automáticamente por Cipi en la aplicación.env durante cipi app create. Alternar funciones opcionales con php artisan cipi:service {type} --enable|--disable o configurarlos manualmente.