Panneau de commande Cipi et API : que sont les deux ? extensions facultatives débloquer

Par Andrea Pollastri · Dernière mise à jour : 22 août 2026 · lecture gratuite, pas de paywall

Cipi est et reste CLI-premier. Tout ce dont un serveur a besoin (applications, bases de données, SSL, déploiements, sauvegardes) n'en fait qu'un. cipi commande via SSH. Depuis la version 4.7.0, vous pouvez ajouter deux packages facultatifs : cipi/api et cipi/gui. Ce guide explique ce qu’ils débloquent ensemble et pourquoi ni l’un ni l’autre n’est requis.

Deux extensions, zéro verrouillage

Cipi n'est pas un panneau qui cache un CLI. Il s'agit d'un CLI qui, si vous le souhaitez, expose un API et un tableau de bord. Ignorez les deux packages et le serveur fonctionne exactement comme avant : pas de démon supplémentaire, pas de surface Web, rien d'écoute. Installez uniquement ce dont vous avez besoin.

• cipi/api — un package Laravel (version actuelle 1.20) qui expose REST à /api/*, un serveur MCP à /mcp et l'interface utilisateur Swagger sur /docs.
• cipi/gui — un tableau de bord self-hosted Laravel 12 qui communique avec un ou plusieurs serveurs seulement à travers ce REST API. Il n'a pas de plan de contrôle propriétaire et ne stocke aucun état du serveur géré.

Tout ce que vous faites dans le navigateur, vous pouvez le faire depuis le shell. Tout ce que vous faites depuis le shell, vous pouvez l'automatiser sur plus de HTTP. Les deux packages sont clients de la même surface, pas d'un second Cipi.

Le API est la colonne vertébrale

Activez le API avant de toucher le GUI. Un commandement prévoit Laravel sous /opt/cipi/api, le Nginx vhost, SSL, une file d'attente SQLite et cipi-queue.service:

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

Le paquet est au niveau du serveur automatisation - distincte de la Cipi Agent (cipi/agent à l'intérieur de chaque Laravel application). L'agent couvre les webhooks par application, la santé et MCP. Le API couvre l'ensemble : applications, bases de données, PHP, SSH, services, SMTP, contrôles de santé, liste blanche IP.

PHP-FPM fonctionne comme www-data et exécute Cipi commandes via sudo sur une liste blanche explicite dans /etc/sudoers.d/cipi-api. Les mots de passe du coffre-fort et MariaDB restent dans Cipi, pas dans PHP. Après cipi self-update, si /docs ou /mcp rendre HTTP 500, cipi api fix-permissions répare le stockage et la propriété SQLite.

Que pouvez-vous faire avec le API

La surface OpenAPI couvre le cycle de vie d'un serveur Cipi. Les lectures sont synchrones ; écrit (créer, modifier, supprimer, déployer, SSL, alias, www, bases de données) return 202 Accepted avec un job_id.

Exemple minimal : répertorier les applications et lire l'état du serveur :

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

Créez une application Laravel Octane (asynchrone, 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"
  }'

Interface utilisateur Swagger sur https://api.example.com/docs est le terrain de jeu : essayez chaque opération avec le même jeton, inspectez les requêtes/réponses et les types de tâches. La spécification vit à public/api-docs/openapi.json.

Jetons Sanctum et capacités granulaires

L'authentification est Laravel Sanctum. Chaque jeton porte un ou plusieurs capacités: un token CI ne peut contenir que deploy-manage et apps-view; un jeton de panneau a besoin de l'ensemble complet. cipi api token create lit la liste canonique du package (identique à php artisan cipi:token-abilities).

Les capacités couvrent les applications (view/create/edit/delete/suspend/basicauth/env/auth/artisan/run/deploy-config), les alias, www, déployer, SSL, les bases de données, le statut, MCP et — depuis API 1.15+ — PHP, SSH, services, SMTP, santé et liste blanche IP. Révoquer avec cipi api token revoke <id>. Ne réutilisez pas un jeton à pleine capacité dans un pipeline public.

Travaux asynchrones et sondages

Un déploiement ou db create n'habite pas dans la requête HTTP : le API met le travail en file d'attente et renvoie 202 + job_id. Sondage GET /api/jobs/{id} pour le statut, CLI output et exit_code. C'est la même superposition que les spectacles GUI et la même boucle 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}"

Depuis Cipi 4.6.3 le package API est mis à jour tous les soirs à 04h30 (cipi api update), afin que les points de terminaison REST et les outils MCP restent à jour sans étape manuelle.

MCP : Cipi à l'intérieur du curseur, VS Code et Claude

Le serveur MCP à /mcp (Streamable HTTP) expose 50+ outils: applications, alias, www, bases de données, déploiement, SSL, Basic Auth, cockpit serveur, .env / auth.json / app-run / deploy-config, jobs, logs and ServerStatus. À partir de API 1.11.1+ un jeton avec seulement mcp-access est suffisant pour chaque MCP outil — les capacités REST par point de terminaison ne sont pas vérifiées /mcp.

Configuration du curseur dans ~/.cursor/mcp.json:

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

VS Code (Copilot) utilise le même transport HTTP ; Claude Code ajoute le serveur avec claude mcp add --transport http; Claude Desktop passe par mcp-remote. Les outils de journalisation suppriment les secrets communs avant leur retour. Le même protocole, côté application, est ce que le Agent intégré à l'application MCP expose — deux surfaces, une norme.

Le panneau UI comme cockpit multi-serveur

Le GUI est une fine couche visuelle au-dessus du API. Il vit dans /opt/cipi/gui, il s'agit du Laravel 12 et il ne conserve aucun travailleur de file d'attente locale : il s'authentifie auprès du API de chaque serveur, répartit les tâches et interroge leur statut. Démontez le panneau et reconstruisez-le ailleurs sans toucher à un serveur géré.

Une connexion, plusieurs serveurs. Enregistrez le point de terminaison + le jeton pour les boîtes de production, de préparation et client, puis basculez entre eux. C'est le cockpit qu'il vous faut lorsque vous avez plus d'un VPS et que vous ne souhaitez pas ouvrir dix sessions SSH.

Ce que vous pouvez faire dans le navigateur

• Laravel et applications personnalisées - créer, modifier, déployer, restaurer, déverrouiller, suspendre/reprendre la suspension, supprimer. Octane (FrankenPHP) au moment de la création à partir de API 1.13+; les vues liste/détail distinguent FPM de Octane.
• Alias, WWW, SSL, authentification de base — le même flux que le CLI, plus les redirections forcées HTTPS et apex/www.
• .env, auth.json, Artisan, commandes d'application — sortie de l'éditeur et du terminal avec copie Markdown (API 1.14+ / Cipi 5.0.3+).
• Bases de données multimoteurs — choisissez MariaDB ou PostgreSQL au moment de la création ; sauvegarde, restauration et rotation des mots de passe depuis le navigateur (API1.12+ / Cipi 4.8+).
• Journaux — nginx, PHP-FPM, Laravel, worker, déployer : filtre de type, pagination, actualisation automatique. Les secrets communs sont expurgés.
• Superposition de tâches — spinner et sortie CLI pendant que le panneau interroge GET /api/jobs/{id}.
• Tableau de bord en direct - Nombre de processeurs, de mémoire, de disques, de services et d'applications via GET /api/status.

Poste de pilotage du serveur

À partir de API 1.15+ / Cipi 5.0.6+ le panel ne gère pas que les applications : il gère la box.

• Installez, supprimez et définissez la valeur par défaut du système PHP (8.3, 8.4, 8.5).
• Ajoutez, renommez et révoquez des clés SSH sur le cipi utilisateur.
• Répertoriez et redémarrez les services système.
• Configurez, testez, activez et désactivez les notifications SMTP (le mot de passe n'est jamais renvoyé sur GET).
• HTTP contrôles de santé par application : créer, exécuter, supprimer.
• Liste blanche IP pour la centrale API / MCP : une adresse ou CIDR par ligne, ou * pour permettre à tout.

C'est cet élément qui fait du GUI une véritable alternative à un panel SaaS, sans déplacer la source de vérité hors du serveur.

Comment les installer

Ordre requis : API sur chaque serveur géré, puis le GUI partout où vous souhaitez utiliser le navigateur. Le GUI peut vivre sur le même boîtier ou sur une petite machine dédiée — ce n'est qu'un client 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 demande le premier e-mail et le mot de passe de l'administrateur (minimum 12 caractères, majuscules, minuscules, chiffres, spéciaux, pas de 4 caractères identiques d'affilée). La configuration arrive /etc/cipi/gui.json. PHP-FPM, vhost et planificateur proviennent de l'installateur : vous ne démarrez pas Laravel à la main.

Mises à jour : cipi gui update / cipi api update pour la mise à jour logicielle quotidienne ; upgrade pour une reconstruction complète. cipi gui refresh-theme recompile uniquement le thème. cipi gui remove désinstalle le vhost, le pool et le planificateur – les serveurs gérés restent intacts. cipi gui reset-user est le chemin de récupération si un administrateur perd 2FA.

Liste blanche SSL, 2FA et IP

Le panneau démarre le HTTP : exécutez immédiatement Let's Encrypt avec cipi gui ssl (renouvellement automatique, même ACME que les domaines d'application). La connexion est basée sur la session ; chaque administrateur peut activer TOTP2FA (Google Authenticator, 1Password, Aegis) à partir de leur profil — opt-in, non obligatoire.

Limitez qui peut parler aux API et 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

Fichier par défaut : /etc/cipi/api-ip-whitelist avec * (permettre tout). Les clients rejetés obtiennent 403. Les équivalents REST vivent sous /api/ip-whitelist; une restriction PUT ajoute automatiquement l'adresse IP de l'appelant, sauf si ensure_client_ip: false.

Cas d'usage : équipes, agences, hébergement, IA

• Freelance avec deux VPS — API + cipi-cli depuis l'ordinateur portable. Le GUI est facultatif ; un prod et un staging le profil suffit.
• Une équipe qui ne vit pas en SSH — un panneau, 2FA, un tableau de bord en direct, Artisan et des journaux sans transmettre la racine à tout le monde.
• Agence multi-clients — une connexion, N serveurs. Chaque boîte a son propre jeton ; supprimer un client revient à révoquer un jeton, et non à désinstaller Cipi.
• Hébergement avec facturation — le Module WHMCS parle le même REST API : créer, SSL, déployer, supprimer sur le cycle de vie du produit.
• Agents IA — le serveur MCP pour l'infrastructure ; Agent intégré à l'application MCP pour la base de code. Spécifications et garde-corps dans le guide axé sur les spécifications.

cipi-cli et WHMCS sur le même fil

Le CLIclient est un binaire Go qui parle REST depuis votre ordinateur portable : applications, alias, déploiement, SSL, bases de données, statut global, tâches. Mêmes jetons, mêmes profils multi-serveurs. Vous préférez le terminal ? Vous n'avez pas besoin du GUI. Vous préférez le navigateur ? Vous n'avez pas besoin cipi-cli. Besoin des deux à des jours différents ? Même API.

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

WHMCS est le troisième client officiel : provisionnement d'hébergement sans Composer, drop-in dans le dossier modules. Aucun des trois ne remplace cipi sur le serveur - ils le distant.

Questions fréquemment posées

Continuez à lire