Panel de control Cipi y API: lo que los dos extensiones opcionales desbloquean

By Andrea Pollastri · Last updated: August 22, 2026 · free to read, no paywall

Cipi es, y permanece, CLI-primero. Todo lo que necesita un servidor (aplicaciones, bases de datos, SSL, implementaciones, copias de seguridad) es uno cipi comando sobre SSH. Desde v4.7.0 puedes agregar dos paquetes opcionales: cipi/api y cipi/gui. Esta guía trata sobre lo que desbloquean juntos y por qué no es necesario.

Dos extensiones, cero lock-in

Cipi no es un panel que oculta un CLI. Es un CLI que, si se quiere, deja al descubierto un API y un salpicadero. Omita ambos paquetes y el servidor se ejecutará exactamente como antes: sin demonios adicionales, sin superficie web, sin nada que escuche. Instala sólo lo que necesitas.

• cipi/api — un paquete Laravel (versión actual 1.20) that exposes REST at /api/*, an MCP server at /mcp and Swagger UI at /docs.
• cipi/gui — un panel self-hosted Laravel 12 que se comunica con uno o más servidores only a través de ese DESCANSO API. No tiene un plano de control propietario y no almacena ningún estado de servidor administrado.

Todo lo que hagas en el navegador, puedes hacerlo desde el shell. Cualquier cosa que hagas desde el shell, puedes automatizarla en más de HTTP. Ambos paquetes son clientes de la misma superficie, no un segundo Cipi.

La API es el eje

Habilite el API antes de tocar el GUI. Un comando dispone Laravel bajo /opt/cipi/api, el Nginx vhost, SSL, una cola SQLite y cipi-queue.service:

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

The package is server-level automation — distinct from the Cipi Agent (cipi/agent dentro de cada aplicación Laravel). El Agente cubre webhooks por aplicación, estado y MCP. El API cubre todo el cuadro: aplicaciones, bases de datos, PHP, SSH, servicios, SMTP, comprobaciones de estado, lista blanca de IP.

PHP-FPM runs as www-data y ejecuta Cipi comandos a través de sudo contra una lista blanca explícita en /etc/sudoers.d/cipi-api. Las contraseñas de Vault y MariaDB permanecen dentro de Cipi, no en PHP. después cipi self-update, if /docs or /mcp return HTTP 500, cipi api fix-permissions Repara el almacenamiento y la propiedad de SQLite.

Qué puedes hacer con la API

La superficie OpenAPI cubre el ciclo de vida de un servidor Cipi. Las lecturas son sincrónicas; escribe (crear, editar, eliminar, implementar, SSL, alias, www, bases de datos) devolver 202 Accepted with a job_id.

Ejemplo mínimo: enumerar aplicaciones y leer el estado del 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}"

Cree una aplicación Laravel Octane (asincrónica, 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 at https://api.example.com/docs es el patio de recreo: pruebe cada operación con el mismo token, inspeccione la solicitud/respuesta y los tipos de trabajo. La especificación vive en public/api-docs/openapi.json.

Tokens Sanctum y abilities granulares

La autenticación es Laravel Sanctum. Cada token lleva uno o más abilities: a CI token can hold only deploy-manage and apps-view; a panel token needs the full set. cipi api token create lee la lista canónica del paquete (igual que php artisan cipi:token-abilities).

Las capacidades cubren aplicaciones (ver/crear/editar/eliminar/suspender/basicauth/env/auth/artisan/run/deploy-config), alias, www, implementar, SSL, bases de datos, estado, MCP y – desde API. 1.15+ — PHP, SSH, servicios, SMTP, estado y lista blanca de IP. Revocar con cipi api token revoke <id>. No reutilice un token de capacidad total en una canalización pública.

Jobs asíncronos y polling

A deploy or db create no vive en la solicitud HTTP: el API pone en cola el trabajo y regresa 202 + job_id. Poll GET /api/jobs/{id} for status, CLI output and exit_code. Esa es la misma superposición que muestra GUI y el mismo bucle 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}"

Since Cipi 4.6.3 el paquete API se actualiza todas las noches a las 04:30 (cipi api update), por lo que los puntos finales REST y las herramientas MCP se mantienen actualizados sin un paso manual.

MCP: Cipi dentro del Cursor, VS Code y Claude

The MCP server at /mcp (Streamable HTTP) exposes 50+ tools: aplicaciones, alias, www, bases de datos, implementación, SSL, autenticación básica, cabina del servidor, .env / auth.json / app-run / deploy-config, jobs, logs and ServerStatus. From API 1.11.1+ a token with only mcp-access es suficiente para cada herramienta MCP: las capacidades REST por punto final no se verifican en /mcp.

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

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

VS Code (Copilot) utiliza el mismo transporte HTTP; Claude Code agrega el servidor con claude mcp add --transport http; Claude Desktop goes through mcp-remote. Las herramientas de registro ocultan secretos comunes antes de que regresen. El mismo protocolo, en el lado de la aplicación, es lo que in-app Agent MCP expone: dos superficies, un estándar.

El panel UI como cabina multiservidor

El GUI es una fina capa visual encima del API. vive en /opt/cipi/gui, es Laravel 12 y no mantiene trabajadores de cola locales: se autentica en el API de cada servidor, distribuye trabajos y sondea su estado. Derribe el panel y reconstrúyalo en otro lugar sin tocar un servidor administrado.

Un inicio de sesión, muchos servidores. Registre el punto final + el token para las cajas de producción, preparación y cliente, luego cambie entre ellas. Es la cabina que deseas cuando tienes más de un VPS y no quieres diez sesiones SSH abiertas.

Qué puedes hacer en el navegador

• Laravel and custom apps — crear, editar, implementar, revertir, desbloquear, suspender/reactivar, eliminar. Octane (FrankenPHP) en el momento de la creación desde API 1.13+; Las vistas de lista/detalle distinguen FPM de Octane.
• Aliases, WWW, SSL, Basic Auth — el mismo flujo que el CLI, más la fuerza HTTPS y las redirecciones apex/www.
• .env, auth.json, Artisan, App commands — editor y salida de terminal con copia Markdown (API 1.14+ / Cipi 5.0.3+).
• Multi-engine databases — elija MariaDB o PostgreSQL en el momento de la creación; copia de seguridad, restauración y rotación de contraseña desde el navegador (API 1.12+ / Cipi 4.8+).
• Logs — nginx, PHP-FPM, Laravel, trabajador, implementación: filtro de tipo, paginación, actualización automática. Los secretos comunes están redactados.
• Job overlay — ruleta y salida CLI mientras el panel sondea GET /api/jobs/{id}.
• Live dashboard — CPU, memoria, disco, servicios y recuento de aplicaciones a través de GET /api/status.

Server cockpit

From API 1.15+ / Cipi 5.0.6+ el panel no sólo gestiona las aplicaciones: gestiona la caja.

• Instale, elimine y configure el sistema predeterminado PHP (8.3, 8.4, 8.5).
• Agregue, cambie el nombre y revoque claves SSH en el cipi user.
• List and restart system services.
• Configure, pruebe, habilite y deshabilite las notificaciones SMTP (la contraseña nunca se devuelve en GET).
• HTTP controles de estado por aplicación: crear, ejecutar y eliminar.
• Lista blanca de IP para el panel API / MCP: una dirección o CIDR por línea, o * to allow all.

Ésa es la pieza que hace del GUI una alternativa real a un panel SaaS, sin mover la fuente de la verdad fuera del servidor.

Cómo instalarlas

Orden requerido: API en cada servidor administrado, luego GUI donde desee que esté el navegador. El GUI puede vivir en la misma caja o en una pequeña máquina dedicada; es solo un 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 el primer correo electrónico y contraseña del administrador (mínimo 12 caracteres, superior, inferior, dígito, especial, no 4 caracteres idénticos seguidos). La configuración aterriza en /etc/cipi/gui.json. PHP-FPM, vhost y el programador provienen del instalador: no inicia Laravel manualmente.

Updates: cipi gui update / cipi api update for the daily soft update; upgrade for a full rebuild. cipi gui refresh-theme recompiles the theme only. cipi gui remove desinstala vhost, pool y programador: los servidores administrados permanecen intactos. cipi gui reset-user es la ruta de recuperación si un administrador pierde 2FA.

SSL, 2FA and IP whitelist

El panel comienza en HTTP: emite Let's Encrypt inmediatamente con cipi gui ssl (renovación automática, mismo ACME que los dominios de aplicaciones). El inicio de sesión se basa en sesiones; cada administrador puede habilitar TOTP 2FA (Google Authenticator, 1Password, Aegis) desde su perfil: participación voluntaria, no obligatoria.

Restringir quién puede hablar con API y 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

Default file: /etc/cipi/api-ip-whitelist with * (allow all). Rejected clients get 403. REST equivalents live under /api/ip-whitelist; a restricting PUT agrega la IP de la persona que llama automáticamente a menos que ensure_client_ip: false.

Casos de uso: equipos, agencias, hosting, IA

• Freelancer with two VPS — API + cipi-cli desde la computadora portátil. El GUI es opcional; un prod and a staging profile are enough.
• A team that does not live in SSH — un panel, 2FA, panel en vivo, Artisan y registros sin entregar root a todos.
• Multi-client agency — un inicio de sesión, N servidores. Cada caja tiene su propia ficha; Dejar caer un cliente es revocar un token, no desinstalar Cipi.
• Hosting with billing — the WHMCS module Habla lo mismo REST API: crear, SSL, implementar, eliminar en el ciclo de vida del producto.
• AI agents — servidor MCP para infraestructura; Agente MCP en la aplicación para el código base. Especificaciones y barandillas en el spec-driven guide.

cipi-cli and WHMCS on the same wire

The CLI client es un binario de Go que habla REST desde su computadora portátil: aplicaciones, alias, implementación, SSL, bases de datos, estado global, trabajos. Mismos tokens, mismos perfiles multiservidor. ¿Prefieres la terminal? No necesitas el GUI. ¿Prefieres el navegador? no necesitas cipi-cli. ¿Necesitas ambos en días diferentes? Mismo API.

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

WHMCS es el tercer cliente oficial: aprovisionamiento de alojamiento sin Composer, acceso directo a la carpeta de módulos. Ninguno de los tres reemplaza cipi on the server — they remote it.

Preguntas frecuentes

Sigue leyendo