Pannello UI e API di Cipi: tutte le potenzialità delle due estensioni

Di Andrea Pollastri · Ultimo aggiornamento: 22 agosto 2026 · lettura gratuita, nessun paywall

Cipi è, e resta, CLI-first. Tutto ciò che un server richiede — app, database, SSL, deploy, backup — sta in un comando cipi via SSH. Dalla v4.7.0 puoi aggiungere due package opzionali: cipi/api e cipi/gui. Questa guida racconta cosa sbloccano insieme, e perché nessuno dei due è obbligatorio.

Due estensioni, zero lock-in

Cipi non è un pannello che nasconde una CLI. È una CLI che, se vuoi, espone un'API e una dashboard. La differenza non è cosmetica: salti entrambi i package e il server gira esattamente come prima — niente daemon extra, niente superficie web, niente in ascolto. Installi solo quello che ti serve.

• cipi/api — package Laravel (release corrente 1.20) che espone REST su /api/*, un server MCP su /mcp e Swagger UI su /docs.
• cipi/gui — dashboard Laravel 12 self-hosted che parla con uno o più server solo tramite quella REST API. Non ha un control plane proprietario e non tiene stato dei server gestiti.

Qualsiasi cosa fai nel browser, la puoi fare dalla shell. Qualsiasi cosa fai dalla shell, la puoi automatizzare via HTTP. I due package sono client della stessa superficie, non un secondo Cipi.

L'API è il filo conduttore

Prima di toccare la GUI, abilita l'API. Un comando provisiona Laravel in /opt/cipi/api, il vhost Nginx, SSL, una coda SQLite e cipi-queue.service:

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

Il package è automazione a livello server — distinta dal Cipi Agent (cipi/agent dentro ogni app Laravel). L'Agent serve webhook, health e MCP per-app. L'API serve il box intero: app, database, PHP, SSH, servizi, SMTP, healthcheck, IP whitelist.

PHP-FPM gira come www-data ed esegue i comandi Cipi via sudo con una whitelist esplicita in /etc/sudoers.d/cipi-api. Vault e password MariaDB restano dentro Cipi, non in PHP. Dopo un cipi self-update, se /docs o /mcp rispondono HTTP 500, cipi api fix-permissions ripara ownership di storage e database SQLite.

Cosa puoi fare con l'API

La superficie OpenAPI copre il ciclo di vita di un server Cipi. Le letture sono sincrone; le scritture (create, edit, delete, deploy, SSL, alias, www, database) rispondono 202 Accepted con un job_id.

Esempio minimo — elenco app e stato server:

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

Crea un'app Laravel Octane (async, 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"
  }'

Swagger UI su https://api.example.com/docs è il playground: prova ogni operazione con lo stesso token, vedi request/response e i tipi job. La spec vive in public/api-docs/openapi.json.

Token Sanctum e ability granulari

L'autenticazione è Laravel Sanctum. Ogni token ha una o più ability: un token da CI può avere solo deploy-manage e apps-view; un token da pannello deve coprire l'intero set. cipi api token create legge la lista canonica dal package (stessa di php artisan cipi:token-abilities).

Le ability coprono app (view/create/edit/delete/suspend/basicauth/env/auth/artisan/run/deploy-config), alias, www, deploy, SSL, database, status, MCP e — da API 1.15+ — PHP, SSH, servizi, SMTP, health e IP whitelist. Revoca con cipi api token revoke <id>. Non riusare un token full-ability in una pipeline pubblica.

Job asincroni e polling

Un deploy o un db create non sta nella request HTTP: l'API accoda il lavoro e risponde 202 + job_id. Interroga GET /api/jobs/{id} per stato, output CLI e exit_code. È lo stesso overlay che vedi nella GUI e lo stesso polling di 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}"

Da Cipi 4.6.3 il package API si aggiorna ogni notte alle 04:30 (cipi api update), così endpoint REST e tool MCP restano allineati senza un intervento manuale.

MCP: Cipi dentro Cursor, VS Code e Claude

Il server MCP su /mcp (Streamable HTTP) espone oltre 50 tool: app, alias, www, database, deploy, SSL, Basic Auth, cockpit server, .env / auth.json / app-run / deploy-config, job, log e ServerStatus. Da API 1.11.1+ un token con sola ability mcp-access basta per tutti i tool MCP — le ability REST per-endpoint non vengono verificate su /mcp.

Configurazione Cursor in ~/.cursor/mcp.json:

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

VS Code (Copilot) usa lo stesso trasporto HTTP; Claude Code si aggiunge con claude mcp add --transport http; Claude Desktop passa da mcp-remote. I tool di log redigono secret comuni prima di consegnare l'output. Lo stesso protocollo, lato app, lo espone l'Agent MCP — due superfici diverse, stesso standard.

Il pannello UI come cockpit multi-server

La GUI è un layer visuale sottile sopra l'API. Vive in /opt/cipi/gui, è Laravel 12, e non tiene queue worker locali: si autentica all'API di ogni server, spedisce job e ne interroga lo stato. Smonti il pannello e lo ricostruisci altrove senza toccare un server gestito.

Un login, tanti server. Registri endpoint + token per produzione, staging e i box dei clienti, poi passi dall'uno all'altro. È il cockpit che manca a chi ha più di una VPS e non vuole dieci sessioni SSH aperte.

Cosa puoi fare dal browser

• App Laravel e custom — crea, modifica, deploy, rollback, unlock, sospendi/riattiva, elimina. Octane (FrankenPHP) in creazione da API 1.13+; le viste list/detail distinguono FPM e Octane.
• Alias, WWW, SSL, Basic Auth — stesso flusso della CLI, con force HTTPS e redirect apex/www.
• .env, auth.json, Artisan, App commands — editor e output terminale con copia Markdown (API 1.14+ / Cipi 5.0.3+).
• Database multi-engine — scegli MariaDB o PostgreSQL alla creazione; backup, restore e rotazione password dal browser (API 1.12+ / Cipi 4.8+).
• Log — nginx, PHP-FPM, Laravel, worker, deploy: filtro tipo, paginazione, auto-refresh. I secret comuni sono redatti.
• Job overlay — spinner e output CLI mentre il pannello fa polling su GET /api/jobs/{id}.
• Dashboard live — CPU, memoria, disco, servizi e conteggio app via GET /api/status.

Server cockpit

Da API 1.15+ / Cipi 5.0.6+ il pannello non gestisce solo le app: gestisce il box.

• Installare, rimuovere e impostare il PHP di sistema (8.3, 8.4, 8.5).
• Aggiungere, rinominare e revocare chiavi SSH dell'utente cipi.
• Elencare e riavviare i servizi di sistema.
• Configurare, testare, abilitare e disabilitare le notifiche SMTP (la password non torna mai in GET).
• Healthcheck HTTP per app — crea, esegui, rimuovi.
• IP whitelist della panel API / MCP: un indirizzo o CIDR per riga, oppure * per consentire tutti.

È il pezzo che fa della GUI un'alternativa vera a un pannello SaaS, senza spostare la fonte di verità fuori dal server.

Come si installano

Ordine obbligatorio: API sul server gestito, poi GUI dove vuoi ospitare il browser. La GUI può vivere sullo stesso box o su una macchina dedicata piccola — è solo un client HTTP.

# su ogni server da gestire
$ cipi api api.example.com
$ cipi api ssl
$ cipi api token create

# sul box del pannello (può essere lo stesso)
$ cipi gui panel.example.com
$ cipi gui ssl

cipi gui chiede email e password del primo admin (minimo 12 caratteri, maiuscola, minuscola, cifra, speciale, niente 4 caratteri identici di fila). Config in /etc/cipi/gui.json. PHP-FPM, vhost e scheduler arrivano dall'installer: non monti Laravel a mano.

Aggiornamenti: cipi gui update / cipi api update per il soft update quotidiano; upgrade per un rebuild completo. cipi gui refresh-theme ricompila solo il tema. cipi gui remove disinstalla vhost, pool e scheduler — i server gestiti restano intatti. cipi gui reset-user è il recovery se un admin perde il 2FA.

SSL, 2FA e IP whitelist

Il pannello nasce in HTTP: emetti Let's Encrypt subito con cipi gui ssl (rinnovo automatico, stesso ACME delle app). Il login è session-based; ogni amministratore può attivare 2FA TOTP (Google Authenticator, 1Password, Aegis) dal profilo — opt-in, non obbligatorio.

Restringi chi parla con 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

File predefinito: /etc/cipi/api-ip-whitelist con * (consenti tutti). I client rifiutati ricevono 403. Gli equivalenti REST sono sotto /api/ip-whitelist; un PUT che restringe la lista aggiunge da solo l'IP del chiamante, salvo ensure_client_ip: false.

Casi d'uso: team, agenzie, hosting, AI

• Freelancer con due VPS — API + cipi-cli dal portatile. La GUI è opzionale; un profilo prod e uno staging bastano.
• Team che non vive in SSH — un pannello, 2FA, dashboard live, Artisan e log senza dare root a tutti.
• Agenzia multi-cliente — un login, N server. Ogni box ha il suo token; revocare un cliente è revocare un token, non smontare Cipi.
• Hosting con fatturazione — il modulo WHMCS parla la stessa REST API: create, SSL, deploy, delete sul ciclo di vita del prodotto.
• Agenti AI — MCP sul server per operazioni di infrastruttura; Agent MCP in-app per il codice. Spec e guardrail nella guida spec-driven.

cipi-cli e WHMCS sullo stesso filo

Il client CLI è un binario Go che parla REST dal portatile: app, alias, deploy, SSL, database, status globale, job. Stessi token, stessi profili multi-server. Preferisci il terminale? Non ti serve la GUI. Preferisci il browser? Non ti serve cipi-cli. Servono entrambi in giorni diversi? Stessa API.

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

WHMCS è il terzo client ufficiale: provisioning hosting senza Composer, drop-in nella cartella moduli. Nessuno dei tre sostituisce cipi sul server — lo remoto.

Domande frequenti

Continua a leggere