Cipi Bedienfeld und API: was die beiden optionale Erweiterungen entsperren

Von Andrea Pollastri · Letzte Aktualisierung: 22. August 2026 · Kostenlose Lektüre, keine Paywall

Cipi ist und bleibt CLI-zuerst. Alles, was ein Server benötigt – Apps, Datenbanken, SSL, Bereitstellungen, Backups – ist eins cipi Befehl über SSH. Seit v4.7.0 können Sie zwei optionale Pakete hinzufügen: cipi/api und cipi/gui. Dieser Leitfaden erklärt, was sie gemeinsam freischalten — und warum keines von beiden Pflicht ist.

Zwei Erweiterungen, kein Lock-in

Cipi ist kein Panel, das ein CLI verbirgt. Es handelt sich um einen CLI, der, wenn Sie möchten, einen API und ein Armaturenbrett freilegt. Überspringen Sie beide Pakete und der Server läuft genau wie zuvor – kein zusätzlicher Daemon, keine Weboberfläche, nichts, was lauscht. Installieren Sie nur das, was Sie brauchen.

• cipi/api — ein Laravel-Paket (aktuelle Version 1.20), die REST verfügbar macht /api/*, ein MCP-Server bei /mcp und Swagger UI unter /docs.
• cipi/gui – ein self-hosted Laravel 12-Dashboard, das mit einem oder mehreren Servern kommuniziert nur durch diesen REST API. Es verfügt über keine proprietäre Steuerungsebene und speichert keinen verwalteten Serverstatus.

Alles, was Sie im Browser tun, können Sie über die Shell tun. Alles, was Sie über die Shell tun, können Sie über HTTP automatisieren. Bei beiden Paketen handelt es sich um Clients derselben Oberfläche, nicht um ein zweites Cipi.

Der API ist das Rückgrat

Enable the API before you touch the GUI. One command provisions Laravel under /opt/cipi/api, der Nginx vhost, SSL, eine SQLite-Warteschlange und cipi-queue.service:

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

Das Paket ist Serverebene Automatisierung – anders als die Cipi Agent (cipi/agent in jeder Laravel-App). Der Agent deckt Pro-App-Webhooks, Gesundheit und MCP ab. Der API deckt die ganze Box ab: Apps, Datenbanken, PHP, SSH, Dienste, SMTP, Healthchecks, IP-Whitelist.

PHP-FPM läuft als www-data und führt Cipi Befehle über sudo gegen eine explizite Whitelist in aus /etc/sudoers.d/cipi-api. Vault- und MariaDB-Passwörter bleiben in Cipi, nicht in PHP. Nachher cipi self-update, wenn /docs oder /mcp Rückgabe HTTP 500, cipi api fix-permissions repariert Speicher und SQLite-Besitz.

Was Sie mit den API machen können

Die OpenAPI-Oberfläche deckt den Lebenszyklus eines Cipi-Servers ab. Lesevorgänge erfolgen synchron; schreibt (erstellen, bearbeiten, löschen, bereitstellen, SSL, Aliase, www, Datenbanken) zurück 202 Accepted mit einem job_id.

Minimales Beispiel – Apps auflisten und Serverstatus lesen:

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

Erstellen Sie eine Laravel Octane App (asynchron, 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-Benutzeroberfläche unter https://api.example.com/docs ist der Spielplatz: Probieren Sie jede Operation mit demselben Token aus, überprüfen Sie die Anforderung/Antwort und die Jobtypen. Die Spezifikation lebt bei public/api-docs/openapi.json.

Sanctum tokens and granular abilities

Auth ist Laravel Sanctum. Jeder Token trägt einen oder mehrere Fähigkeiten: Ein CI-Token kann nur enthalten deploy-manage und apps-view; Ein Panel-Token benötigt den vollständigen Satz. cipi api token create liest die kanonische Liste aus dem Paket (dasselbe wie php artisan cipi:token-abilities).

Die Fähigkeiten umfassen Apps (Anzeigen/Erstellen/Bearbeiten/Löschen/Suspendieren/Basicauth/env/auth/artisan/run/deploy-config), Aliase, www, bereitstellen, SSL, Datenbanken, Status, MCP und – seit API 1.15+ — PHP, SSH, Dienste, SMTP, Gesundheit und IP-Whitelist. Widerrufen mit cipi api token revoke <id>. Verwenden Sie ein Token mit voller Funktionalität nicht in einer öffentlichen Pipeline wieder.

Asynchrone Jobs und Abfragen

Ein Deploy bzw db create lebt nicht in der HTTP-Anfrage: Die API stellt die Arbeit in die Warteschlange und kehrt zurück 202 + job_id. Umfrage GET /api/jobs/{id} für Status, CLI output und exit_code. Das ist das gleiche Overlay, das GUI zeigt, und die gleiche Schleife wie 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}"

Seit Cipi 4.6.3 Das API-Paket bietet jede Nacht um 04:30 Uhr Soft-Updates (cipi api update), sodass REST-Endpunkte und MCP-Tools ohne manuellen Schritt auf dem neuesten Stand bleiben.

MCP: Cipi innerhalb von Cursor, VS Code und Claude

Der MCP-Server bei /mcp (Streambar HTTP) wird angezeigt Über 50 Werkzeuge: apps, aliases, www, databases, deploy, SSL, Basic Auth, server cockpit, .env / auth.json / app-run / deploy-config, jobs, logs and ServerStatus. Ab API 1.11.1+ ein Token mit nur mcp-access reicht für jedes MCP-Tool – REST-Fähigkeiten pro Endpunkt werden nicht überprüft /mcp.

Cursorkonfiguration in ~/.cursor/mcp.json:

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

VS Code (Copilot) verwendet den gleichen HTTP-Transport; Claude Code fügt den Server mit hinzu claude mcp add --transport http; Claude Desktop geht durch mcp-remote. Protokollierungstools schwärzen allgemeine Geheimnisse, bevor sie zurückkehren. Dasselbe Protokoll ist auf der App-Seite das, was die In-App-Agent MCP belichtet – zwei Oberflächen, ein Standard.

Das UI-Panel als Multiserver-Cockpit

Das GUI ist eine dünne visuelle Schicht über dem API. Es lebt darin /opt/cipi/gui, es ist Laravel 12, und es behält keine lokalen Warteschlangenarbeiter: Es authentifiziert sich beim API jedes Servers, verteilt Jobs und fragt deren Status ab. Zerlegen Sie das Panel und bauen Sie es an anderer Stelle wieder auf, ohne einen verwalteten Server zu berühren.

Ein Login, viele Server. Registrieren Sie Endpunkt + Token für Produktions-, Staging- und Client-Boxen und wechseln Sie dann zwischen ihnen. Es ist das Cockpit, das Sie benötigen, wenn Sie mehr als eine VPS haben und nicht zehn SSH-Sitzungen geöffnet haben möchten.

Was Sie im Browser tun können

• Laravel und benutzerdefinierte Apps – Erstellen, Bearbeiten, Bereitstellen, Rollback, Entsperren, Anhalten/Aufheben der Suspendierung, Löschen. Octane (FrankenPHP) zum Erstellungszeitpunkt ab API 1.13+; Listen-/Detailansichten unterscheiden FPM von Octane.
• Aliase, WWW, SSL, Basic Auth – der gleiche Ablauf wie CLI, plus Force HTTPS und Apex/www-Weiterleitungen.
• .env, auth.json, Artisan, App-Befehle — Editor- und Terminalausgabe mit Markdown-Kopie (API 1.14+ / Cipi 5.0.3+).
• Mehrmotorige Datenbanken — wähle zum Zeitpunkt der Erstellung MariaDB oder PostgreSQL; Sicherung, Wiederherstellung und Passwortrotation über den Browser (API1.12+ / Cipi 4.8+).
• Protokolle — nginx, PHP-FPM, Laravel, worker, deploy: type filter, pagination, auto-refresh. Common secrets are redacted.
• Job-Overlay – Spinner und CLI-Ausgabe, während das Panel abfragt GET /api/jobs/{id}.
• Live-Dashboard – CPU-, Speicher-, Festplatten-, Dienste- und App-Anzahl über GET /api/status.

Server-Cockpit

Ab API 1.15+ / Cipi 5.0.6+ Das Panel verwaltet nicht nur Apps, sondern auch die Box.

• Installieren, entfernen und stellen Sie den Systemstandard PHP (8.3, 8.4, 8.5) ein.
• SSH-Schlüssel hinzufügen, umbenennen und widerrufen cipi Benutzer.
• Systemdienste auflisten und neu starten.
• Konfigurieren, testen, aktivieren und deaktivieren Sie SMTP-Benachrichtigungen (das Passwort wird bei GET nie zurückgegeben).
• Gesundheitschecks pro App für HTTP – erstellen, ausführen, entfernen.
• IP-Whitelist für das Panel API / MCP: eine Adresse oder CIDR pro Zeile, oder * alles zulassen.

That is the piece that makes the GUI a real alternative to a SaaS panel, without moving the source of truth off the server.

So installieren Sie sie

Erforderliche Reihenfolge: API auf jedem verwalteten Server, dann GUI überall dort, wo Sie den Browser haben möchten. Der GUI kann auf derselben Box oder auf einer kleinen dedizierten Maschine leben – es ist nur ein HTTP-Client.

# 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 fragt nach der ersten Administrator-E-Mail-Adresse und dem ersten Passwort (mindestens 12 Zeichen, Groß- und Kleinbuchstaben, Ziffer, Sonderzeichen, keine 4 identischen Zeichen hintereinander). Config landet in /etc/cipi/gui.json. PHP-FPM, Vhost und Scheduler kommen vom Installationsprogramm: Sie booten Laravel nicht manuell.

Aktualisierungen: cipi gui update / cipi api update für das tägliche Soft-Update; upgrade für einen kompletten Umbau. cipi gui refresh-theme Kompiliert nur das Thema neu. cipi gui remove deinstalliert Vhost, Pool und Scheduler – verwaltete Server bleiben intakt. cipi gui reset-user ist der Wiederherstellungspfad, wenn ein Administrator 2FA verliert.

SSL, 2FA und IP-Whitelist

Das Panel beginnt bei HTTP: Geben Sie Let's Encrypt sofort mit aus cipi gui ssl (automatische Verlängerung, dasselbe ACME wie App-Domains). Die Anmeldung erfolgt sitzungsbasiert; Jeder Administrator kann es aktivieren TOTP 2FA (Google Authenticator, 1Password, Aegis) aus ihrem Profil – Opt-in, nicht obligatorisch.

Beschränken Sie, wer mit API und MCP sprechen kann:

$ 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

Standarddatei: /etc/cipi/api-ip-whitelist mit * (alles zulassen). Abgelehnte Kunden erhalten 403. REST-Äquivalente leben unter /api/ip-whitelist; eine Einschränkung PUT fügt die IP des Anrufers automatisch hinzu, es sei denn ensure_client_ip: false.

Anwendungsfälle: Teams, Agenturen, Hosting, KI

• Freiberufler mit zwei VPS — API + cipi-cli vom Laptop. Der GUI ist optional; a prod und a staging Profil reichen aus.
• Ein Team, das nicht in SSH lebt – ein Panel, 2FA, Live-Dashboard, Artisan und Protokolle, ohne dass jeder Root erhalten muss.
• Multi-Client-Agentur — ein Login, N Server. Jede Box hat ihren eigenen Token; Durch das Löschen eines Clients wird ein Token widerrufen, nicht die Deinstallation von Cipi.
• Hosting mit Abrechnung – die WHMCS-Modul spricht das gleiche REST API: erstellen, SSL, bereitstellen, löschen im Produktlebenszyklus.
• KI-Agenten — Server MCP für Infrastruktur; In-App-Agent MCP für die Codebasis. Spezifikationen und Leitplanken im spezifikationsgesteuerter Leitfaden.

cipi-cli and WHMCS on the same wire

Die CLI Kunde ist eine Go-Binärdatei, die REST von Ihrem Laptop aus kommuniziert: Apps, Aliase, Bereitstellung, SSL, Datenbanken, globaler Status, Jobs. Gleiche Token, gleiche Multiserverprofile. Bevorzugen Sie das Terminal? Sie benötigen den GUI nicht. Bevorzugen Sie den Browser? Das brauchst du nicht cipi-cli. Benötigen Sie beides an verschiedenen Tagen? Gleiche API.

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

WHMCS ist der dritte offizielle Client: Hosting-Bereitstellung ohne Composer, Drop-in in den Modulordner. Keiner der drei ersetzt cipi auf dem Server – sie remoten es.

Häufig gestellte Fragen

Lesen Sie weiter