Cipi Agent

Installazione di Cipi Agent

Cipi Agent (cipi/agent on Packagist) è il companion Laravel ufficiale per Cipi. Collega la tua applicazione al pannello di controllo del server con:

• Deploy attivati da webhook da GitHub e GitLab
• Monitoraggio health (app, database, cache, queue, commit di deploy)
• Un server MCP in-app per assistenti AI (Cursor, VS Code, Claude Desktop)
• Un database anonymizer orientato al GDPR

Su un server gestito da Cipi, cipi app create inietta automaticamente le variabili .env richieste. Health check e MCP funzionano su qualsiasi host Laravel; deploy completo e accesso ai log richiedono un ambiente gestito da Cipi.

Requisiti

$ composer require cipi/agent

Il service provider si auto-scopre — non serve modificare config/app.php. Dopo l'installazione, commit e push; Cipi deploya l'aggiornamento al prossimo release.

Opzionale — pubblica il file di config (non-Cipi o default personalizzati):

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

Comandi Artisan

Webhook — deploy automatici

L'agent espone un endpoint POST su /cipi/webhook. Quando il tuo provider Git invia un evento push, l'agent verifica la firma e scrive un file flag .deploy-trigger. Un cron job che gira ogni minuto come utente dell'app rileva questo file, lo rimuove ed esegue Deployer in background.

Questo design significa che la risposta del webhook è istantanea (nessun timeout HTTP in attesa del completamento del deploy) e Deployer gira con i permessi utente corretti — nessun sudo richiesto.

Configura il tuo provider Git

Il token da usare è salvato in .env come CIPI_WEBHOOK_TOKEN. Puoi recuperarlo in qualsiasi momento con:

$ cipi deploy myapp --webhook

Filtro branch

Di default ogni push attiva un deploy. Per limitare i deploy a un branch specifico, aggiungi questo al tuo .env:

CIPI_DEPLOY_BRANCH=main

I push su qualsiasi altro branch riceveranno una risposta skipped e nessun deploy verrà attivato.

Health check

L'agent espone anche un endpoint GET su /cipi/health che restituisce un payload JSON con lo stato di app, database, cache, queue e l'hash del commit Git attualmente deployato. Utile per servizi di monitoraggio esterni come UptimeRobot. Protetto dal Bearer token CIPI_HEALTH_TOKEN — generane uno con php artisan cipi:generate-token health.

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

{
  "status": "healthy",
  "app_user": "myapp",
  "php": "8.5",
  "laravel": "12.0.0",
  "environment": "production",
  "checks": {
    "app":      { "ok": true, "version": "2.1.0", "debug": false },
    "database": { "ok": true, "database": "myapp_prod" },
    "cache":    { "ok": true },
    "queue":    { "ok": true, "pending_jobs": 0 },
    "deploy":   { "ok": true, "commit": "a1b2c3d4…", "short_commit": "a1b2c3d" }
  },
  "timestamp": "2026-06-10T14:22:01.000000Z"
}

Il commit di deploy viene risolto dalla prima fonte disponibile:

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

Autenticazione

Il Bearer token viene risolto in ordine: CIPI_HEALTH_TOKEN (dedicato), poi CIPI_WEBHOOK_TOKEN (fallback). Disabilita l'endpoint del tutto con php artisan cipi:service health --disable o CIPI_HEALTH_CHECK=false.

Integrazioni di monitoraggio

L'endpoint health funziona con qualsiasi checker HTTP che supporti Bearer token — es. UptimeRobot, Better Stack, Grafana, o cron personalizzato + curl. Interroga checks.queue.pending_jobs per alert di backlog della queue.

Server MCP

cipi-agent include un server MCP integrato (Model Context Protocol) che espone la tua applicazione agli assistenti AI come Cursor, VS Code (con GitHub Copilot) e Claude Desktop. L'endpoint implementa MCP 2024-11-05 su HTTP usando JSON-RPC 2.0 ed è protetto dal Bearer token CIPI_MCP_TOKEN.

L'endpoint MCP è disponibile su POST /cipi/mcp ed è disabilitato di default. Per abilitarlo:

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

Tool disponibili

Il server MCP espone sei tool che un assistente AI può invocare per nome:

Parametri del tool logs

Operazioni bloccate (sicurezza MCP)

• Artisan: serve, tinker, queue:work, queue:listen, schedule:work, horizon, octane:start, reverb:start
• SQL: DROP, TRUNCATE, GRANT, REVOKE, file I/O — lettura/scrittura limitata a 100 righe

Istruzioni di setup

Esegui il comando Artisan cipi:mcp per ottenere l'URL dell'endpoint e snippet di configurazione pronti da incollare per il tuo client AI:

$ php artisan cipi:mcp

Il comando stampa i tool disponibili e la configurazione JSON per Cursor, VS Code e Claude Desktop.

Cursor

Aggiungi quanto segue a ~/.cursor/mcp.json (oppure vai su Cursor → Settings → MCP):

{
  "mcpServers": {
    "cipi-myapp": {
      "type": "http",
      "url": "https://yourdomain.com/cipi/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_CIPI_MCP_TOKEN"
      }
    }
  }
}

Sostituisci cipi-myapp con il nome utente della tua app, yourdomain.com con il tuo dominio reale e YOUR_CIPI_MCP_TOKEN con il token dal tuo .env. Cursor si connette nativamente via HTTP — nessun bridge necessario.

VS Code

VS Code (con GitHub Copilot) supporta MCP nativamente dalla versione 1.102. Aggiungi quanto segue a .vscode/mcp.json nel tuo progetto (oppure esegui MCP: Open User Configuration per un setup globale):

{
  "servers": {
    "cipi-myapp": {
      "type": "http",
      "url": "https://yourdomain.com/cipi/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_CIPI_MCP_TOKEN"
      }
    }
  }
}

Sostituisci cipi-myapp, yourdomain.com e YOUR_CIPI_MCP_TOKEN come sopra. Usa MCP: Add Server dalla Command Palette per un setup guidato. VS Code si connette via HTTP — nessun bridge necessario.

Claude Desktop

Claude Desktop richiede il bridge mcp-remote per convertire stdio in HTTP. Aggiungi quanto segue a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cipi-myapp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://yourdomain.com/cipi/mcp",
        "--header",
        "Authorization: Bearer YOUR_CIPI_MCP_TOKEN"
      ]
    }
  }
}

Installa mcp-remote globalmente una volta con:

$ npm install -g mcp-remote

Cosa puoi fare con esso

Una volta connesso, il tuo assistente AI può interagire con l'applicazione gestita da Cipi in linguaggio naturale. Ad esempio:

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

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

User:  Show me the last errors from the log.

Claude: 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 [...]

User:  Clear the cache and deploy the latest version.

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

User:  What's the current migration status?

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

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

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

Database anonymizer

cipi-agent include un database anonymizer integrato che crea copie sanitizzate del tuo database di produzione — ideale per condividerle con sviluppatori, team QA o ambienti staging senza esporre dati reali degli utenti. Supporta sia MySQL che PostgreSQL, usa trasformazioni basate su Faker configurate via file JSON e gira come job in background così i database grandi non bloccano le richieste HTTP.

Questa funzionalità risiede dentro la tua applicazione Laravel (il package cipi/agent). È separata dall'API di backup database a livello server esposta da cipi api — vedi Agent vs Cipi API sotto.

Casi d'uso

• Sviluppo locale — offri a ogni sviluppatore un dataset realistico senza copiare email, indirizzi o note di pagamento di produzione
• Ambienti staging / preview — aggiorna un database non di produzione con struttura e volume di produzione, con PII sostituiti
• QA e demo — riproduci bug che dipendono da dati relazionali senza rischio GDPR
• Accesso vendor o contractor — condividi un dump SQL quando VPN completa + accesso produzione non è accettabile
• Pipeline CI — esegui cipi:anonymize sul server o attiva POST /cipi/db da uno step di automazione sicuro

Prerequisiti

Agent vs Cipi API

Entrambi i componenti Cipi toccano i database, ma risolvono problemi diversi:

Come funziona

1. Una richiesta autenticata POST /cipi/db (con un email destinatario) accoda AnonymizeDatabaseJob
2. Il job esegue php artisan cipi:anonymize, che:
   • esegue il dump del database con mysqldump o pg_dump
   • scorre le istruzioni INSERT e riscrive solo le colonne elencate in anonymization.json
   • scrive il risultato in storage/cipi/anonymized_{jobId}.sql
3. In caso di successo, Laravel invia un'email con un URL di download a tempo limitato (15 minuti)
4. GET /cipi/db/{token} serve il file — nessun Bearer token; l'URL stesso è la credenziale
5. In caso di fallimento, viene inviata un'email di errore in plain text allo stesso indirizzo

Notifiche email

L'API HTTP non restituisce l'URL di download nella risposta JSON — l'email è l'unico canale di consegna per POST /cipi/db. Capire chi lo riceve e cosa deve essere configurato evita fallimenti silenziosi.

Chi riceve l'email?

Esattamente l'indirizzo che passi nel body JSON — nient'altro:

{ "email": "developer@example.com" }

• Successo → email HTML con il link di download firmato (15 minuti)
• Fallimento → email plain text con l'errore e l'ID del job
• Nessun CC, BCC o fallback all'admin Cipi, CIPI_APP_USER o un indirizzo fisso in .env
• Chiunque possieda CIPI_ANONYMIZER_TOKEN sceglie il destinatario a ogni richiesta

Laravel mail deve funzionare

Le notifiche usano la facade Mail di Laravel e le impostazioni MAIL_* della tua applicazione — la stessa config di reset password o form di contatto. È indipendente dallo SMTP server Cipi (cipi smtp configure per alert backup/deploy sull'host).

Voci tipiche di .env in produzione:

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}"

Test rapido mail (come utente dell'app, prima del tuo primo export):

$ php artisan tinker --execute="Mail::raw('Cipi anonymizer mail test', fn (\$m) => \$m->to('you@example.com')->subject('Mail test'));"

Se quel messaggio non arriva, sistema prima Laravel mail — oppure usa il percorso CLI (php artisan cipi:anonymize) che scrive il file direttamente e salta l'email.

Setup — passo per passo

Esegui questi comandi sul server come utente dell'app (SSH: ssh myapp@your-server o sudo su - myapp come root — vedi SSH come utente dell'app):

1. Installa l'agent (se non è già in composer.json):

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

2. Abilita il servizio e crea un token:

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

3. Crea lo scaffold del file di configurazione:

$ php artisan cipi:init-anonymize

Crea /home/{app_user}/.db/anonymization.json (permessi 0640) dal template integrato. Il file vive fuori dal repository Git — non viene mai deployato con il tuo codice. Usa --force per sovrascrivere un file esistente.

4. Modifica la config per corrispondere alle tue tabelle reali e colonne sensibili (vedi Configuration).

5. Verifica queue e mail: conferma che il worker esegua i job e che Laravel possa inviare all'indirizzo che passerai in POST /cipi/db (vedi Email notifications).

$ 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('Mail test', fn (\$m) => \$m->to('you@example.com')->subject('Mail test'));"

6. Attiva il tuo primo export anonymizzato via HTTP o CLI (vedi esempi sotto).

Configurazione

Percorsi validi (vince il primo match):

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

Il file JSON ha due chiavi top-level: transformations (obbligatorio) e options (opzionale).

{
  "transformations": {
    "users": {
      "name": "fakeName",
      "email": "fakeEmail",
      "password": "password",
      "phone": "fakePhoneNumber",
      "address": "fakeAddress"
    },
    "orders": {
      "customer_notes": "fakeParagraph",
      "shipping_address": "fakeAddress"
    },
    "support_tickets": {
      "user_message": "fakeParagraph",
      "agent_response": "fakeParagraph"
    }
  },
  "options": {
    "hash_algorithm": "auto",
    "preserve_ids": true,
    "faker_locale": "en_US"
  }
}

Sotto transformations, ogni chiave è un nome tabella. Le chiavi annidate sono nomi colonna; i valori sono tipi di trasformazione (non nomi grezzi di metodi Faker — vedi tabella sotto). Le colonne non elencate mantengono i valori originali, così puoi anonymizzare PII preservando foreign key, enum e campi di business logic.

Trasformazioni supportate

Opzioni

HTTP API — endpoint

Quando l'anonymizer è disabilitato (CIPI_ANONYMIZER=false), le route restituiscono 404 — gli endpoint sono completamente nascosti.

Esempi pratici (curl)

Sistema le variabili una volta (sostituisci con il dominio dell'app e il token dal .env):

export APP_URL="https://myapp.example.com"
export CIPI_ANONYMIZER_TOKEN="your-token-from-env"

1. Accoda un job di anonymization

curl -sS -X POST "${APP_URL}/cipi/db" \
  -H "Authorization: Bearer ${CIPI_ANONYMIZER_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"email": "developer@example.com"}'

Risposta di successo (200):

{
  "status": "queued",
  "message": "Database anonymization job has been queued. You will receive an email with download instructions when complete.",
  "email": "developer@example.com"
}

La chiamata HTTP restituisce immediatamente status: queued — questo non garantisce che l'email di notifica sia stata inviata. L'elaborazione può richiedere minuti su database grandi (timeout job: 1 ora). Il messaggio di completamento va solo all'email nel body JSON; se non arriva nulla, controlla storage/logs/laravel.log per errori di trasporto mail, php artisan queue:failed per un job fallito e che MAIL_* sia configurato (vedi Email notifications).

2. Scarica il dump (dal link email)

L'email di completamento contiene un URL come:

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

Salvalo con curl (incolla l'URL completo dall'email — nessun header Bearer):

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

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

Link scaduti o non validi restituiscono 410 Gone o 404. Richiedi un nuovo export con POST /cipi/db se la finestra di 15 minuti è passata.

3. Cerca un user ID per email

Dopo l'anonymization, le email sono fake — ma gli user ID restano gli stessi. Usa questo prima di anonymizzare per mappare un'email di produzione nota a un ID che puoi trovare dopo nel dump:

curl -sS -X POST "${APP_URL}/cipi/db/user" \
  -H "Authorization: Bearer ${CIPI_ANONYMIZER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"email": "customer@production.com"}'

{
  "user_id": 42,
  "email": "customer@production.com",
  "found_at": "2026-06-10T14:22:01+00:00"
}

Interroga la tabella live users — esegui solo quando sei autorizzato a toccare dati di produzione. Non modifica nulla.

4. Risposte di errore (troubleshooting)

CLI — esecuzione senza HTTP

Per script, cron o export one-off sul server:

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

Il comando stampa tre passi (dump → transform → save) ed esce con codice non-zero in caso di fallimento. Non invia email — copia il file via SCP o il tuo canale sicuro.

Confronto curl: backup raw Cipi API

Per riferimento, un backup server non anonymizzato via Cipi API assomiglia a questo (host, token e semantica diversi):

export CIPI_API_URL="https://api.myserver.com"
export CIPI_API_TOKEN="sanctum-token-with-dbs-manage"

curl -sS -X POST "${CIPI_API_URL}/api/dbs/myapp_db/backup" \
  -H "Authorization: Bearer ${CIPI_API_TOKEN}" \
  -H "Accept: application/json"

Restituisce 202 con un job_id — interroga GET /api/jobs/{id} per il percorso backup sul server. L'archivio contiene dati di produzione reali; limita l'accesso di conseguenza.

Sicurezza e suggerimenti GDPR

• Conserva CIPI_ANONYMIZER_TOKEN in un secrets manager — chiunque lo possieda può accodare dump e interrogare /cipi/db/user
• Ruota il token dopo cambi nel team: php artisan cipi:generate-token anonymize
• Disabilita quando non serve: php artisan cipi:service anonymize --disable (gli endpoint restituiscono 404)
• I link di download scadono in 15 minuti — inoltra le email con attenzione
• Documenta quali colonne vengono trasformate per il tuo DPA / privacy policy
• Testa il dump: grep per un'email di produzione nota — non deve apparire se fakeEmail era impostato su quella colonna

Sicurezza

Cipi Agent usa la defense in depth: ogni funzionalità ha il proprio Bearer token e può essere disattivata indipendentemente. Quando disabilitata, le route restituiscono 404 (nascoste, non 403).

Isolamento token

Verifica webhook

• GitHub — X-Hub-Signature-256 HMAC-SHA256
• GitLab — X-Gitlab-Token header comparison

Codice sorgente e release: github.com/cipi-sh/agent (MIT).

Variabili ENV

Queste variabili vengono iniettate automaticamente da Cipi nel .env dell'app durante cipi app create. Attiva o disattiva funzionalità opzionali con php artisan cipi:service {type} --enable|--disable o impostale manualmente.