Cipi painel de controle e API: o que os dois extensões opcionais desbloquear

Por Andrea Pollastri · Última atualização: 22 de agosto de 2026 · grátis para ler, sem acesso pago

Cipi é, e permanece, CLI-primeiro. Tudo o que um servidor precisa — aplicativos, bancos de dados, SSL, implantações, backups — é um cipi comando sobre SSH. Desde a v4.7.0 você pode adicionar dois pacotes opcionais: cipi/api e cipi/gui. Este guia é sobre o que eles desbloqueiam juntos e por que nenhum deles é necessário.

Duas extensões, zero lock-in

Cipi não é um painel que esconde um CLI. É um CLI que, se quiser, expõe um API e um dashboard. Ignore ambos os pacotes e o servidor será executado exatamente como antes — sem daemon extra, sem superfície web, nada escutando. Instale apenas o que você precisa.

• cipi/api — um pacote Laravel (versão atual 1.20) que expõe REST em /api/*, um servidor MCP em /mcp e UI Swagger em /docs.
• cipi/gui — um painel self-hosted Laravel 12 que se comunica com um ou mais servidores apenas através desse REST API. Não possui plano de controle proprietário e não armazena estado de servidor gerenciado.

Tudo o que você faz no navegador, você pode fazer no shell. Qualquer coisa que você fizer a partir do shell, você pode automatizar mais de HTTP. Ambos os pacotes são clientes da mesma superfície, e não um segundo Cipi.

O API é a espinha dorsal

Habilite API antes de tocar em GUI. Um comando dispõe Laravel em /opt/cipi/api, o Nginx vhost, SSL, uma fila SQLite e cipi-queue.service:

$ cipi api api.example.com
$ cipi api ssl
$ cipi api token create

O pacote é nível de servidor automação - distinta da Cipi Agente (cipi/agent dentro de cada aplicativo Laravel). O Agente cobre webhooks por aplicativo, saúde e MCP. O API cobre toda a caixa: aplicativos, bancos de dados, PHP, SSH, serviços, SMTP, verificações de integridade, lista de permissões de IP.

PHP-FPM funciona como www-data e executa comandos Cipi via sudo contra uma lista de permissões explícita em /etc/sudoers.d/cipi-api. As senhas Vault e MariaDB ficam dentro de Cipi, não em PHP. Depois cipi self-update, se /docs ou /mcp retornar HTTP 500, cipi api fix-permissions repara o armazenamento e a propriedade do SQLite.

O que você pode fazer com o API

A superfície OpenAPI cobre o ciclo de vida de um servidor Cipi. As leituras são síncronas; escreve (criar, editar, excluir, implantar, SSL, aliases, www, bancos de dados) retornar 202 Accepted com um job_id.

Exemplo mínimo – listar aplicativos e ler o status do servidor:

export CIPI_API_URL="https://api.example.com"
export CIPI_API_TOKEN="1|your-sanctum-token"

curl -sS "${CIPI_API_URL}/api/apps" \
  -H "Authorization: Bearer ${CIPI_API_TOKEN}" \
  -H "Accept: application/json"

curl -sS "${CIPI_API_URL}/api/status" \
  -H "Authorization: Bearer ${CIPI_API_TOKEN}"

Crie um aplicativo Laravel Octane (assíncrono, API 1.13+ / Cipi 5.0+):

curl -sS -X POST "${CIPI_API_URL}/api/apps" \
  -H "Authorization: Bearer ${CIPI_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "shop.example.com",
    "repository": "git@github.com:you/shop.git",
    "branch": "main",
    "octane": true,
    "engine": "mariadb"
  }'

UI Swagger em https://api.example.com/docs é o playground: tente todas as operações com o mesmo token, inspecione a solicitação/resposta e os tipos de trabalho. A especificação reside em public/api-docs/openapi.json.

Tokens de Santuário e habilidades granulares

Auth é Laravel Sanctum. Cada token carrega um ou mais habilidades: um token CI pode conter apenas deploy-manage e apps-view; um token de painel precisa do conjunto completo. cipi api token create lê a lista canônica do pacote (o mesmo que php artisan cipi:token-abilities).

As habilidades abrangem aplicativos (visualizar/criar/editar/excluir/suspender/basicauth/env/auth/artisan/run/deploy-config), aliases, www, implantar, SSL, bancos de dados, status, MCP e — desde API 1.15+ — PHP, SSH, serviços, SMTP, integridade e lista de permissões de IP. Revogar com cipi api token revoke <id>. Não reutilize um token de capacidade total num pipeline público.

Trabalhos assíncronos e pesquisas

Uma implantação ou db create não reside na requisição HTTP: o API coloca o trabalho na fila e retorna 202 + job_id. Enquete GET /api/jobs/{id} para status, CLI output e exit_code. Essa é a mesma sobreposição que GUI mostra e o mesmo loop que cipi-cli jobs wait.

curl -sS -X POST "${CIPI_API_URL}/api/apps/myapp/deploy" \
  -H "Authorization: Bearer ${CIPI_API_TOKEN}"

curl -sS "${CIPI_API_URL}/api/jobs/JOB_ID" \
  -H "Authorization: Bearer ${CIPI_API_TOKEN}"

Desde Cipi 4.6.3 o pacote API é atualizado todas as noites às 04:30 (cipi api update), para que os endpoints REST e as ferramentas MCP permaneçam atualizados sem uma etapa manual.

MCP: Cipi dentro do Cursor, VS Code e Claude

O servidor MCP em /mcp (Streamable HTTP) expõe Mais de 50 ferramentas: aplicativos, aliases, www, bancos de dados, implantação, SSL, autenticação básica, cockpit do servidor, .env / auth.json / app-run / deploy-config, jobs, logs and ServerStatus. De API 1.11.1+ um token com apenas mcp-access é suficiente para cada ferramenta MCP — as habilidades REST por endpoint não são verificadas em /mcp.

Configuração do cursor em ~/.cursor/mcp.json:

{
  "mcpServers": {
    "cipi-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer 1|your-token"
      }
    }
  }
}

O VS Code (Copilot) usa o mesmo transporte HTTP; Claude Code adiciona o servidor com claude mcp add --transport http; Claude Desktop passa mcp-remote. As ferramentas de log editam segredos comuns antes que eles retornem. O mesmo protocolo, do lado do aplicativo, é o que o Agente no aplicativo MCP expõe – duas superfícies, um padrão.

O painel UI como um cockpit multiservidor

O GUI é uma fina camada visual sobre o API. Ele vive em /opt/cipi/gui, é Laravel 12 e não mantém nenhum trabalhador de fila local: ele autentica no API de cada servidor, despacha jobs e pesquisa seu status. Desmonte o painel e reconstrua-o em outro lugar sem tocar em um servidor gerenciado.

Um login, muitos servidores. Registre endpoint + token para caixas de produção, teste e cliente e alterne entre eles. É o cockpit que você deseja quando tem mais de um VPS e não quer dez sessões SSH abertas.

O que você pode fazer no navegador

• Laravel e aplicativos personalizados — criar, editar, implantar, reverter, desbloquear, suspender/cancelar a suspensão, excluir. Octane (FrankenPHP) no momento da criação a partir de API 1.13+; visualizações de lista/detalhe distinguem FPM de Octane.
• Aliases, WWW, SSL, autenticação básica — o mesmo fluxo que CLI, mais força HTTPS e redirecionamentos apex/www.
• .env, auth.json, Artisan, Comandos do aplicativo — saída do editor e terminal com cópia Markdown (API 1.14+ / Cipi 5.0.3+).
• Bancos de dados multimecanismo — escolha MariaDB ou PostgreSQL no momento da criação; backup, restauração e rotação de senha do navegador (API 1.12+ / Cipi 4.8+).
• Registros — nginx, PHP-FPM, Laravel, trabalhador, implantar: tipo filtro, paginação, atualização automática. Segredos comuns são redigidos.
• Sobreposição de trabalho — girador e saída CLI enquanto o painel pesquisa GET /api/jobs/{id}.
• Painel ao vivo — CPU, memória, disco, serviços e contagem de aplicativos via GET /api/status.

Cabine do servidor

De API 1.15+ / Cipi 5.0.6+ o painel não gerencia apenas os aplicativos: ele gerencia a caixa.

• Instale, remova e defina o padrão do sistema PHP (8.3, 8.4, 8.5).
• Adicione, renomeie e revogue chaves SSH no cipi usuário.
• Liste e reinicie os serviços do sistema.
• Configure, teste, habilite e desabilite notificações SMTP (a senha nunca é retornada em GET).
• HTTP verificações de integridade por aplicativo — crie, execute, remova.
• Lista branca de IP para o painel API / MCP: um endereço ou CIDR por linha, ou * para permitir tudo.

Essa é a peça que torna o GUI uma alternativa real a um painel SaaS, sem retirar a fonte da verdade do servidor.

Como instalá-los

Ordem necessária: API em cada servidor gerenciado, depois GUI onde você quiser o navegador. O GUI pode ficar na mesma caixa ou em uma pequena máquina dedicada — é apenas um cliente HTTP.

# on every server you will manage
$ cipi api api.example.com
$ cipi api ssl
$ cipi api token create

# on the panel box (can be the same machine)
$ cipi gui panel.example.com
$ cipi gui ssl

cipi gui solicita o primeiro e-mail e senha do administrador (mínimo 12 caracteres, superior, inferior, dígito, especial, sem 4 caracteres idênticos seguidos). Configuração chega /etc/cipi/gui.json. PHP-FPM, vhost e agendador vêm do instalador: você não inicializa Laravel manualmente.

Atualizações: cipi gui update / cipi api update para a atualização suave diária; upgrade para uma reconstrução completa. cipi gui refresh-theme recompila apenas o tema. cipi gui remove desinstala vhost, pool e agendador – os servidores gerenciados permanecem intactos. cipi gui reset-user é o caminho de recuperação se um administrador perder 2FA.

SSL, 2FA e lista de permissões de IP

O painel inicia em HTTP: emita Let's Encrypt imediatamente com cipi gui ssl (renovação automática, mesmo ACME dos domínios de aplicativos). O login é baseado em sessão; cada administrador pode ativar TOTP 2FA (Google Authenticator, 1Password, Aegis) em seu perfil – opcional, não obrigatório.

Restringir quem pode falar com API e MCP:

$ cipi api ip-whitelist add 203.0.113.10
$ cipi api ip-whitelist set --ips=203.0.113.0/24,2001:db8::/32
$ cipi api ip-whitelist show --json

Arquivo padrão: /etc/cipi/api-ip-whitelist com * (permitir tudo). Clientes rejeitados recebem 403. Equivalentes REST residem em /api/ip-whitelist; uma restrição PUT adiciona o IP do chamador automaticamente, a menos que ensure_client_ip: false.

Casos de uso: equipes, agências, hospedagem, IA

• Freelancer com dois VPS — API + cipi-cli do laptop. O GUI é opcional; um prod e um staging perfil são suficientes.
• Uma equipe que não vive em SSH — um painel, 2FA, painel ao vivo, Artisan e registros sem entregar root a todos.
• Agência multicliente — um login, N servidores. Cada caixa possui seu próprio token; descartar um cliente é revogar um token, não desinstalar Cipi.
• Hospedagem com cobrança - o Módulo WHMCS fala o mesmo REST API: criar, SSL, implantar, excluir no ciclo de vida do produto.
• Agentes de IA — servidor MCP para infraestrutura; Agente MCP no aplicativo para a base de código. Especificações e guarda-corpos no guia baseado em especificações.

cipi-cli e WHMCS no mesmo fio

O CLI cliente é um binário Go que fala REST do seu laptop: aplicativos, aliases, implantação, SSL, bancos de dados, status global, trabalhos. Os mesmos tokens, os mesmos perfis de vários servidores. Prefere o terminal? Você não precisa do GUI. Prefere o navegador? Você não precisa cipi-cli. Precisa de ambos em dias diferentes? Idem API.

$ cipi-cli api token add prod
$ cipi-cli prod apps list
$ cipi-cli prod deploy myapp
$ cipi-cli status

WHMCS é o terceiro cliente oficial: provisionamento de hospedagem sem Composer, direto para a pasta de módulos. Nenhum dos três substitui cipi no servidor – eles o remotam.

Perguntas frequentes

Continue lendo