Cipi Agente

Instalando o Agente Cipi

Cipi Agente (cipi/agent no Packagista) é o companheiro oficial de Laravel para Cipi. Ele conecta seu aplicativo e o painel de controle do servidor com:

• Implantações acionadas por Webhook de GitHub e GitLab
• Monitoramento de integridade (aplicativo, banco de dados, cache, fila, commit de implantação)
• Um aplicativo Servidor MCP para assistentes de IA (Cursor, VS Code, Claude Desktop)
• Orientado para GDPR anonimizador de banco de dados

Em um servidor gerenciado por Cipi, cipi app create injeta o necessário .env variáveis automaticamente. A verificação de integridade e MCP podem funcionar em qualquer host Laravel; implantação completa e registro o acesso espera um ambiente gerenciado por Cipi.

Requisitos

$ composer require cipi/agent

O provedor de serviços descobre automaticamente — não config/app.php é necessária uma mudança. Após a instalação, comprometer e empurrar; Cipi implanta a atualização na próxima versão.

Opcional — publique o arquivo de configuração (não Cipi ou padrões personalizados):

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

Comandos Artisan

Webhook — Implantações automáticas

O agente expõe um endpoint POST em /cipi/webhook. Quando seu provedor Git envia um push evento, o agente verifica a assinatura e escreve um .deploy-trigger arquivo de bandeira. Um cron job sendo executado a cada minuto enquanto o usuário do aplicativo detecta esse arquivo, o remove e executa o Deployer no fundo.

Este design significa que a resposta webhook é instantânea (sem tempo limite de HTTP aguardando a implantação para concluído) e o Deployer é executado com as permissões de usuário corretas — não sudo necessário.

Configure seu provedor Git

O token a ser usado é armazenado em .env como CIPI_WEBHOOK_TOKEN. Você também pode recupere-o a qualquer momento com:

$ cipi deploy myapp --webhook

Filtragem de ramificação

Por padrão, cada push aciona uma implantação. Para restringir implantações a uma ramificação específica, adicione isto ao seu .env:

CIPI_DEPLOY_BRANCH=main

Pushes para qualquer outro branch receberão um skipped resposta e nenhuma implantação será acionado.

Verificação de saúde

O agente também expõe um endpoint GET em /cipi/health que retorna uma carga útil JSON com o status do aplicativo, banco de dados, cache, fila e o hash de commit do Git atualmente implantado. Útil para serviços de monitoramento externo, como UptimeRobot. Protegido pelo CIPI_HEALTH_TOKEN Token do portador — gere um com php artisan cipi:generate-token health.

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

{
  "estado": "saudável",
  "app_user": "meu aplicativo",
  "php": "8.5",
  "laravel": "12.0.0",
  "meio ambiente": "produção",
  "cheques": {
    "aplicativo":      { "ok": verdade, "versão": "2.1.0", "depurar": falso },
    "banco de dados": { "ok": verdade, "banco de dados": "meuapp_prod" },
    "cache":    { "ok": verdade },
    "fila":    { "ok": verdade, "trabalhos_pendentes": 0 },
    "implantar":   { "ok": verdade, "comprometer-se": "a1b2c3d4…", "short_commit": "a1b2c3d" }
  },
  "carimbo de data/hora": "2026-06-10T14:22:01.000000Z"
}

O commit de implantação é resolvido a partir da primeira fonte disponível:

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

Autenticação

O token do portador é resolvido na seguinte ordem: CIPI_HEALTH_TOKEN (dedicado), então CIPI_WEBHOOK_TOKEN (cair pra trás). Desative totalmente o endpoint com php artisan cipi:service health --disable ou CIPI_HEALTH_CHECK=false.

Monitorando integrações

O endpoint de integridade funciona com qualquer verificador HTTP que suporte tokens Bearer – por exemplo. UptimeRobot, Melhor pilha, Grafanaou personalizado MCP + curl. Enquete checks.queue.pending_jobs para alertas de pendências de fila.

MCP Servidor

cipi-agente inclui um embutido Servidor MCP (Protocolo de Contexto Modelo) que expõe seu aplicativo a assistentes de IA, como Cursor, Código VS (com GitHub Copiloto), e Claude Desktop. O ponto final implementa MCP 05/11/2024 sobre HTTP usando JSON-RPC 2.0 e é protegido pelo CIPI_MCP_TOKEN Token do portador.

O endpoint MCP está disponível em POST /cipi/mcp e está desabilitado por padrão. Para habilitar isso:

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

Ferramentas disponíveis

O servidor MCP expõe seis ferramentas que um assistente de IA pode invocar pelo nome:

logs parâmetros da ferramenta

Operações bloqueadas (segurança MCP)

• Artisan: serve, tinker, queue:work, queue:listen, schedule:work, horizon, octane:start, reverb:start
• SQL: DROP, TRUNCATE, GRANT, REVOKE, E/S de arquivo – leitura/gravação limitada em 100 linhas

Instruções de configuração

Execute o cipi:mcp Comando Artisan para obter o URL do endpoint e pronto para colar trechos de configuração para seu cliente de IA:

$ php artisan cipi:mcp

O comando imprime as ferramentas disponíveis e a configuração JSON para Cursor, VS Code e Claude Área de trabalho.

Cursor

Adicione o seguinte a ~/.cursor/mcp.json (ou vá para Cursor → Configurações → MCP):

{
  "mcpServidores": {
    "cipi-meuapp": {
      "tipo": "http",
      "URL": "https://seudominio.com/cipi/mcp",
      "cabeçalhos": {
        "Autorização": "Portador YOUR_CIPI_MCP_TOKEN"
      }
    }
  }
}

Substituir cipi-myapp com o nome de usuário do seu aplicativo, yourdomain.com com o seu domínio real, e YOUR_CIPI_MCP_TOKEN com o token do seu .env. O cursor se conecta nativamente através de HTTP — sem necessidade de ponte.

Código VS

O VS Code (com GitHub Copilot) suporta MCP nativamente desde a versão 1.102. Adicione o seguinte a .vscode/mcp.json em seu projeto (ou execute MCP: Abrir configuração do usuário para uma configuração global):

{
  "servidores": {
    "cipi-meuapp": {
      "tipo": "http",
      "URL": "https://seudominio.com/cipi/mcp",
      "cabeçalhos": {
        "Autorização": "Portador YOUR_CIPI_MCP_TOKEN"
      }
    }
  }
}

Substituir cipi-myapp, yourdomain.come YOUR_CIPI_MCP_TOKEN como acima. Usar MCP: Adicionar servidor na paleta de comandos para uma configuração guiada. Código VS conecta-se através de HTTP — nenhuma ponte é necessária.

Claude Desktop

Claude Desktop requer o mcp-remoto bridge para converter stdio em HTTP. Adicione o seguindo para ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServidores": {
    "cipi-meuapp": {
      "comando": "NPX",
      "argumentos": [
        "-você",
        "mcp-remoto",
        "https://seudominio.com/cipi/mcp",
        "-cabeçalho",
        "Autorização: Portador YOUR_CIPI_MCP_TOKEN"
      ]
    }
  }
}

Instalar mcp-remote globalmente uma vez com:

$ npm install -g mcp-remote

O que você pode fazer com isso

Uma vez conectado, seu assistente de IA pode interagir com o aplicativo gerenciado por Cipi naturalmente linguagem. Por exemplo:

Usuário:  Is the app healthy? Any pending jobs in the queue?

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

Usuário:  Show me the last errors from the log.

Cláudio: 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 [...]

Usuário:  Clear the cache and deploy the latest version.

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

Usuário:  What's the current migration status?

Cláudio: Calling artisan tool (migrate:status)...
         All 47 migrations have been run.

Usuário:  How many users signed up in the last 7 days?

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

Anonimizador de banco de dados

cipi-agenteinclui um anonimizador de banco de dados integrado que cria cópias limpas de seu banco de dados de produção — ideal para compartilhar com desenvolvedores, equipes de controle de qualidade ou ambientes de teste sem expor dados reais do usuário. Suporta ambos MCP e MySQL, usa Falsificadortransformações baseadas em -configuradas por meio de um arquivo JSON e executadas como um trabalho em segundo plano para que bancos de dados grandes não bloqueiem solicitações HTTP.

Esse recurso reside dentro do seu Laravel aplicativo (o cipi/agent pacote). Ele é separado do backup de banco de dados em nível de servidor API exposto por cipi api - veja Agente vs Cipi API abaixo.

Casos de uso

• Desenvolvimento local - forneça a cada desenvolvedor um conjunto de dados realista sem copiar e-mails de produção, endereços ou notas de pagamento
• Ambientes de preparação/visualização — atualizar um banco de dados que não seja de produção estrutura e volume de produção, com PII substituído
• Controle de qualidade e demonstrações — reproduzir bugs que dependem de dados relacionais sem risco do GDPR
• Acesso de fornecedor ou contratado — compartilhe um dump SQL quando uma VPN completa + produção o acesso não é aceitável
• Pipelines de CI - correr cipi:anonymize no servidor ou gatilho POST /cipi/db de uma etapa de automação segura

Pré-requisitos

Agente vs Cipi API

Ambos os componentes Cipi tocam bancos de dados, mas resolvem problemas diferentes:

Como funciona

1. Um autenticado POST /cipi/db solicitação (com um destinatário email) filas AnonymizeDatabaseJob
2. O trabalho é executado php artisan cipi:anonymize, que:
   • despeja o banco de dados com mysqldump ou pg_dump
   • flui através INSERT declarações e reescreve apenas as colunas listadas em anonymization.json
   • escreve o resultado em storage/cipi/anonymized_{jobId}.sql
3. Em caso de sucesso, Laravel envia um e-mail com um URL de download por tempo limitado (15 minutos)
4. GET /cipi/db/{token} entrega o arquivo — sem token de portador; o URL em si é o credencial
5. Em caso de falha, um e-mail de erro em texto simples é enviado para o mesmo endereço

Notificações por e-mail

O HTTP API não retorna o URL de download na resposta JSON — e-mail é o único canal de entrega para POST /cipi/db. Entender quem recebe e o que deve ser configurado evita falhas silenciosas.

Quem recebe o e-mail?

Exatamente o endereço que você passa no corpo de JSON — nada mais:

{ "e-mail": "desenvolvedor@exemplo.com" }

• Sucesso → HTML e-mail com link de download assinado (15 minutos)
• Falha → e-mail de texto simples com o erro e o ID do trabalho
• Sem CC, CCO ou substituto para o administrador Cipi, CIPI_APP_USER, ou um endereço fixo em .env
• Quem segura CIPI_ANONYMIZER_TOKEN escolhe o destinatário em cada solicitação

Laravel e-mail deve funcionar

As notificações usam Laravel's Mail fachada e sua aplicação MAIL_* configurações – a mesma configuração de redefinições de senha ou formulários de contato. Isto é independente do servidor Cipi SMTP (cipi smtp configure para backup/implantação alertas no host).

Produção 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}"

Teste rápido de e-mail (como usuário do aplicativo, antes da primeira exportação):

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

Se essa mensagem não chegar, corrija o e-mail Laravel primeiro – ou use o caminho CLI (php artisan cipi:anonymize) que grava o arquivo diretamente e ignora o email.

Configuração – passo a passo

Execute estes comandos no servidor como usuário do aplicativo (SSH: ssh myapp@your-server ou sudo su - myapp como root - veja SSH como usuário do aplicativo):

1. Instale o agente (se ainda não estiver em composer.json):

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

2. Habilite o serviço e crie um token:

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

3. Crie o arquivo de configuração:

$ php artisan cipi:init-anonymize

Isso cria /home/{app_user}/.db/anonymization.json (permissões 0640) do modelo integrado. O arquivo vive fora do repositório Git - nunca é implantado com seu código. Usar --force para substituir um arquivo existente.

4. Edite a configuração para corresponder às suas tabelas reais e colunas confidenciais (consulte Configuração).

5. Verifique a fila e o correio: confirme se o trabalhador executa tarefas e Laravel pode enviar para o endereço que você vai passar POST /cipi/db (veja Notificações por e-mail).

$ 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. Acione sua primeira exportação anônima via HTTP ou CLI (veja exemplos abaixo).

Configuração

Caminhos válidos (vitórias na primeira partida):

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

O arquivo JSON possui duas chaves de nível superior: transformations (obrigatório) e options (opcional).

{
  "transformações": {
    "usuários": {
      "nome": "nome falso",
      "e-mail": "E-mail falso",
      "senha": "senha",
      "telefone": "número de telefone falso",
      "endereço": "endereço falso"
    },
    "ordens": {
      "notas_docliente": "parágrafo falso",
      "endereço_de_envio": "endereço falso"
    },
    "suporte_tickets": {
      "mensagem_do_usuário": "parágrafo falso",
      "agente_resposta": "parágrafo falso"
    }
  },
  "opções": {
    "hash_algoritmo": "automático",
    "preserve_ids": verdade,
    "faker_locale": "en_US"
  }
}

Abaixo transformations, cada chave é um nome da tabela. As chaves aninhadas são nomes de colunas; valores são tipos de transformação (não nomes brutos de métodos Faker - consulte tabela abaixo). Colunas não listados mantêm seus valores originais, para que você possa anonimizar as PII enquanto preservando chaves estrangeiras, enumerações e campos de lógica de negócios.

Transformações suportadas

Opções

HTTP API — pontos finais

Quando o anonimizador está desativado (CIPI_ANONYMIZER=false), rotas retornam 404 — os pontos finais ficam totalmente ocultos.

Exemplos práticos (curl)

Defina variáveis uma vez (substitua pelo domínio do seu aplicativo e token de .env):

exportar APP_URL="https://myapp.example.com"
exportar CIPI_ANONYMIZER_TOKEN="seu-token-do-env"

1. Coloque um trabalho de anonimato na fila

curl -sS -X POST "${APP_URL}/cipi/db" \
  -H "Autorização: Portador ${CIPI_ANONYMIZER_TOKEN}" \
  -H "Tipo de conteúdo: aplicativo/json" \
  -H "Aceitar: aplicativo/json" \
  -d '{"email": "desenvolvedor@example.com"}'

Resposta bem-sucedida (200):

{
  "estado": "na fila",
  "mensagem": "O trabalho de anonimato do banco de dados foi colocado na fila. Você receberá um e-mail com instruções de download quando concluído.",
  "e-mail": "desenvolvedor@exemplo.com"
}

A chamada HTTP retorna imediatamente com status: queued - isso faz não garantir que o e-mail de notificação foi enviado. O processamento pode levar minutos em bancos de dados grandes (trabalho tempo limite: 1 hora). A mensagem de conclusão vai apenas para o email no seu corpo JSON; se nada chega, verifique storage/logs/laravel.log para erros de transporte de correio, php artisan queue:failed por um trabalho fracassado, e isso MAIL_* está configurado (veja Notificações por e-mail).

2. Baixe o dump (do link do e-mail)

O e-mail de conclusão contém um URL como:

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

Salve-o com curl (cole o URL completo do e-mail – sem cabeçalho do 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

Retorno de links expirados ou inválidos 410 Gone ou 404. Solicite uma nova exportação com POST /cipi/db se a janela de 15 minutos passou.

3. Procure um ID de usuário por e-mail

Após o anonimato, os e-mails são falsos — mas IDs de usuário permanecem os mesmos. Use isto antes anonimato para mapear um e-mail de produção conhecido para um ID que você pode encontrar posteriormente no despejo:

curl -sS -X POST "${APP_URL}/cipi/db/usuário" \
  -H "Autorização: Portador ${CIPI_ANONYMIZER_TOKEN}" \
  -H "Tipo de conteúdo: aplicativo/json" \
  -d '{"email": "cliente@produção.com"}'

{
  "id_usuário": 42,
  "e-mail": "cliente@produção.com",
  "encontrado_em": "2026-06-10T14:22:01+00:00"
}

Isso consulta o live users tabela – execute somente quando você tiver permissão para tocar na produção dados. Não modifica nada.

4. Respostas de erro (solução de problemas)

CLI — execute sem HTTP

Para scripts, cron ou exportações únicas no servidor:

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

O comando imprime três etapas (despejar → transformar → salvar) e sai diferente de zero em caso de falha. Não enviar email – copie o arquivo via SCP ou seu próprio canal seguro.

Curl de comparação: Cipi API backup bruto

Para referência, um não anonimizado backup do servidor via Cipi API fica assim (host, token e semântica diferentes):

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

curl -sS -X POST "${CIPI_API_URL}/api/dbs/myapp_db/backup" \
  -H "Autorização: Portador ${CIPI_API_TOKEN}" \
  -H "Aceitar: aplicativo/json"

Isso retorna 202 com um job_id - enquete GET /api/jobs/{id} para o caminho de backup no servidor. O arquivo contém dados reais de produção; restringir acesse adequadamente.

Dicas de segurança e GDPR

• Loja CIPI_ANONYMIZER_TOKEN no gerenciamento de segredos – qualquer pessoa com ele pode enfileirar dumps e consulta /cipi/db/user
• Gire o token após mudanças de equipe: php artisan cipi:generate-token anonymize
• Desative quando não for necessário: php artisan cipi:service anonymize --disable (pontos finais retornam 404)
• Os links para download expiram em 15 minutos - encaminhe e-mails com cuidado
• Documente quais colunas são transformadas para sua DPA/política de privacidade
• Teste o dump: grep para um e-mail de produção conhecido - ele não deve aparecer se fakeEmail foi definido naquela coluna

Segurança

Cipi Agente usa defesa em profundidade: cada recurso tem seu próprio token de portador e pode ser desativado de forma independente. Quando desativado, as rotas retornam 404 (oculto, não 403).

Isolamento de token

Webhook verificação

• GitHub — X-Hub-Signature-256 HMAC-SHA256
• GitLab — X-Gitlab-Token comparação de cabeçalho

Código fonte e versões: github.com/cipi-sh/agent (MIT).

Variáveis ENV

Essas variáveis ​​são injetadas automaticamente por Cipi no aplicativo.env durante cipi app create. Alternar recursos opcionais com php artisan cipi:service {type} --enable|--disable ou configure-os manualmente.