cipi api

Cipi can optionally enable a REST API layer on the server via cipi api <domain>. It is powered by the Laravel package cipi/api (current release 1.34.0. node_build on app create and repository_access in the job results need Cipi 5.6.0+; disk usage needs Cipi 5.5.2+ so the API sudoers allow cipi disk; soft disk limits and Cloudflare DNS-01 accounts need 5.5.0+, and http / wildcard: false on SSL install need 5.5.1+. Redirects, proxies and Node restart still need 5.4.1+), which exposes:

  • REST API — apps (including Octane and Node create, .env, auth.json, Artisan, whitelisted app run, deploy-config, fix-permissions, resource limits and the soft disk limit), aliases, www redirects, app and path redirects, prefix proxies, Node runtimes, deploy and the deploy audit ledger, SSL (HTTP-01 or Cloudflare DNS-01 / wildcard), multi-engine databases, Meilisearch, app logs, disk usage, an app's cipi.yml (plan, apply, auto-apply; API 1.35+ / Cipi 5.6.4+), server status (/api/*)
  • MCP server — 73 tools at /mcp (Streamable HTTP)
  • Read-only host insights — optional packages, system monitor, Cloudflare Zero Trust status (API 1.31+) and disk usage per app and per database (API 1.33+ / Cipi 5.5.2+)
  • Server cockpit — PHP install/switch, SSH keys, services, SMTP, healthchecks, IP whitelist (API 1.15.0+ / Cipi 5.0.6+)
  • Swagger UI — interactive reference at /docs

Requires PHP 8.3+ and Laravel 12.41+ or 13 on the panel host (API 1.32+). This is server-level automation — distinct from the per-app Cipi Agent package (cipi/agent on each Laravel app).

A domain of its own

The API is not installed inside an app. It is a separate Laravel application with its own Nginx vhost and its own certificate, so it needs a domain or subdomain that only the API uses. Pick a subdomain such as api.example.com and create a DNS A record (and AAAA for IPv6) that points it at the server, before you run cipi api <domain>: since 5.8.2 the command checks the DNS first and stops, with the record to create, when the name does not resolve or points elsewhere (the Cloudflare proxy counts as pointing here; --skip-dns-check behind a NAT or proxy it cannot see through). It then installs the API, issues the Let's Encrypt certificate (--no-ssl to skip) and, on a terminal, offers to create the first token (--no-token to skip). cipi api ssl and cipi api move run the same DNS check.

What Example domain Set up with
Your app example.com, www.example.com cipi app create, cipi alias add
Panel API + MCP api.example.com cipi api api.example.com
Control panel (GUI) panel.example.com cipi gui panel.example.com

The three can live on the same server and under the same registered domain: what matters is that each hostname belongs to one of them only. Since Cipi 5.7.0, Cipi refuses any overlap. cipi api and cipi api move will not take the domain or an alias of an app, or the GUI's domain. In the other direction, cipi app create, cipi app edit --domain, cipi alias add, cipi app clone, cipi sync import and cipi.yml aliases will not take the API's or the GUI's domain.

API on an app's domain (before 5.7.0): Nginx ends up with two vhosts with the same server_name, serves only one of them, and the two certificates fight over the same lines. cipi api status now warns when this is the case. Fix it with cipi api move api.example.com; the app's certificate is left alone.

The cipi/api package

On a normal Cipi server you never install the package manually — cipi api <domain> provisions Laravel at /opt/cipi/api, Nginx, SSL, SQLite job queue, and cipi-queue.service. For reference or custom setups:

bash
composer require cipi/api
php artisan vendor:publish --tag=cipi-config
php artisan vendor:publish --tag=cipi-assets
php artisan migrate
php artisan cipi:seed-api-user
php artisan cipi:token-create

Panel .env uses CIPI_APPS_JSON=/etc/cipi/apps.json (or apps-public.json projection for non-sensitive fields). Token abilities are defined in config/cipi.php — list them with php artisan cipi:token-abilities (same list as cipi api token create since Cipi 4.6.3).

Source and changelog: github.com/cipi-sh/api (MIT). Client wrappers: cipi-cli and the PHP SDK (cipi/sdk).

Commands

bash
cipi api <domain>           # DNS check, install, certificate, token — one command (--no-ssl --no-token --skip-dns-check)
cipi api ssl                  # (re)issue the Let's Encrypt certificate (--skip-dns-check)
cipi api move <domain>      # move to another domain: old certificate out, new one in
cipi api remove               # uninstall API + MCP, tokens, vhost, crons and certificate
cipi api token list           # list tokens
cipi api token create         # create a new token (choose abilities)
cipi api token create --name=ci --full-access   # v5.9.0+ a token that may do everything
cipi api token create --name=ci --abilities=apps-view,deploy-manage --expires=2027-06-30
cipi api token revoke <id>    # revoke a token
cipi api status               # Laravel + cipi-api versions, queue worker, pending jobs, FPM pool
cipi api fix-permissions      # repair panel storage/database ownership (www-data)
cipi api update               # soft update: composer update on Laravel and API packages
cipi api upgrade              # full rebuild with rollback at /opt/cipi/api.old

Changing the API domain — cipi api move

Installed the API on the wrong domain, or rebranding? Move it. The Laravel app, tokens, job history and IP whitelist stay exactly as they are; only the address changes.

bash
cipi api move api.newdomain.com            # move and issue the new certificate
cipi api move api.newdomain.com --no-ssl   # move now, certificate later (cipi api ssl)
  1. Point the new domain at the server first (DNS A/AAAA record): Let's Encrypt checks it over port 80.
  2. cipi api move rewrites the Nginx vhost for the new domain. If nginx -t rejects it, the old vhost goes back and nothing else changes.
  3. It updates /etc/cipi/api.json and APP_URL, and restarts cipi-queue.
  4. SSL: it deletes the old domain's certificate, including any -0001 copies certbot made, so nothing renews a domain the server no longer serves. Then it issues a certificate for the new domain. If that fails (DNS not propagated yet, port 80 closed), the API is already on the new domain over HTTP: fix the cause and run cipi api ssl. A certificate that an app still uses is never deleted.

Then update the URL in every client of the server: the server's entry in the GUI (Connections), the cipi-cli profile, the PHP SDK configuration and MCP clients (https://api.newdomain.com/mcp). Tokens keep working.

Running cipi api <other-domain> on a server whose API is already configured stops and points you to cipi api move. Before 5.7.0 it silently changed domain, lost the HTTPS configuration and left the old certificate renewing.

Removing the API — cipi api remove

Uninstalls everything cipi api <domain> set up. Your apps, databases and the GUI are untouched. uninstall is an alias, and --force skips the confirmation.

bash
cipi api remove
cipi api remove --force

It removes:

  • the cipi-queue worker
  • the Nginx vhost and the PHP-FPM pool
  • the scheduler, maintenance and nightly update crons
  • the Let's Encrypt certificate of the API domain
  • /opt/cipi/api, /opt/cipi/api.old and the upgrade backups
  • api.json, the IP whitelist and the API logs

All tokens die with it, so GUI panels, cipi-cli and MCP clients that use this server lose access. The www-data sudoers whitelist (/etc/sudoers.d/cipi-api) stays, because it is part of every Cipi install. Reinstall any time with cipi api <domain>: you get a new, empty token database.

Panel API troubleshooting

After cipi self-update, root-owned files under /opt/cipi/api or /opt/cipi/gui can prevent PHP-FPM (www-data) from writing logs or the SQLite job database — the browser shows a bare HTTP 500 on /docs or /mcp. Cipi normally repairs ownership automatically during self-update (migration 5.0.13+ reclaims API/GUI ownership); if problems persist:

bash
cipi api fix-permissions   # chown storage, database, bootstrap/cache, .env → www-data
cipi api status              # confirm Laravel version, queue worker, pending jobs

The panel's Backups tab says "not configured" on a server where backups run. The tab shows what cipi backup status --json answers when the API runs it. Compare on the server, as root:

bash
ls -l /etc/cipi/backup.json                                             # the file `cipi backup configure` writes
sudo -u www-data sudo -n /usr/local/bin/cipi backup status --json | head -c 300   # exactly what the panel runs

No file: backups were configured on another server, or never with cipi backup configure. "configured": true from the second command: the server is fine and the answer is lost on the way — panel 4.2.1 and API 1.39.1 show the error instead of "not configured" (cipi api update, cipi gui update). sudo asking for a password: /etc/sudoers.d/cipi-api does not list the backup commands — the migration of Cipi 5.9.0 writes them.

cipi api status prints the installed Laravel and cipi/api package versions, whether cipi-queue.service is active, pending async jobs in the panel SQLite database, and PHP-FPM pool stats for the API vhost (including slow requests when configured). cipi api update soft-updates the panel API package from Packagist (since 5.0.15; migration drops stale VCS repo entries). cipi api upgrade performs a full rebuild with rollback at /opt/cipi/api.old. Since 5.0.14–5.0.17, self-update uses timed GitHub tarballs and Packagist dist installs instead of blocking Composer VCS clones for API and GUI packages. Since 5.0.18, GUI upgrade/update avoids Composer symlinks that break PHP-FPM open_basedir (HTTP 500); run cipi gui fix-permissions or cipi self-update to repair existing panels.

Since v4.7.18 (migrations 4.7.15–4.7.18), Panel API failures on Ubuntu 25.10+ / 26.04 are fixed end-to-end: sudo-rs rejects cipi db restore * * wildcards (the whole sudoers file was ignored — I'm afraid I can't do that), so the whitelist uses trailing * only; sourcing common.sh no longer aborts read-only commands when /etc/cipi is remounted read-only; API open_basedir includes /usr/local/bin/ for log helpers; and cipi db list shows empty databases and surfaces vault/MariaDB errors. Run cipi self-update to apply.

Token creation and granular permissions

Authentication uses Sanctum. Each token can have one or more abilities that limit allowed operations:

  • apps-view — read apps
  • apps-create — create apps
  • apps-edit — edit apps (PHP, repository, branch, primary domain since API 1.9.0+ / Cipi 4.6.2+)
  • apps-suspend — suspend and unsuspend apps
  • apps-basicauth — enable, disable, and inspect HTTP Basic Auth on apps (API 1.10.0+)
  • apps-env — list/merge app .env keys (API 1.14.0+ / Cipi 5.0.3+)
  • apps-auth — manage shared Composer auth.json (API 1.14.0+; distinct from apps-basicauth)
  • apps-artisan — run Artisan as an async job (API 1.14.0+)
  • apps-run — whitelisted non-interactive app run (API 1.14.0+)
  • apps-deploy-config — structured Deployer recipe options (API 1.14.0+)
  • php-view — list installed PHP versions (API 1.15.0+)
  • php-manage — install PHP versions (API 1.15.0+; install-only since 1.19.0 — removing a version or switching the default stays on the CLI)
  • ssh-view — list SSH keys on the cipi user (API 1.15.0+)
  • ssh-manage — add/remove/rename SSH keys (API 1.15.0+)
  • services-view — list system services (API 1.15.0+)
  • services-manage — restart services (API 1.15.0+)
  • smtp-view — read SMTP notification settings (password never returned; API 1.15.0+)
  • smtp-manage — configure, enable, disable, test, delete SMTP (API 1.15.0+)
  • health-view — list healthchecks (API 1.15.0+)
  • health-manage — set, unset, and run healthchecks per app (API 1.15.0+)
  • ip-whitelist-view — read panel API / MCP IP allowlist (API 1.15.0+)
  • ip-whitelist-manage — edit IP allowlist entries (API 1.15.0+)
  • redirects-view / redirects-manage — read and change whole-app and path redirects (API 1.31.0+ / Cipi 5.4.1+)
  • proxies-view / proxies-manage — read and change prefix reverse proxies (API 1.31.0+ / Cipi 5.4.1+)
  • node-view — Node runtimes and per-app Node status; node-manage — blue/green restart of an SSR app (API 1.31.0+ / Cipi 5.4.1+)
  • search-view — Meilisearch status; search-manage — enable or disable search per Laravel app (API 1.31.0+ / Cipi 5.2.2+)
  • packages-view, monitor-view, zt-view — read-only host package catalog, system monitor and Cloudflare Zero Trust status (API 1.31.0+)
  • disk-view — disk usage of the server, every app and every database (API 1.33.0+ / Cipi 5.5.2+). A token created before 1.33 does not have it.
  • node-runtimes-manage — install, upgrade and remove Node runtimes and change the server default; backups-view — read backup destinations (never their keys), profiles, last runs and stored archives; backups-manage — create, edit, pause, run and verify backup profiles (API 1.39.0+ / Cipi 5.9.0+). A token created before 1.39 with a list of abilities has none of the three; a full-access token has them already.
  • yml-view — read an app's cipi.yml status and plan; yml-manage — apply it and turn auto-apply on or off (API 1.35.0+ / Cipi 5.6.4+). A token created before 1.35 has neither.
  • apps-delete — delete apps
  • deploy-manage — deploy, rollback, unlock, and read the deploy audit ledger (API 1.31.0+ / Cipi 5.4.0+)
  • ssl-manage — install and manage SSL certificates
  • aliases-view — read aliases
  • aliases-create — add aliases
  • aliases-delete — remove aliases
  • www-manage — www/apex counterpart and redirects (API 1.12.0+ / Cipi 4.8+)
  • dbs-view — list databases
  • dbs-create — create databases
  • dbs-manage — backup, restore, regenerate password, install an engine
  • status-view — read server status snapshot (GET /api/status, API 1.11.6+)
  • mcp-access — access the MCP server

Since Cipi 4.6.3 / API 1.11.7+, cipi api token create reads the canonical ability list from the panel API package (same entries as php artisan cipi:token-abilities on the server). Migration 4.6.3 retrofits existing servers with the updated list (including status-view, apps-suspend, and apps-basicauth). API 1.19.0 removed dbs-delete along with the endpoints it guarded.

Full access (Cipi 5.9.0, API 1.39.0): cipi api token create --full-access — or f in the checklist — creates a token with the wildcard ability * instead of a list. It passes every ability check, REST and MCP, and keeps passing for the abilities later versions add, which a token holding today's whole list does not get. It is the token for something that is meant to do everything — the panel, your own automation; a CI pipeline that only deploys is still better served by deploy-manage alone. --name=, --abilities=a,b and --expires=YYYY-MM-DD create a token without the prompts.

REST endpoints

All endpoints require the Authorization: Bearer <token> header. Write operations (create, edit, delete, deploy, rollback, unlock, SSL, alias, www, database) are asynchronous: they return 202 Accepted with a job_id to poll via GET /api/jobs/{id} — with the ability the job was created under (apps-create for an app create, dbs-manage for a database password, …; API 1.36.1+ — before, any token could read any job by id). Read-only endpoints such as GET /api/dbs, GET /api/dbs/engines, GET /api/status, GET /api/apps/{name}/www, and GET /api/apps/{name}/logs (API 1.11.9+), GET /api/php, GET /api/ssh/keys, GET /api/services, GET /api/smtp, GET /api/health, GET /api/ip-whitelist (API 1.15.0+ / Cipi 5.0.6+), and the API 1.31.0 additions — redirects, proxies, GET /api/node, the deploy audit, search, packages, monitor and Zero Trust — are synchronous. Since API 1.32.0, GET /api/apps/{name}/limits and GET|PUT|DELETE /api/ssl/dns are synchronous too (PUT on limits is the async job app-limits). Since API 1.33.0, GET /api/disk and GET /api/disk/dbs are synchronous and measured on request. Since API 1.35.0, GET /api/apps/{name}/yml and POST /api/apps/{name}/yml/auto/enable|disable are synchronous; POST /api/apps/{name}/yml/apply is the async job app-yml-apply. POST /api/apps accepts optional custom (boolean) and docroot (string) parameters for creating custom apps with classic deployment. The repository field is required for Laravel apps and optional for custom apps: omit it (or send empty) to provision an SFTP-only site aligned with Cipi v4.5.1+. When no repository is set, branch is omitted. Since API 1.12.0+ / Cipi 4.8+, Laravel app create also accepts optional engine (mariadb or pgsql) to pick the database engine. Since API 1.13.0+ / Cipi 5.0+, Laravel app create accepts optional octane (true or "frankenphp") to provision Laravel Octane (FrankenPHP); octane is rejected when custom is set. The MCP tool AppCreate follows the same rules. Since API 1.36.0+ (MCP server 1.6.0) / Cipi 5.8.0+, app create and PUT /api/apps/{name} also accept env — the app's environment label (^[a-z0-9][a-z0-9_-]{0,31}$, default production), the same as cipi app create --env / cipi app edit --env — and app objects return it; it decides which cipi-<env>.yml the app reads. Keep the API package current with cipi api update / cipi api upgrade so validation and OpenAPI match this behavior.

POST /api/apps/{name}/suspend takes an app offline by swapping its Nginx vhost for a generic HTTP 503 maintenance page (HTTPS included) without deleting it, while POST /api/apps/{name}/unsuspend restores the normal vhost. Both require the apps-suspend ability and return 409 if the app is already in the target state. The suspended flag survives vhost regeneration and is exposed on GET /api/apps and GET /api/apps/{name}. These endpoints require the API package 1.8.1+ and Cipi 4.5.8+ on the server.

PUT /api/apps/{name} accepts an optional domain field to rename the app’s primary domain. Since API 1.15.0+ / Cipi 5.0.6+, the endpoint only forwards fields that differ from the current app (prevents no-op webhook or deploy-key recreation when PHP or branch are unchanged). PHP must be installed on the host (422 otherwise). The API validates the format synchronously and returns 409 if the domain is already used by another app (aliases of the current app are allowed, so promoting an alias to primary works). Requires the API package 1.9.0+ and Cipi 4.6.2+. The MCP tool AppEdit accepts the same domain parameter.

GET /api/apps and GET /api/apps/{name} expose boolean suspended and basic_auth flags per app (from apps.json). Since API 1.12.0+ they also expose engine, www_redirect, and force_https from apps-public.json / apps metadata. Since API 1.13.0+ they expose octane and octane_port for Octane apps. Since API 1.36.0+ / Cipi 5.8.0+ they expose env, the environment label (production for every app that never set one).

HTTP Basic Auth endpoints under /api/apps/{name}/basicauth/* wrap cipi basicauth synchronously — they do not return a job_id. Enable accepts optional user and password (auto-generated when omitted; returned once in the response). Requires the apps-basicauth ability and API package 1.10.0+. This is distinct from Composer auth.json management — see cipi basicauth.

WWW / apex endpoints under /api/apps/{name}/www/* wrap cipi www (API 1.12.0+ / Cipi 4.8+). GET …/www is synchronous and returns primary, apex, www, and redirect. POST …/www/add, …/force-to-root, …/force-from-root, and …/clear are async jobs. Requires the www-manage ability. MCP tools: WwwStatus, WwwAdd, WwwForceToRoot, WwwForceFromRoot, WwwClear.

POST /api/apps/{name}/ssl/force re-applies the HTTP → HTTPS redirect without issuing a new certificate (cipi ssl force). Requires ssl-manage and API 1.12.0+. MCP tool: SslForce.

GET /api/dbs lists databases synchronously by running sudo cipi db list on the host (same as the server CLI). Optional query engine=mariadb|pgsql filters by engine (API 1.12.0+ / Cipi 4.8+). GET /api/dbs/engines lists installed engines and the server default (sync; MCP DbEngines). Other /api/dbs/* write operations are asynchronous jobs and accept optional engine on create, delete, backup, restore, and password. Database commands require Cipi 4.4.17+ on the server (cipi db … entries in the API sudoers whitelist); multi-engine support needs Cipi 4.8+.

POST /api/apps/{name}/webhook/recreate recreates the GitHub/GitLab deploy webhook; optional body { "rotate_secret": true } also rotates CIPI_WEBHOOK_TOKEN in apps.json and shared/.env. Async job (app-webhook-recreate; ability apps-edit; CLI cipi app webhook recreate [--rotate-secret]; API 1.15.0+ / Cipi 5.0.6+). MCP: AppWebhookRecreate.

PHP management (API 1.15.0+ / Cipi 5.0.6+): GET /api/php lists installed versions (sync; ability php-view). POST /api/php/install and DELETE /api/php/{version} install or remove a version (async; php-manage). Installable versions are 8.3, 8.4, 8.5. MCP: PhpList.

DB engines — POST /api/dbs/engines/install (ability dbs-manage; API 1.15.0+).

Removed in API 1.19.0: DELETE /api/php/{version}, PUT /api/php/default, DELETE /api/dbs/{name} (and MCP DbDelete) and PUT /api/dbs/engines/default. Removing PHP, switching the default PHP or engine, and dropping a database are destructive host operations — run cipi php remove|switch, cipi db delete and cipi db default on the server.

SSH keys — GET|POST /api/ssh/keys, DELETE /api/ssh/keys/{n} (abilities ssh-view / ssh-manage; API 1.15.0+).

Services — GET /api/services, POST /api/services/{name}/restart (abilities services-view / services-manage; API 1.15.0+).

SMTP — GET|PUT|DELETE /api/smtp, POST /api/smtp/enable|disable|test (abilities smtp-view / smtp-manage; password never returned on GET; API 1.15.0+ / Cipi 5.0.6+ non-interactive cipi smtp configure --host=…).

Healthchecks — GET /api/health, GET|PUT|DELETE /api/apps/{name}/health, POST /api/apps/{name}/health/check (abilities health-view / health-manage; API 1.15.0+).

IP whitelist — middleware cipi.ip on api/* and /mcp reads /etc/cipi/api-ip-whitelist (missing file or * = allow all). Rejected clients get 403 { "error": "IP not allowed", "ip": "…" }. REST: GET /api/ip-whitelist, PUT /api/ip-whitelist (entries, optional ensure_client_ip), POST /api/ip-whitelist (ip), DELETE /api/ip-whitelist (ip), POST /api/ip-whitelist/allow-all (abilities ip-whitelist-view / ip-whitelist-manage; CLI cipi api ip-whitelist; API 1.15.0+ / Cipi 5.0.6+). MCP: IpWhitelistShow. Since 5.8.5 the list is replaced by an atomic rename (temporary file next to /etc/cipi/api-ip-whitelist, never a cross-device mv that removes the live file first), and a read-only /etc/cipi gets the vault's remount attempt, then one error naming the cause — a root the kernel remounted read-only, or a caller inside a systemd unit sandboxed with ProtectSystem= / ReadOnlyPaths=, named from its cgroup — instead of mv: inter-device move failed … Read-only file system in the panel's IP tab. show never aborts on a read-only directory (missing file = allow all).

GET /api/status returns the same structured JSON as cipi status (system, resources, services, PHP pools, app count). Since API 1.39.1 system.api is the installed cipi/api release, next to system.cipi: the panel (4.2.1+) shows both on the Server page. Since API 1.11.8+ the endpoint prefers sudo cipi status on the host and falls back to direct host reads when sudo is unavailable. Since API 1.12.1+ the host-read fallback includes postgresql when the systemd unit is installed (matching Cipi 4.8+). Requires the status-view ability (API 1.11.6+). The MCP tool ServerStatus returns the same payload and requires only mcp-access. From your laptop, use cipi-cli status for a global overview across all configured server profiles, or detail for one profile.

GET /api/apps/{name}/logs returns synchronous, paginated log snapshots for nginx, PHP-FPM, Laravel (when present), worker, and deploy logs — the REST counterpart to cipi app logs and cipi-cli apps logs. Query params: type (default all), page (default 1, most recent first), per_page (default 50, max 1000). Requires the apps-view ability and API package 1.11.9+. Log text is redacted for common secrets (same policy as MCP AppLogs since API 1.11.5+).

Redirects (API 1.31.0+) wrap cipi redirect synchronously: the CLI validates the rule, regenerates the vhost, runs nginx -t and reverts on failure. GET /api/apps/{name}/redirects returns the whole-app redirect and the path redirects (redirects-view). PUT /api/apps/{name}/redirect with { "to", "code"?, "keep_path"? } sends every hostname of the app to the target in one hop; POST …/redirect/enable and …/redirect/disable toggle it without forgetting the target; DELETE …/redirect removes it. POST /api/apps/{name}/redirects with { "from", "to", "code"?, "keep_path"? } adds or updates a path redirect (a from ending in / is a prefix), and DELETE with { "from" } removes it. Writes need redirects-manage. MCP: RedirectList, RedirectSet, RedirectToggle, RedirectUnset, RedirectAdd, RedirectRemove.

Proxies (API 1.31.0+) wrap cipi proxy: GET /api/apps/{name}/proxies (proxies-view), POST with { "prefix", "upstream", "strip_prefix"?, "preserve_host"?, "timeout"?, "buffering"? } and DELETE with { "prefix" } (proxies-manage). The loopback guard is never bypassed from the API — there is no --force — so upstreams on ports Cipi already uses (nginx, SSH, MariaDB, PostgreSQL, Valkey, Meilisearch, another app's Octane or Reverb) are refused. MCP: ProxyList, ProxyAdd, ProxyRemove.

Node apps (API 1.31.0+ / Cipi 5.4.0+): POST /api/apps accepts node (spa|static|ssr), framework (next|nuxt|sveltekit|astro|remix|vite), node_version, build, start, output and health_path — see Node apps. Node apps require a repository and refuse custom, octane, engine and php. PUT /api/apps/{name} accepts the same fields; node_version also pins a Laravel app's asset builds to a Node major (default follows the server again). GET /api/node lists installed runtimes, the server default and the apps on each major; GET /api/apps/{name}/node shows an app's Node status (node-view). POST /api/apps/{name}/node/restart is a blue/green restart, async job node-restart (node-manage). App list/show expose node, node_mode and node_version, plus redirect, redirects and proxies. MCP: NodeRuntimes, NodeStatus, NodeRestart.

Node runtimes (API 1.39.0, Cipi 5.9.0). Before 1.39 installing, upgrading and removing runtimes and changing the server default stayed on the CLI. With the ability node-runtimes-manage: POST /api/node/install (major), POST /api/node/upgrade (optional major; restart: true moves the SSR apps to the new binary blue/green), PUT /api/node/default (major, or system) and DELETE /api/node/{major} — async jobs node-install, node-upgrade, node-default, node-remove. On an older core these answer 503 with what they need.

Backups (API 1.39.0, Cipi 5.9.0). GET /api/backups returns what cipi backup status --json prints: destinations without their keys, every profile with the apps and databases it covers right now, its last run, overdue, running, and uncovered — what no enabled profile takes. GET /api/backups/runs (optional profile) lists the stored runs per destination. POST /api/backups/run starts cipi backup run --detach on the server and answers 202 at once: the run goes on by itself and GET /api/backups says when it is done. POST /api/backups/verify, POST /api/backups/profiles, PUT|DELETE /api/backups/profiles/{name}, POST …/enable and …/disable, and POST /api/backups/destinations/test complete it. Destinations are read-only: cipi backup configure and cipi backup destination add take an S3 secret key, and the only way the API passes a value to the CLI is a command line (which it also keeps in its jobs table). Buckets are added on the server.

Since API 1.39.1 GET /api/backups always carries configured as a boolean — an answer of the CLI without it is a 503 that says so, never an empty 200 — and says where it comes from: host (the server's hostname) and config_file (/etc/cipi/backup.json, the file cipi backup configure writes and the status looks for). A line sudo prints around the JSON is ignored; sudo refusing the command is reported as that, with the file to check (/etc/sudoers.d/cipi-api).

Databases and dumps (API 1.39.0, Cipi 5.9.0). GET /api/dbs returns app, link and size_mb for each database; POST /api/dbs takes app; POST|DELETE /api/dbs/{name}/link link an existing database to an app and unlink it (see a database that belongs to an app); GET /api/apps returns each app's databases. A dump can be uploaded instead of having to be on the server already: GET /api/dbs/uploads/limits, POST /api/dbs/uploads (filename, size), POST /api/dbs/uploads/{id}/chunks (index, chunk) — in pieces, so a dump does not have to fit one request — then POST /api/dbs/{name}/restore with upload_id in place of file. .sql or .sql.gz, up to db_upload.max_mb (2 GB by default); the upload is deleted when the restore job ends, and DELETE /api/dbs/uploads/{id} gives one up.

Deploy audit (API 1.31.0+ / Cipi 5.4.0+) — GET /api/apps/{name}/deploy/audit?days=90 returns the app's records from the hash-chained deploy ledger (cipi deploy <app> --audit --json): event, release, commit, origin (cli, panel, webhook, ssh, cron, …), operator, IP and the app's claimed fields. The list is empty until the first deploy after the update. Ability deploy-manage; MCP DeployAudit.

Deploy status (API 1.37.0+ / Cipi 5.8.4+) — GET /api/apps/{name}/deploy/status?tail=N is cipi deploy <app> --status --json: whether a deploy is running right now, whoever started it (state running / queued / interrupted / idle, phase, current with trigger, branch, start time and elapsed seconds, last with the previous run's result, optionally the last tail lines of the deploy log). Synchronous and read-only, safe to poll — the GUI does, to show a deploy started by a Git push. On a server older than Cipi 5.8.4 the API answers 503 and never sends the flag (an older core would start a deploy). Ability deploy-manage; MCP DeployStatus.

GET /api/apps/{name}/deploy/history?limit=N (API 1.39.0, Cipi 5.9.0) is cipi deploy --history <app> --json: past deploys and rollbacks, newest first, each with result, kind, release, duration, exit, trigger, branch, from_release, started_at and finished_at — read from the deploy log and its rotated files. A client that read deploy.log through the logs endpoint had the duration of a deploy until the first nightly rotation only; that is why deploys started by a Git push seemed to have none. GET /api/deploys/last returns the last finished run of every app (null for one never deployed), for an app list. Both need apps-view or deploy-manage, are synchronous and read-only, and answer 503 on a core older than 5.9.0 without sending the flag.

Search (API 1.31.0+ / Cipi 5.2.2+) — GET /api/search (search-view) and POST /api/apps/{name}/search/enable|disable (search-manage, Laravel apps only) wrap cipi search. Installing, upgrading or removing Meilisearch and rotating its master key stay on the CLI. MCP: SearchStatus, SearchEnable, SearchDisable.

Host insights (API 1.31.0+, read-only by design) — GET /api/packages (packages-view, cipi package list), GET /api/monitor (monitor-view, checks with config, state and last alert) and GET /api/zt (zt-view, parsed cipi zt status plus raw output). MCP: PackageList, MonitorList, ZtStatus.

App type (API 1.32.0+) — GET /api/apps and GET /api/apps/{name} return custom and a type of laravel, custom or node. Cipi stores custom: true on Node apps too, so type is the field that tells them apart. The list also returns docroot. MCP AppList and AppShow return the same fields, plus node, node_mode and node_version.

Limits (API 1.32.0+) — GET /api/apps/{name}/limits (apps-view) returns fpm_max_children, memory_limit, octane_workers and worker_procs (null is the CLI default), the defaults, and disk_limit_gb. PUT with any of those fields is the async job app-limits (apps-edit); the result reports disk_used_gb, disk_percent and over_limit. Node apps accept only disk_limit_gb. null removes the soft disk limit. The limit is soft (Cipi 5.5.0+): the monitor check app_disk warns at 90% and alerts when over; nothing is blocked. See cipi app limits. MCP: AppLimitsShow, AppLimitsUpdate. The control panel shows the limit and still sets it on the host.

DNS-01 and wildcard certificates (API 1.32.0+, ability ssl-manage) — POST /api/apps/{name}/ssl accepts an optional body { "dns": "cloudflare", "account", "wildcard", "http" }. With no body, Cipi 5.5.1+ reissues a DNS-01 certificate over DNS-01 with its own account. http: true goes back to HTTP-01; wildcard: false drops a remembered *.<apex>. Both need Cipi 5.5.1+; naming an account or issuing a wildcard needs 5.5.0+. GET /api/ssl/dns lists Cloudflare accounts and the certificates that renew with each. PUT /api/ssl/dns with { "name"?, "token" } adds an account or rotates its token. That call is synchronous, so the token is never queued or stored by the API, and it is never returned. DELETE /api/ssl/dns/{account} answers 409 while a certificate still renews with that account. The ssl-install job result includes challenge (http-01 / dns-01), dns and account. MCP: SslDnsList; SslInstall accepts dns, account, wildcard and http. Account tokens are not settable over MCP.

Disk usage (API 1.33.0+, ability disk-view) — GET /api/disk is what cipi disk --json prints: the filesystem /home is on (mount, size_gb, used_gb, free_gb, used_percent), then every app largest first with files_gb, database_gb, total_gb, percent, the KiB figures, the soft limit (limit_gb, limit_percent, over_limit), and the totals apps_total_gb, apps_percent, other_gb, other_percent. GET /api/disk/dbs is one entry per installed engine (mariadb, pgsql, valkey, meilisearch): databases (name, size_mb, plus keys for Valkey and documents for Meilisearch), on_disk_mb, memory_mb (Valkey) and note when the engine did not answer. Both are measured when asked, so a server with large apps takes a few seconds. They need Cipi 5.5.2+ (cipi self-update, migration 5.5.2) so /etc/sudoers.d/cipi-api allows cipi disk. Older servers answer 503; every other route stays as in 1.32.0. The host command itself exists since 5.5.0. MCP: DiskUsage, DiskDatabases. From a laptop, cipi-cli disk (1.6.0+). The control panel shows the same figures on Server → Disk (panel 3.1).

cipi.yml (API 1.35.0+, abilities yml-view / yml-manage) — GET /api/apps/{name}/yml is what cipi yml plan <app> --json prints: file (the cipi.yml of the live release, null when there is none), auto, valid (null with no file; false → errors), in_sync (true when nothing would change and nothing blocks), warnings, changes (kind, a short token such as php or alias-add, and summary, the text to show), blockers and notes — and, since API 1.36.0+ / Cipi 5.8.0+, env, the app's environment, file then being the cipi-<env>.yml when the release carries one. POST /api/apps/{name}/yml/apply takes no body and returns 202 with a job_id (type app-yml-apply). Its result carries outcome (applied, unchanged, partial, blocked, invalid, no-file), applied, failed, failures, blockers and errors. applied and unchanged end completed; the others end failed with the same result. Nothing changes while blockers is not empty. POST /api/apps/{name}/yml/auto/enable and …/auto/disable are idempotent and return { "app", "auto", "sudoers", "file" } — sudoers is the rule that lets webhook deploys apply the file, and should equal auto. Turning auto on lets anyone who can push to the repository change the app's aliases, PHP settings, limits, workers, deploy recipe, crons, databases and backup schedule; clients ask for confirmation. Every route needs Cipi 5.6.4+ (cipi self-update): it adds the --json outputs, and migration 5.6.4 lets www-data run cipi yml plan|apply|auto. --file= is refused through the API, which only reads the app's own file. Older servers answer 503; 404 for an unknown app. MCP: AppYmlShow, AppYmlApply, AppYmlAuto. Remote clients: cipi-cli yml, the PHP SDK yml() resource and the control panel's cipi.yml tab on the app page.

Fix permissions (API 1.31.0+ / Cipi 5.2.1+) — POST /api/apps/{name}/fix-permissions restores the app home permission model (cipi app fix-permissions). Async job app-fix-permissions; ability apps-edit; MCP AppFixPermissions. Since API 1.31.0, app create and edit also accept a wildcard primary domain (*.example.com, Cipi 5.1.1+).

Method Endpoint Required ability
GET /api/apps apps-view
GET /api/apps/{name} apps-view
GET /api/apps/{name}/logs apps-view
POST /api/apps apps-create
PUT /api/apps/{name} apps-edit
POST /api/apps/{name}/webhook/recreate apps-edit
POST /api/apps/{name}/fix-permissions apps-edit
POST /api/apps/{name}/suspend apps-suspend
POST /api/apps/{name}/unsuspend apps-suspend
DELETE /api/apps/{name} apps-delete
GET /api/apps/{name}/basicauth apps-basicauth
POST /api/apps/{name}/basicauth/enable apps-basicauth
POST /api/apps/{name}/basicauth/disable apps-basicauth
GET|PUT /api/apps/{name}/env apps-env
GET|POST|PUT|DELETE /api/apps/{name}/auth apps-auth
POST /api/apps/{name}/artisan apps-artisan
GET /api/run-commands apps-run
POST /api/apps/{name}/run apps-run
GET|PUT /api/apps/{name}/deploy-config apps-deploy-config
GET /api/apps/{name}/aliases aliases-view
POST /api/apps/{name}/aliases/{alias} aliases-create
DELETE /api/apps/{name}/aliases/{alias} aliases-delete
GET /api/apps/{name}/www www-manage
POST /api/apps/{name}/www/add www-manage
POST /api/apps/{name}/www/force-to-root www-manage
POST /api/apps/{name}/www/force-from-root www-manage
POST /api/apps/{name}/www/clear www-manage
GET /api/apps/{name}/redirects redirects-view
PUT|DELETE /api/apps/{name}/redirect redirects-manage
POST /api/apps/{name}/redirect/enable|disable redirects-manage
POST|DELETE /api/apps/{name}/redirects redirects-manage
GET /api/apps/{name}/proxies proxies-view
POST|DELETE /api/apps/{name}/proxies proxies-manage
GET /api/node node-view
GET /api/apps/{name}/node node-view
POST /api/apps/{name}/node/restart node-manage
POST /api/node/install node-runtimes-manage (1.39+)
POST /api/node/upgrade node-runtimes-manage (1.39+)
PUT /api/node/default node-runtimes-manage (1.39+)
DELETE /api/node/{major} node-runtimes-manage (1.39+)
POST /api/apps/{name}/deploy deploy-manage
POST /api/apps/{name}/deploy/rollback deploy-manage
POST /api/apps/{name}/deploy/unlock deploy-manage
GET /api/apps/{name}/deploy/audit deploy-manage
GET /api/apps/{name}/deploy/status deploy-manage
GET /api/apps/{name}/deploy/history apps-view or deploy-manage (1.39+)
GET /api/deploys/last apps-view or deploy-manage (1.39+)
POST /api/apps/{name}/ssl ssl-manage
POST /api/apps/{name}/ssl/force ssl-manage
GET /api/dbs/engines dbs-view
POST /api/dbs/engines/install dbs-manage
GET /api/dbs dbs-view
POST /api/dbs dbs-create
POST /api/dbs/{name}/backup dbs-manage
POST /api/dbs/{name}/restore dbs-manage
POST /api/dbs/{name}/password dbs-manage
POST|DELETE /api/dbs/{name}/link dbs-manage (1.39+)
GET /api/dbs/uploads/limits dbs-manage (1.39+)
POST /api/dbs/uploads dbs-manage (1.39+)
POST /api/dbs/uploads/{id}/chunks dbs-manage (1.39+)
DELETE /api/dbs/uploads/{id} dbs-manage (1.39+)
GET /api/backups backups-view (1.39+)
GET /api/backups/runs backups-view (1.39+)
POST /api/backups/run backups-manage (1.39+)
POST /api/backups/verify backups-manage (1.39+)
POST /api/backups/destinations/test backups-manage (1.39+)
POST /api/backups/profiles backups-manage (1.39+)
PUT|DELETE /api/backups/profiles/{name} backups-manage (1.39+)
POST /api/backups/profiles/{name}/enable|disable backups-manage (1.39+)
GET /api/php php-view
POST /api/php/install php-manage
GET /api/ssh/keys ssh-view
POST /api/ssh/keys ssh-manage
DELETE /api/ssh/keys/{n} ssh-manage
GET /api/services services-view
POST /api/services/{name}/restart services-manage
GET /api/smtp smtp-view
PUT /api/smtp smtp-manage
POST /api/smtp/enable|disable|test smtp-manage
DELETE /api/smtp smtp-manage
GET /api/health health-view
GET /api/apps/{name}/health health-view
PUT|DELETE /api/apps/{name}/health health-manage
POST /api/apps/{name}/health/check health-view
GET /api/search search-view
POST /api/apps/{name}/search/enable|disable search-manage
GET /api/packages packages-view
GET /api/monitor monitor-view
GET /api/zt zt-view
GET|PUT /api/apps/{name}/limits apps-view / apps-edit
GET|PUT /api/ssl/dns ssl-manage
DELETE /api/ssl/dns/{account} ssl-manage
GET /api/disk disk-view
GET /api/disk/dbs disk-view
GET /api/apps/{name}/yml yml-view
POST /api/apps/{name}/yml/apply yml-manage
POST /api/apps/{name}/yml/auto/enable|disable yml-manage
GET /api/status status-view
GET /api/jobs/{id} the ability the job was created under (API 1.36.1+; any authenticated token before)
GET /api/ip-whitelist ip-whitelist-view
PUT|POST|DELETE /api/ip-whitelist (+ /allow-all) ip-whitelist-manage

REST examples (curl)

Set your API base URL and token (from cipi api token create):

bash
export CIPI_API_URL="https://api.myserver.com"
export CIPI_API_TOKEN="your-sanctum-token"

List apps (sync, 200):

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

Server status (sync, requires status-view):

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

App logs (sync, requires apps-view, API 1.11.9+):

bash
curl -sS "${CIPI_API_URL}/api/apps/myapp/logs?type=deploy&page=1&per_page=50" \
  -H "Authorization: Bearer ${CIPI_API_TOKEN}" \
  -H "Accept: application/json"

Create a Laravel Octane app (async, API 1.13.0+ / Cipi 5.0+; requires apps-create):

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

Send "octane": "frankenphp" for the same effect. Omit octane for classic PHP-FPM. Use "engine": "pgsql" when PostgreSQL is installed (API 1.12.0+ / Cipi 4.8+).

App .env (sync, API 1.14.0+ / Cipi 5.0.3+; requires apps-env):

bash
curl -sS "${CIPI_API_URL}/api/apps/myapp/env" \
  -H "Authorization: Bearer ${CIPI_API_TOKEN}"

curl -sS -X PUT "${CIPI_API_URL}/api/apps/myapp/env" \
  -H "Authorization: Bearer ${CIPI_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"set":{"APP_DEBUG":"false"},"unset":["LEGACY_KEY"]}'

Artisan / app run (async jobs, API 1.14.0+; abilities apps-artisan / apps-run):

bash
curl -sS -X POST "${CIPI_API_URL}/api/apps/myapp/artisan" \
  -H "Authorization: Bearer ${CIPI_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"command":"cache:clear"}'

curl -sS -X POST "${CIPI_API_URL}/api/apps/myapp/run" \
  -H "Authorization: Bearer ${CIPI_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"command":"composer install --no-dev"}'

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

Poll GET /api/jobs/{id} for output / exit_code — with the same ability (apps-artisan / apps-run, API 1.36.1+). Job types: app-artisan, app-run.

Deploy an app (async, 202 + job_id):

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

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

Create a Node SSR app (async, API 1.31.0+ / Cipi 5.4.1+; requires apps-create):

bash
curl -sS -X POST "${CIPI_API_URL}/api/apps" \
  -H "Authorization: Bearer ${CIPI_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "web.example.com",
    "repository": "git@github.com:you/web.git",
    "node": "ssr",
    "framework": "next",
    "node_version": "22"
  }'

Redirects and proxies (sync, API 1.31.0+ / Cipi 5.4.1+; redirects-manage / proxies-manage):

bash
curl -sS -X POST "${CIPI_API_URL}/api/apps/myapp/redirects" \
  -H "Authorization: Bearer ${CIPI_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"from":"/blog/","to":"https://blog.example.com/","code":301}'

curl -sS -X POST "${CIPI_API_URL}/api/apps/myapp/proxies" \
  -H "Authorization: Bearer ${CIPI_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"prefix":"/api/","upstream":"http://127.0.0.1:3000","strip_prefix":true}'

Deploy audit (sync, API 1.31.0+ / Cipi 5.4.0+; deploy-manage):

bash
curl -sS "${CIPI_API_URL}/api/apps/myapp/deploy/audit?days=30" \
  -H "Authorization: Bearer ${CIPI_API_TOKEN}"

Database backup (async, dbs-manage) — returns a real backup path in the job result, not an anonymized dump (see Agent anonymizer):

bash
curl -sS -X POST "${CIPI_API_URL}/api/dbs/myapp_db/backup" \
  -H "Authorization: Bearer ${CIPI_API_TOKEN}"

Host integration (sudoers)

The panel API runs as www-data and executes Cipi CLI commands via sudo using /etc/sudoers.d/cipi-api — an explicit whitelist of cipi subcommands. Vault and MariaDB credentials stay inside Cipi, not in PHP.

  • GET /api/dbs — runs sudo cipi db list (sync). Requires Cipi 4.4.17+ (migration adds cipi db … to sudoers). Without it: sudo: a terminal is required. Multi-engine list/engines need Cipi 4.8+ / API 1.12.0+.
  • GET /api/status / MCP ServerStatus — prefer sudo cipi status (API 1.11.8+); host-read fallback when sudo fails (includes postgresql since API 1.12.1+).
  • MCP ServiceList — sudo cipi service list
  • MCP AppArtisan — sudo cipi app artisan <app> …
  • Since Cipi 5.0.6+ / API 1.15+: php list|install|remove|switch, ssh list|add|remove, service list|restart, status, db install|default|engines, app webhook recreate, smtp status|configure|enable|disable|test|delete, api ip-whitelist (+ args) in the sudoers whitelist (migration 5.0.6 creates the default IP whitelist file and regenerates /etc/sudoers.d/cipi-api on cipi self-update).
  • Since Cipi 5.0.3+ / API 1.14+: app env, app artisan, app run, auth create|edit|show|delete, and deploy-config in the sudoers whitelist (migration regenerates /etc/sudoers.d/cipi-api on cipi self-update).
  • Since Cipi 5.2.2+: search status|list|enable|disable and package list in the sudoers whitelist. search install|upgrade|key rotate|remove and package install|remove stay off it — they change or destroy server state and stay with the operator on the CLI.
  • Since Cipi 5.2.3+: the manual stack upgrades — nginx upgrade, db upgrade and service upgrade — are not in the sudoers whitelist either, for the same reason as package install: restarting a database engine is an operator decision, taken at the CLI while you are watching.
  • Since Cipi 5.3.0+: zt status and monitor list in the sudoers whitelist. zt enable, lock and the rest, and monitor enable|disable|set, stay with the operator on the CLI — the same rule as package install.
  • Since Cipi 5.4.1+ (API 1.31.0+): redirect set|enable|disable|unset|add|remove|list, proxy add|remove|list and node list|status|restart — each rule the usual exact command line. deploy <app> --audit reads the root-only ledger. Migration 5.4.1 regenerates /etc/sudoers.d/cipi-api and checks it with visudo -cf. What deliberately stays CLI-root: Node runtime management (node install|default|upgrade|remove), search install|upgrade|key-rotate, package install|remove and every zt mutation — installing software on the server is not something a web panel should be able to do, compromised or not. The redirect/proxy validation is the CLI's own, so the panel gets exactly the same refusals.
  • Async jobs — cipi app (including --octane / --engine), deploy, alias, www, ssl / ssl force, db create|delete|backup|restore|password|engines, etc.

After cipi self-update, run cipi api fix-permissions if /docs or /mcp return HTTP 500 (see troubleshooting above).

IP whitelist (CLI)

Since Cipi 5.0.6+, restrict panel API and MCP clients by source IP. Default file /etc/cipi/api-ip-whitelist is * (allow all). One IPv4/IPv6 address or CIDR per line (or comma-separated --ips=).

bash
cipi api ip-whitelist show
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 allow-all
cipi api ip-whitelist show --json

REST equivalents live under /api/ip-whitelist (API 1.15.0+). PUT auto-adds the caller IP when tightening the list unless ensure_client_ip: false.

Swagger / OpenAPI

Interactive documentation is available at /docs (Swagger UI). The OpenAPI spec is generated from public/api-docs/openapi.json and covers apps (including suspend, unsuspend, domain rename, basic auth, .env, Composer auth.json, Artisan / app-run jobs, deploy-config, fix-permissions, paginated logs, www redirects, Octane and Node create, and multi-engine engine), app and path redirects, proxies, Node runtimes, aliases, deploy and deploy audit, SSL (install + force HTTPS), databases (engines list + optional engine on mutations), search, packages, monitor, Zero Trust, server status, job polling with structured result types, and MCP tool schemas. Current API package version: 1.34.0 (1.30.0 was published in error from an old commit — skip it). 1.32.0 adds app type, /api/apps/{name}/limits and /api/ssl/dns. 1.33.0 adds /api/disk and /api/disk/dbs. 1.34.0 adds node_build to POST /api/apps (the Laravel asset build, same rule as the CLI) and repository_access to the app-create result, and to the app-edit result when the repository or branch changed: status (ok, nobranch, denied), branch, error and the CLI fix as hint. 1.35.0 adds /api/apps/{name}/yml, …/yml/apply and …/yml/auto/enable|disable with the yml-view / yml-manage abilities (Cipi 5.6.4+).

MCP server

An MCP (Model Context Protocol) server is exposed at /mcp via Streamable HTTP. Since API package 1.11.1+, a token with the mcp-access ability is sufficient for all MCP tools — per-endpoint REST abilities (apps-view, deploy-manage, apps-basicauth, www-manage, etc.) are not checked on /mcp. The server exposes 73 tools (one tools/list page; MCP server 1.3.0) for app, alias, www, redirects, proxies, Node, database, deploy and deploy audit, SSL, HTTP Basic Auth, search, limits, disk usage, cipi.yml, server management (PHP, SSH, services, SMTP, health, IP whitelist, packages, monitor, Zero Trust), .env / auth.json / app-run / deploy-config, job polling, logs, Artisan, and server monitoring. Write operations that dispatch async jobs return a job_id — poll with JobShow (API 1.11.0+). Basic auth actions and read-only tools run synchronously.

  • Applications: AppList, AppShow, AppCreate (optional engine, octane), AppEdit, AppSuspend, AppUnsuspend, AppDelete, AppDeploy, AppDeployRollback, AppDeployUnlock, AppArtisan (Laravel apps only; rejects custom apps and tinker), AppEnvShow, AppEnvUpdate, AppAuthJson*, AppRun, AppRunCommands, AppDeployConfigShow, AppDeployConfigUpdate, AppWebhookRecreate (API 1.15.0+ / Cipi 5.0.6+; earlier app tooling requires API 1.14.0+ / Cipi 5.0.3+), AppFixPermissions (API 1.31.0+), AppLimitsShow, AppLimitsUpdate (API 1.32.0+; disk_limit_gb needs Cipi 5.5.0+), AppYmlShow, AppYmlApply (async job), AppYmlAuto (app, enabled) — the app's cipi.yml (API 1.35.0+ / Cipi 5.6.4+)
  • Redirects & proxies: RedirectList, RedirectSet, RedirectToggle, RedirectUnset, RedirectAdd, RedirectRemove, ProxyList, ProxyAdd, ProxyRemove (API 1.31.0+ / Cipi 5.4.1+)
  • Node: NodeRuntimes, NodeStatus, NodeRestart (API 1.31.0+ / Cipi 5.4.1+)
  • Deploy audit: DeployAudit (API 1.31.0+ / Cipi 5.4.0+)
  • Deploy status: DeployStatus — is a deploy running right now, whoever started it (API 1.37.0+ / Cipi 5.8.4+)
  • Search: SearchStatus, SearchEnable, SearchDisable (API 1.31.0+ / Cipi 5.2.2+)
  • Server management: PhpList, IpWhitelistShow (API 1.15.0+ / Cipi 5.0.6+); PackageList, MonitorList, ZtStatus — read-only (API 1.31.0+); DiskUsage, DiskDatabases — read-only (API 1.33.0+ / Cipi 5.5.2+)
  • HTTP Basic Auth: AppBasicAuthStatus, AppBasicAuthEnable, AppBasicAuthDisable
  • Aliases: AliasList, AliasAdd, AliasRemove
  • WWW / apex: WwwStatus, WwwAdd, WwwForceToRoot, WwwForceFromRoot, WwwClear (API 1.12.0+)
  • Databases: DbEngines, DbList, DbCreate, DbBackup, DbRestore, DbPassword (optional engine on list/mutations; API 1.12.0+; DbDelete removed in 1.19.0)
  • SSL: SslInstall (optional dns, account, wildcard, http since API 1.32.0+), SslForce (API 1.12.0+), SslDnsList (API 1.32.0+; account tokens stay off MCP)
  • Jobs & logs: JobShow (poll async job status, parsed result, and CLI output), AppLogs (recent app logs by type: all, nginx, php, worker, deploy, laravel — same as cipi app logs; REST equivalent: GET /api/apps/{name}/logs since API 1.11.9+), ApiLogShow (recent Laravel logs for the panel API host)
  • Server monitoring: ServerStatus (structured JSON matching GET /api/status / cipi status), ServiceList (system service status via cipi service list)
Since API 1.11.5+, MCP log tools (AppLogs, ApiLogShow) prefix every response with a production-content warning and redact common secrets before delivery. Sensitive CLI output from JobShow and AppArtisan is redacted too; structured job result objects (e.g. app credentials from create jobs) are left intact so operators can still read them once.

Since Cipi 4.6.3, the panel API package is soft-updated nightly at 04:30 via /etc/cron.d/cipi-api (cipi api update), so MCP and REST endpoints stay current without manual intervention.

Installing the MCP server

The MCP endpoint is optional and loads only when the required MCP package is installed. To use it from VS Code, Cursor, or Claude Desktop:

  1. Configure the API with cipi api <domain> and cipi api ssl
  2. Create a token with cipi api token create and select at least mcp-access
  3. Add the MCP server to your client config (see below)

Cursor

Add to ~/.cursor/mcp.json (or Cursor → Settings → MCP):

json
{
  "mcpServers": {
    "cipi-api": {
      "type": "http",
      "url": "https://<your-api-domain>/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Cursor connects natively over HTTP — no bridge needed.

VS Code

VS Code (with GitHub Copilot) supports MCP natively since 1.102. Add to .vscode/mcp.json or run MCP: Open User Configuration for a global setup. Use inputs to prompt for the token once and store it securely:

json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "cipi-token",
      "description": "Cipi API Token",
      "password": true
    }
  ],
  "servers": {
    "cipi-api": {
      "type": "http",
      "url": "https://<your-api-domain>/mcp",
      "headers": {
        "Authorization": "Bearer ${input:cipi-token}"
      }
    }
  }
}

Restart VS Code after saving. Use MCP: Add Server from the Command Palette for a guided setup.

Claude Code

Add the MCP server directly from the CLI:

bash
claude mcp add --transport http cipi-api https://<your-api-domain>/mcp \
    --header "Authorization: Bearer <your-token>"

Claude Desktop

Claude Desktop requires the mcp-remote bridge to convert stdio to HTTP. Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent config path on your OS:

json
{
  "mcpServers": {
    "cipi-api": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://<your-api-domain>/mcp",
        "--header",
        "Authorization: Bearer <your-token>"
      ]
    }
  }
}

Install mcp-remote once with npm install -g mcp-remote.

Replace <your-api-domain> with your API domain (e.g. api.myhosting.com) and <your-token> with the token created in step 2.

WHMCS Module

An official WHMCS provisioning module is available at github.com/cipi-sh/whmcs. It bridges the WHMCS provisioning lifecycle to the Cipi REST API — automating app creation, deletion, SSL certificates, deployments, and configuration changes for your hosting customers. No Composer dependencies; the module is a self-contained drop-in.

Requirements

  • WHMCS 8.x (provisioning module type “Server”)
  • Cipi server with API enabled: cipi api <domain> and cipi api ssl
  • Sanctum Bearer token with the required abilities:
Ability Required for
apps-view Test Connection, App Info
apps-create Create Account
apps-edit Change Package
apps-suspend Suspend / Unsuspend
apps-delete Terminate Account
deploy-manage Deploy, Rollback, Unlock
ssl-manage Install SSL, Auto-SSL

Installation

  1. Copy modules/servers/cipi/ into your WHMCS root:
    your-whmcs/
    └── modules/
        └── servers/
            └── cipi/
                ├── cipi.php
                └── lib/
                    └── CipiApiClient.php
  2. In WHMCS Admin → System Settings → Servers → Add New Server:
    • Type: Cipi (Laravel hosting)
    • Hostname: API base URL (e.g. https://api.example.com, no trailing slash)
    • Password: Bearer token from cipi api token create
    • Secure: Yes (recommended — enables TLS verification)
  3. Create a hosting product linked to this server and configure Module Settings:
Setting Description Default
PHP Version 8.2 / 8.3 / 8.4 / 8.5 8.5
App Type laravel or custom laravel
Git Repository (SSH) Required for Laravel; optional for custom —
Git Branch Branch to deploy main
Auto SSL Install Let’s Encrypt after creation No

App types

App type Cipi equivalent Stack Git / Deploy
laravel (default) cipi app create Isolated Linux user, PHP-FPM pool, Nginx vhost, MariaDB, Supervisor workers, Deployer releases SSH repository URL required; branch from settings
custom cipi app create --custom htdocs/ directory, Nginx + PHP — ideal for static sites, SPAs, WordPress, or generic PHP apps Optional: leave Git Repository empty for SFTP-only hosting, or set a repo for Git-based deploy

Provisioning lifecycle

WHMCS action API call Behaviour
Test Connection GET /api/apps Validates token and API reachability
Create Account POST /api/apps Provisions a Cipi app (Laravel or custom); waits for async jobs; optionally installs SSL
Suspend POST /api/apps/{name}/suspend Takes the app offline (HTTP 503 maintenance page) without deleting it; waits for async jobs
Unsuspend POST /api/apps/{name}/unsuspend Restores the app’s normal Nginx vhost; waits for async jobs
Terminate Account DELETE /api/apps/{name} Removes the app; waits for async jobs
Change Package PUT /api/apps/{name} Updates PHP version, Git repository, or branch

Suspend / Unsuspend require Cipi 4.5.8+ (suspend/unsuspend endpoints), the API package 1.8.1+, and a token with the apps-suspend ability. Suspending swaps the app’s vhost for a generic HTTP 503 maintenance page; unsuspending restores it.

Admin buttons

From the WHMCS admin service view, operators can trigger one-click actions:

Button API call Description
Install SSL POST /api/apps/{name}/ssl Install a Let’s Encrypt certificate
Deploy POST /api/apps/{name}/deploy Trigger a zero-downtime deployment
Rollback Deploy POST /api/apps/{name}/deploy/rollback Revert to the previous release
Unlock Deploy POST /api/apps/{name}/deploy/unlock Unlock a stuck deployment
App Info GET /api/apps/{name} Fetch current app details into the Module Log

Auto-SSL on creation

Enable Auto SSL in the product module settings to automatically install a Let’s Encrypt certificate right after provisioning. If SSL installation fails, the app is still created successfully and a warning is logged.

Full API client

The bundled CipiApiClient covers the entire Cipi REST API surface. Even if a feature is not wired to a WHMCS hook, you can use the client in custom hooks or addons:

Area Methods
Apps listApps, getApp, createApp, editApp, suspendApp, unsuspendApp, deleteApp
Deploy deployApp, rollbackDeploy, unlockDeploy
SSL installSsl
Aliases listAliases, addAlias, removeAlias
Databases listDatabases, createDatabase, deleteDatabase, backupDatabase, restoreDatabase, resetDatabasePassword
Jobs getJob, waitForJob

Extending the module

php
// Example: add an alias from a WHMCS hook
require_once ROOTDIR . '/modules/servers/cipi/lib/CipiApiClient.php';

$client = new CipiApiClient('https://api.example.com', $token);
$client->addAlias('myapp', 'alias.example.com');

// Example: create an extra database
$client->createDatabase('myapp_extra');

// Example: backup a database
$client->backupDatabase('myapp');

Customer-facing behaviour

The module does not add a Client Area tab, custom buttons, or live status from Cipi. Customers see the standard WHMCS service view (domain, status, renewal dates). When Cipi provisions an app it generates one-time secrets (SSH password, DB password, deploy key, webhook URL). The REST API does not automatically push those secrets into WHMCS — you should extend the module, write a hook, or deliver credentials through your support workflow.

Module logging

All API calls are logged via logModuleCall() — Create, Terminate, Change Package, SSL, Deploy, Rollback, Unlock, and App Info. Enable Utilities → Logs → Module Log in WHMCS Admin for full visibility.

Full source code, project structure, and contribution guidelines are available on GitHub. The module is open-source under the MIT License.

cipi sync

Transfer, replicate, and back up entire Laravel applications between Cipi servers — including configuration, database dumps, storage files, SSH keys, workers, and crontabs. Every archive is encrypted with AES-256-CBC and protected by a user-defined passphrase, so credentials and sensitive data are safe at rest and during transfer.

Commands overview

bash
cipi sync export  [app ...] [--with-db] [--with-storage] [--output=<path>] [--passphrase=<secret>]
cipi sync import  <archive.tar.gz.enc> [app ...] [--update] [--deploy] [--yes] [--passphrase=<secret>]
cipi sync push    [app ...] [--host=IP] [--port=22] [--with-db] [--with-storage] [--import] [--passphrase=<secret>]
cipi sync list    <archive.tar.gz.enc> [--passphrase=<secret>]
cipi sync pubkey  # display the server's sync public key for inter-server trust
cipi sync trust   # add a remote server's public key to cipi's authorized_keys

Archive encryption

All sync archives are encrypted by default with AES-256-CBC. During export you are prompted for a passphrase (minimum 8 characters) that protects the archive. The same passphrase is required to import or inspect it. This protects SSH keys, .env files, database dumps, and credentials at rest and during transfer.

bash
# Interactive mode (default) — prompted for passphrase
cipi sync export --with-db
#   Enter passphrase to encrypt the archive: ********
#   Confirm passphrase: ********

# Non-interactive mode — for cron jobs and scripts
cipi sync export --with-db --passphrase="MyStr0ngP@ss"
For automated setups, store the passphrase in a secure file and reference it in your scripts: echo "MyStr0ngP@ss" > /etc/cipi/.sync_passphrase && chmod 400 /etc/cipi/.sync_passphrase. Then use --passphrase="$(cat /etc/cipi/.sync_passphrase)" in cron jobs.

Export

Packs app configs into an encrypted .tar.gz.enc archive. Optionally includes database dumps and storage files.

bash
# Export all apps (config only)
cipi sync export

# Export three specific apps with database + storage
cipi sync export shop blog api --with-db --with-storage

# Export to a custom path (non-interactive)
cipi sync export --with-db --output=/root/backups/cipi-march.tar.gz --passphrase="MyStr0ngP@ss"

What goes into the archive

File Description Included
env The app's .env from /home/<app>/shared/.env Always
auth.json Composer auth credentials (if exists) Always
deploy.php Deployer config Always
ssh/* Deploy key, known_hosts, authorized_keys, SSH config Always
supervisor.conf Queue workers config Always
crontab App's crontab (scheduler + deploy trigger) Always
db.sql.gz Gzipped MariaDB dump (schema + data + routines) --with-db
storage.tar.gz Archive of /home/<app>/shared/storage/ --with-storage

Plus global configs: apps.json (filtered to selected apps), databases.json, backup.json, api.json.

Import

Restores apps from an archive onto the current server.

bash
# Import all apps from archive
cipi sync import /tmp/cipi-sync-aws01-20260306.tar.gz.enc

# Import only two apps from an archive that contains ten
cipi sync import /tmp/cipi-sync-aws01-20260306.tar.gz.enc shop blog --passphrase="MyStr0ngP@ss"

# Import and deploy code from Git immediately
cipi sync import /tmp/cipi-sync-aws01-20260306.tar.gz.enc --deploy

# Non-interactive (skip all prompts)
cipi sync import /tmp/cipi-sync-aws01-20260306.tar.gz.enc --yes --passphrase="MyStr0ngP@ss"

What import does for a NEW app

When an app does not exist on the target server, import creates it from scratch — equivalent to cipi app create with all configs pre-filled from the archive:

  1. Linux user — Creates a new user with a random password
  2. Directories — Creates /home/<app>/shared/, logs/, .ssh/, .deployer/
  3. SSH deploy key — Restores from archive (same key works with GitHub/GitLab without reconfiguration)
  4. MariaDB database — Creates database + user with a new random password
  5. Database data — Imports the dump if --with-db was used during export
  6. .env — Copies from archive, then overwrites DB_PASSWORD, DB_USERNAME, DB_DATABASE, DB_HOST with the new server's values. Everything else (APP_KEY, MAIL_*, REDIS_*, custom vars) stays as-is. Since v5.5.0, an .env exported by a server still on LOG_CHANNEL=daily is switched to single, and dated Laravel logs that arrive with --with-storage are folded into laravel.log
  7. App user SSH access — follows the target server's default for new apps (cipi ssh apps, v5.5.0+), and the app's soft disk limit travels with it
  8. PHP-FPM pool, Nginx vhost, Supervisor workers, Crontab, Deployer — Fully configured from archive data
  9. cipi.yml auto-apply — since v5.6.4, an app that had cipi yml auto on gets its webhook sudoers rule back, so pushes keep applying the file
At the end of import, Cipi prints the new SSH and DB passwords. Save them — they are shown only once.

Safety checks before import

The import runs pre-flight checks before touching anything:

  • App already exists — blocked unless --update is passed
  • Domain conflict — blocked if another app already uses the same domain
  • Missing PHP version — warning (the app is skipped; install the version first with cipi php install)

Update mode (--update)

The key feature for repeated sync (e.g. failover replication). Without --update, import refuses to touch apps that already exist. With --update, it updates existing apps and creates new ones.

bash
cipi sync import /tmp/archive.tar.gz.enc --update --passphrase="MyStr0ngP@ss"

What update does for an existing app

  • .env sync — The archive .env replaces the local one, but DB_PASSWORD, DB_USERNAME, DB_DATABASE, and DB_HOST are preserved from the local server. Everything else (APP_KEY, MAIL_*, REDIS_*, custom vars) comes from the source.
  • Database data — If the archive has a dump, drops all tables (with SET FOREIGN_KEY_CHECKS=0) and reimports. Uses local root credentials.
  • Storage — If the archive has storage, extracts over the existing directory (new files added, existing overwritten). Since v5.5.0, dated Laravel logs that come with it are folded into laravel.log, and a synced .env still on LOG_CHANNEL=daily is switched to single.
  • PHP version migration — If the source uses a different PHP version, the update migrates FPM pool, supervisor, crontab, deployer, and .env automatically.
  • Nginx vhost, Supervisor workers, Deployer config — Regenerated from archive data.
  • cipi.yml auto-apply — since v5.6.4, the webhook sudoers rule follows the archive: written when auto-apply is on, removed when it is off.
  • Deploy — If --deploy is passed, runs dep deploy to pull latest code.

What update does NOT change

  • Linux user password
  • SSH deploy keys (kept from first import)
  • MariaDB user credentials (target keeps its own)
  • SSL certificates (run cipi ssl install separately)

List (inspect archive)

View what is inside an archive without importing anything.

bash
cipi sync list /tmp/cipi-sync-aws01-20260306.tar.gz.enc --passphrase="MyStr0ngP@ss"

Cipi Sync Archive
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Cipi           v5.1.0
  Exported       2026-03-06T15:00:00Z
  Source         aws01 (3.120.xx.xx)
  Database       true
  Storage        true
 
  Apps
  APP            DOMAIN                       PHP    DB       STORAGE
  shop           shop.example.com             8.4    yes      yes
  blog           blog.example.com             8.4    yes      yes
  api            api.example.com              8.5    yes      yes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Push (export + transfer + import)

Combines export, rsync transfer, and remote import in one command. Runs entirely from the source server.

bash
# Interactive push — prompted for target IP and passphrase
cipi sync push --with-db --with-storage --import

# Non-interactive push (for cron and scripts)
cipi sync push --host=51.195.xx.xx --port=22 --with-db --with-storage --import --passphrase="MyStr0ngP@ss"

# Push specific apps only
cipi sync push shop blog --host=51.195.xx.xx --with-db --import --passphrase="MyStr0ngP@ss"

# Push without auto-import (transfer only — import manually on remote)
cipi sync push --host=51.195.xx.xx --with-db --passphrase="MyStr0ngP@ss"

How push works

  1. Step 1: Runs cipi sync export locally (encrypts with passphrase)
  2. Step 2: Transfers the encrypted archive to the target via rsync
  3. Step 3: If --import is passed, runs cipi sync import --update --yes on the target via SSH

Push always adds --update and --yes when calling import on the remote. This means: first run creates all apps, subsequent runs incrementally update them. This is what makes push safe to run repeatedly via cron.

SSH setup for push

The source server needs SSH access to the target as the cipi user. Use the built-in trust mechanism for passwordless, key-based authentication between Cipi servers:

bash
# On the SOURCE server — display its sync public key
cipi sync pubkey

# On the TARGET server — add the source's public key to cipi's authorized_keys
cipi sync trust

Once trusted, cipi sync push connects as the cipi user automatically — no root access required.

Practical scenarios

Scenario 1: Migrate all apps from AWS to OVH

You have 20 apps on AWS. You bought an OVH VPS and installed Cipi on it.

bash
# On AWS (source server)
cipi sync push --host=51.195.xx.xx --with-db --with-storage --import

On the OVH target: 20 Linux users, 20 databases, 20 nginx vhosts, PHP-FPM pools, supervisor configs, crontabs — all created automatically. DB data imported, storage extracted, .env files copied with OVH's DB passwords, SSH deploy keys preserved (same keys work with GitHub). After import, install SSL and update DNS:

bash
# On OVH (target server)
cipi ssl install shop
cipi ssl install blog
# ... then update DNS A records to OVH IP

Scenario 2: Scheduled failover replication (cron)

Every 6 hours, Server 1 syncs all apps to Server 2. If Server 1 dies, change DNS and go live on Server 2.

bash
# One-time setup on Server 1 — trust Server 2 using cipi sync trust
cipi sync pubkey  # copy this key, then run "cipi sync trust" on Server 2
echo "YourStr0ngPassphrase!" > /etc/cipi/.sync_passphrase
chmod 400 /etc/cipi/.sync_passphrase

# First push (manual, to verify)
cipi sync push --host=server2-ip --with-db --with-storage --import --passphrase="$(cat /etc/cipi/.sync_passphrase)"

# Add to crontab for automatic replication
crontab -e
cron
0 */6 * * * /usr/local/bin/cipi sync push --host=51.195.xx.xx --port=22 --with-db --with-storage --import --passphrase="$(cat /etc/cipi/.sync_passphrase)" >> /var/log/cipi/sync-replica.log 2>&1

Data loss window equals the cron interval (6 hours in this example). When Server 1 goes down: change DNS to Server 2, run cipi ssl install for each app, and you are live.

Scenario 3: Replicate to multiple servers

cron
# Stagger by 30 minutes so exports don't run simultaneously
0 */6 * * * /usr/local/bin/cipi sync push --host=51.195.xx.xx --with-db --with-storage --import --passphrase="$(cat /etc/cipi/.sync_passphrase)" >> /var/log/cipi/sync-ovh.log 2>&1
30 */6 * * * /usr/local/bin/cipi sync push --host=164.90.xx.xx --with-db --with-storage --import --passphrase="$(cat /etc/cipi/.sync_passphrase)" >> /var/log/cipi/sync-do.log 2>&1

Scenario 4: Daily encrypted backup (no transfer)

cron
0 3 * * * /usr/local/bin/cipi sync export --with-db --with-storage --output=/root/backups/cipi-$(date +\%Y\%m\%d).tar.gz --passphrase="$(cat /etc/cipi/.sync_passphrase)" >> /var/log/cipi/export.log 2>&1

Creates an encrypted portable archive every night. Restore on any Cipi server at any time with cipi sync import.

Limitations

  • SSL certificates are not included in the archive. Run cipi ssl install after importing on a new server.
  • DB sync is full replace, not incremental. Each update drops all tables and reimports.
  • Storage sync is full extract, not incremental rsync. Deleted files on the source remain on the target.
  • Deploy keys are the same on source and target — no GitHub/GitLab reconfiguration needed.

Vault & Encryption

Cipi encrypts all configuration files at rest using AES-256-CBC. The Vault system provides transparent encryption and decryption so that sensitive data — database passwords, API tokens, SSH keys, .env contents — is never stored in plaintext on disk.

Architecture

The system is built on two layers:

  • Vault — transparent encryption of JSON configuration files on disk (server.json, apps.json, databases.json, backup.json, smtp.json, api.json)
  • Sync encryption — passphrase-based encryption of export archives for secure transfer between servers

How Vault works

A master key is generated during installation with openssl rand -base64 32 and stored at /etc/cipi/.vault_key (chmod 400, root-only). Every JSON config file is encrypted on disk with openssl enc -aes-256-cbc -salt -pbkdf2. Files keep the .json extension — the content is simply an encrypted blob instead of readable JSON.

The vault_read function auto-detects whether a file is plaintext or encrypted (backward compatibility), so existing servers migrate seamlessly during update.

Vault functions

bash
# Core functions in lib/vault.sh
vault_init          # Generate .vault_key if not present
vault_read <file>   # Decrypt and output JSON to stdout (auto-detect plain/encrypted)
vault_write <file>  # Read JSON from stdin, encrypt and write to disk
vault_seal <file>   # Encrypt an existing plaintext file in-place
vault_get <file> <jq_query>  # Shortcut: vault_read | jq

Public projection

Cipi generates an apps-public.json file containing only non-sensitive fields (domain, aliases, PHP version, branch, repository, user, creation timestamp, plus suspended and basic_auth flags). The cipi-api group reads this plaintext projection instead of the encrypted file, keeping the vault key restricted to root.

Sync archive encryption

When you run cipi sync export, configs are decrypted from the vault into a staging area, then the entire archive is encrypted with your passphrase. On import, the archive is decrypted with the passphrase, and configs are re-encrypted with the destination server's vault key.

If the vault key is lost, configuration files become irrecoverable. The key is protected by chmod 400 and included in server backups. Consider exporting it manually for additional safety.

Email Notifications

Cipi can send email alerts when backup errors, deploy failures, system cron job failures, or security-relevant authentication events occur. SMTP configuration is stored encrypted in /etc/cipi/smtp.json and included in sync exports. Since v5.3.0 the same notifications can also go to Slack, Discord, Telegram, ntfy or a webhook — see chat alert channels.

Commands

bash
cipi smtp configure      # interactive setup (Gmail, SendGrid, Mailgun, custom)
cipi smtp status          # display current notification settings
cipi smtp test            # send a verification email
cipi smtp enable          # enable notifications
cipi smtp disable         # disable without losing settings
cipi smtp delete          # remove SMTP configuration entirely

# Non-interactive (v5.0.6+) — panel API, scripts, automation
cipi smtp configure --host=smtp.example.com --port=587 --user=… --password=… \
    --from=alerts@example.com --to=ops@example.com --tls=on
cipi smtp status --json
cipi smtp delete --force

Granular notification triggers

Since v4.6.3, you can control which events send email when SMTP is configured. All triggers are on by default; events are always logged to /var/log/cipi/events.log regardless.

bash
cipi notifications list              # all triggers grouped by category
cipi notifications enable <trigger>   # turn one trigger on
cipi notifications disable <trigger>  # turn one trigger off
cipi notifications enable-all          # re-enable everything
cipi notifications disable-all         # mute all email alerts
cipi notifications reset               # restore defaults (all on)

Config: /etc/cipi/notifications.json. Run cipi notifications list on the server for the live on/off state. Trigger IDs for cipi notifications enable|disable <trigger>:

v5.1.0 adds five: backup_stale (a profile has not succeeded within twice its own interval), ini_set (a PHP setting changed), yml_apply and yml_fail (a project's cipi.yml was applied, or was invalid), and self_update (Cipi updated itself — so an unattended nightly update no longer lands without a word).

v5.2.2 adds eight more under two new categories: Search (search_install, search_enable, search_disable, search_key_rotate, search_upgrade, search_remove) and Packages (package_install, package_remove).

v5.2.3 adds five: yml_post_fail (a deploy.post step failed) and one per manually upgraded service — nginx_upgrade, mariadb_upgrade, pgsql_upgrade, valkey_upgrade.

v5.3.0 adds twelve. Eight under Monitor, one per cipi monitor check — monitor_disk, monitor_ssl, monitor_services, monitor_workers, monitor_http_5xx, monitor_fs, monitor_load — plus the recovery message monitor_ok. Four under Security for Cloudflare Zero Trust: zt_enable, zt_disable, zt_lock_http and zt_lock_ssh. Every trigger also reaches the chat channels you configure.

v5.3.1 adds two under Domains, both on by default: redirect_change for cipi redirect and proxy_change for cipi proxy.

v5.4.0 adds node_default under a new Node category: the server-wide Node version changed (cipi node default, or the 5.4.0 migration moving a server from Node 20 to 22). Since 5.4.0, api_update fires only when cipi api update actually changed a locked package, and names the old and new cipi/api versions — before, the 04:30 soft update sent it every night. A backup whose retention could not list or delete on S3 now sends backup_fail as well.

Fixed in v5.3.0: jq's // true treats false the same as “absent”, so an explicitly disabled flag read back as enabled. cipi notifications disable <trigger> wrote false, yet the trigger kept sending email and cipi notifications list showed it as on. And cipi smtp configure --tls=off stored tls: false, then generated /etc/msmtprc with tls on — which breaks a plain relay — while cipi smtp status reported the wrong value. An explicit false now stays false. If you rely on --tls=off, run cipi smtp configure again after updating so /etc/msmtprc is rewritten.
Trigger ID Category Event
app_createAppsApp created
app_editAppsApp modified
app_deleteAppsApp deleted
app_suspendAppsApp suspended
app_unsuspendAppsApp unsuspended
app_ssh_password_resetAppsApp SSH password reset
app_db_password_resetAppsApp DB password reset
alias_addDomainsAlias added
alias_removeDomainsAlias removed
www_addDomainsWWW alias added
www_force_to_rootDomainsWWW force to-root
www_force_from_rootDomainsWWW force from-root
www_clearDomainsWWW redirect cleared
redirect_changeDomainsApp or path redirect changed (5.3.1)
proxy_changeDomainsProxy prefix added or removed (5.3.1)
node_defaultNodeServer-wide Node version changed (5.4.0)
auth_createAuthComposer auth.json created
auth_editAuthComposer auth.json edited
auth_deleteAuthComposer auth.json deleted
basicauth_enableBasic authHTTP basic auth enabled
basicauth_disableBasic authHTTP basic auth disabled
deploy_successDeployDeploy succeeded
deploy_failDeployDeploy failed
deploy_rollbackDeployDeploy rollback
deploy_snapshot_failDeployPre-deploy DB snapshot failed
health_failHealthHTTP healthcheck failed (periodic, after 3 failures)
deploy_health_failHealthPost-deploy healthcheck failed
monitor_diskMonitorDisk usage over threshold (5.3.0)
monitor_sslMonitorSSL certificate expiring (5.3.0)
monitor_servicesMonitorSystem service not running (5.3.0)
monitor_workersMonitorQueue worker / Horizon not running (5.3.0)
monitor_http_5xxMonitorHTTP 5xx spike in access logs (5.3.0)
monitor_fsMonitorFilesystem read-only / config not writable (5.3.0)
monitor_loadMonitorLoad average over threshold (5.3.0)
monitor_okMonitorMonitor check recovered (5.3.0)
ssl_installSSLSSL certificate installed
ssl_forceSSLHTTP → HTTPS redirect forced
ssl_renewSSLSSL certificates renewed
php_installPHPPHP version installed
php_switchPHPSystem PHP switched
php_removePHPPHP version removed
php_upgradePHPPHP packages upgraded
nginx_upgradeStacknginx packages upgraded (5.2.3)
mariadb_upgradeStackMariaDB packages upgraded (5.2.3)
pgsql_upgradeStackPostgreSQL packages upgraded (5.2.3)
valkey_upgradeStackValkey packages upgraded (5.2.3)
db_createDatabaseDatabase created
db_deleteDatabaseDatabase deleted
worker_addWorkersWorker added
worker_removeWorkersWorker removed
ssh_key_addSSH keysSSH key added
ssh_key_renameSSH keysSSH key renamed
ssh_key_removeSSH keysSSH key removed
ssh_loginSecuritySSH login (cipi/root/sudo users)
sudoSecuritySudo elevation
suSecuritysu to root by cipi
zt_enableSecurityCloudflare Zero Trust enabled (5.3.0)
zt_disableSecurityCloudflare Zero Trust disabled (5.3.0)
zt_lock_httpSecurityHTTP ports locked (Cloudflare) (5.3.0)
zt_lock_sshSecuritySSH port closed (Cloudflare Tunnel) (5.3.0)
backup_failBackupBackup failed
backup_staleBackupBackup overdue (no successful run in its window) (5.1.0)
cron_failCronCron job failed
ini_setPHPPHP setting changed (5.1.0)
yml_applycipi.ymlcipi.yml applied (5.1.0)
yml_failcipi.ymlcipi.yml invalid or could not be applied (5.1.0)
yml_post_failcipi.ymlA deploy.post step failed (5.2.3)
self_updateUpdatesCipi updated itself (5.1.0)
reset_root_passwordResetRoot SSH password reset
reset_db_passwordResetMariaDB root password reset
reset_valkey_passwordResetValkey password reset
api_configureAPIPanel API configured
api_updateAPIPanel API updated — only on a real package change since 5.4.0
api_upgradeAPIPanel API upgraded
api_sslAPIPanel API SSL installed
git_configureGitGit provider token configured
sync_exportSyncApps exported
sync_importSyncApps imported
sync_pushSyncApps pushed to remote
service_restartServicesService restarted
service_startServicesService started
service_stopServicesService stopped
search_installSearchMeilisearch installed (5.2.2)
search_enableSearchSearch enabled for an app (5.2.2)
search_disableSearchSearch disabled for an app (5.2.2)
search_key_rotateSearchSearch API key rotated (5.2.2)
search_upgradeSearchMeilisearch upgraded (5.2.2)
search_removeSearchMeilisearch removed (5.2.2)
package_installPackagesHost package installed (5.2.2)
package_removePackagesHost package removed (5.2.2)

Automatic alerts

Once configured, Cipi sends email notifications on:

  • Backup errors (S3 upload failures, dump errors, a corrupt archive) and, since v5.1.0, backups that are simply overdue (backup_stale)
  • Deploy results — since v5.1.0 both success and failure, from the CLI and the Git webhook alike, with the branch, release number, commit, author, duration and the post-deploy healthcheck verdict in the body
  • A release that failed its post-deploy healthcheck (deploy_health_fail), including what an automatic rollback did about it
  • System cron job failures (via the cipi-cron-notify wrapper)
  • App lifecycle events — notifies when an app is created, edited, or deleted, including server hostname, app name, domain, and PHP version
  • Sudo and su elevation — notifies when any user successfully elevates via sudo or su, including who ran it, target user (for su), SSH key, client IP, and TTY
  • Privileged SSH login — notifies when root or any sudoer logs in via SSH, including source IP, SSH key fingerprint, and key comment
  • SSH key changes — notifies when an SSH key is added to, removed from, or renamed on the cipi user, including hostname, IP, fingerprint, key comment, timestamp, and remaining key count. Rename alerts also include the old and new key name.

Every email notification includes a footer with the client IP (SSH_CLIENT) and the SSH key name used to authenticate, when applicable. The key name is resolved via SSH_USER_AUTH with an auth.log fallback when needed.

Security auth notifications

Cipi integrates PAM-based authentication notifications via pam_exec.so with ExposeAuthInfo enabled. When SMTP is configured, the system automatically sends email alerts on these security-relevant events:

  • Sudo and su elevation — triggered when any user successfully runs sudo or su. The notification includes the username, target user (for su), the TTY, SSH key, client IP, and timestamp.
  • Privileged SSH login — triggered when root or any user in the sudo group logs in via SSH. The notification includes the username, source IP address, SSH key fingerprint, and key comment (resolved from /var/log/auth.log fingerprint matching against authorized_keys).
  • SSH key changes — triggered when an SSH key is added to, removed from, or renamed on the cipi user via cipi ssh add, cipi ssh remove, or cipi ssh rename. The notification includes the hostname, server IP, key fingerprint, key comment, timestamp, and remaining key count. Rename alerts also include the old and new key name.
  • App lifecycle events — triggered when an app is created, edited, or deleted. The notification includes the server hostname, app name, domain, and PHP version.

Notifications run asynchronously in the background so they never delay login or command execution. If SMTP is not configured, the hooks fail silently with no impact on the system.

Security event log

Regardless of SMTP configuration, all notification events (SSH key changes, app lifecycle, password resets, sudo/su/SSH login, cron failures) are always logged to /var/log/cipi/events.log in a compact one-line format. The log is rotated daily with 1-year retention via logrotate.

Cron wrapper

The cipi-cron-notify utility wraps system cron jobs and sends a notification if the job exits with a non-zero code. This is useful for monitoring critical scheduled tasks.

Chat alert channels

Since v5.3.0, email is no longer the only way out of Cipi's notifications. Every trigger — deploys, backups, scans, SSH logins, healthchecks and monitor alerts — also fans out to Slack, Discord, Telegram, ntfy or a custom webhook. Channels do not need SMTP. And nothing changes until you add one: with no channel configured, delivery is email-only, exactly as before.

bash
cipi notifications channel add slack ops --url=https://hooks.slack.com/services/…
cipi notifications channel add discord team --url=https://discord.com/api/webhooks/…
cipi notifications channel add telegram oncall --token=<bot-token> --chat-id=<id>
cipi notifications channel add ntfy phone --url=https://ntfy.sh/my-topic --priority=high
cipi notifications channel add webhook pager --url=https://example.com/hooks/cipi

cipi notifications channel list [--json]   # secrets masked
cipi notifications channel test ops        # or: test all
cipi notifications channel disable ops     # keep it, stop sending
cipi notifications channel enable ops
cipi notifications channel remove ops

Channel ids are lowercase letters, digits and dashes, and unique on the server.

Type Options What arrives
slack --url= — an Incoming Webhook A text message: the subject in bold, then the body.
discord --url= — a channel webhook The same, truncated at Discord's 2,000-character cap.
telegram --token= — the bot token from @BotFather; --chat-id= — send /start to the bot, then read getUpdates (negative for groups) Plain text through the Bot API — no Markdown, so an underscore in a hostname cannot break it — truncated at Telegram's 4,096-character cap.
ntfy --url= — the topic URL; optional --priority=min|low|default|high|urgent Title, Priority and Tags headers. Urgent triggers — security events, failures, most monitor alerts — raise a default-priority channel to high.
webhook --url= Structured JSON, for anything else.
json
// POST body sent to a webhook channel
{
  "server": "web-01",
  "trigger": "deploy_fail",
  "subject": "…",
  "body": "…",
  "ts": 1789123456
}

Best-effort, never blocking

Each channel gets a 5-second timeout, and a failed delivery is only logged to /var/log/cipi/events.log: a slow or dead webhook can never stall a deploy or a cron run. Channels are stored encrypted in /etc/cipi/alerts.json; channel list masks the secret part of webhook URLs and shows only the start of a bot token.

Channels follow the same triggers as email: cipi notifications disable <trigger> mutes that event everywhere, and there is no per-channel filter. A chat message carries the same body as the email, footer included.

Migration 5.3.0 writes an empty alerts.json and configures no channel and no trigger. To see what an alert looks like everywhere at once, run cipi monitor test.

Log Retention (GDPR)

Cipi enforces automatic log rotation policies designed to meet GDPR and general data protection requirements. Logs are rotated and deleted automatically — no manual cleanup needed.

Category Logs Retention
Application Laravel, PHP-FPM, workers, deploy, system 12 months
Security Fail2ban, UFW firewall, authentication, Cipi events (events.log) 12 months
HTTP / Navigation Nginx access and error logs 90 days
HTTP/navigation logs (nginx access logs) contain IP addresses, which are personal data under GDPR. The 90-day retention ensures compliance with the data minimization principle while preserving enough history for debugging and security analysis. Application and security logs are retained for 12 months to support audit trails and incident investigation.

Laravel logs: fixed in 5.5.0

Up to 5.4 the 12-month policy did not actually reach Laravel logs. Apps were created with LOG_CHANNEL=daily, so every day had its own file, and logrotate rotated each of those files exactly once: the content landed in laravel-<date>.log.1, which was never compressed (delaycompress waits for a second rotation that never came) and never deleted (rotate 365 counts rotations per file, and every date is its own file).

Since v5.5.0 Laravel apps write one storage/logs/laravel.log (LOG_CHANNEL=single), and the cipi-app-logs rule rotates it daily, compressed from the second day, for 365 rotations. The rule's Laravel pattern is now storage/logs/*[!0-9].log, so a log whose name ends in a date is left to Laravel: an app that sets LOG_CHANNEL=daily on purpose is pruned by Laravel itself after LOG_DAILY_DAYS. The 5.5.0 migration switches existing apps and folds their dated history into laravel.log, from where it leaves through the normal rotation.

Valkey

Valkey is the in-memory data store that Cipi installs as part of the default stack. Since v4.5.6 Cipi provisions Valkey instead of redis-server. It excels at caching, session storage, message queues, real-time broadcasting, and rate limiting.

One instance per app (v5.9.0+)

Until 5.9.0 the server had one Valkey and one password, and every app got it in its .env: any app could read and write the cache, the sessions and the queued jobs of every other app, and one FLUSHDB emptied them all. An app now has an instance of its own — cipi-valkey@<app>.service, running as the app's user, listening on 127.0.0.1 on a port of its own (from 6400), with its own password (REDIS_HOST, REDIS_PORT, REDIS_PASSWORD in the app's .env), its configuration in /etc/cipi-valkey/<app>.conf and its data in /var/lib/cipi-valkey/<app>. An idle instance costs about 10 MB of RAM.

bash
cipi valkey list [--json]         # which app uses which instance
cipi valkey isolate shop          # its own instance: keys copied, .env switched, workers restarted
cipi valkey isolate --all         # every app still on the shared one
cipi valkey share shop            # back to the shared instance
cipi valkey restart shop
cipi valkey flush-shared          # once nobody uses it: empty it and change its password
  • New Laravel apps get their instance from cipi app create (--valkey=shared keeps the old behaviour for one app). It is removed with the app.
  • Apps that exist are not touched until you run isolate. The app goes into maintenance mode, its workers stop, its keys are copied with their expiry — by the key prefix the application itself reports — the .env is switched, the config cache rebuilt, workers (queue, Horizon, Octane, Reverb) restarted, maintenance mode off: seconds. A copy that is refused leaves the app exactly where it was.
  • An app whose prefix cannot be read (no release deployed yet, an empty prefix) is not moved unless you pass --no-copy: it then starts empty, without maintenance mode. An app whose .env points Redis at another host, or through REDIS_URL, is left alone.
  • --maxmemory=256mb and --policy=allkeys-lru set a ceiling for the instance; without them it behaves like the shared one.
  • cipi app clone gives the clone its own instance and no longer copies the source's REDIS_*; cipi sync keeps this server's Valkey settings for an app that exists and gives an imported one an instance here.
  • cipi pending lists the apps still on the shared instance; a Valkey package upgrade restarts every instance.

Why Valkey instead of Redis

Valkey is the truly open-source, BSD-licensed fork of Redis, stewarded by the Linux Foundation. It was created in 2024 after Redis Inc. relicensed Redis away from the permissive BSD license to the source-available SSPL / RSALv2 — a change that no longer met the open-source definition. Backed by AWS, Google Cloud, Oracle, and a large community, Valkey continues the same battle-tested codebase under a license that stays free forever. That makes it a perfect fit for Cipi's MIT, no-vendor-lock-in philosophy, and it ships natively in Ubuntu 24.04's Universe repository (packages valkey-server + valkey-tools) — no third-party PPA to trust.

Just as importantly, Valkey is a drop-in replacement: it speaks the exact same RESP protocol on the same port (127.0.0.1:6379), honours the same requirepass / bind directives, and reads the same RDB/AOF data format. Your apps need zero changes — the phpredis extension and your existing REDIS_* .env values keep working exactly as before.

How Cipi implements it

  • Install — setup.sh installs and configures Valkey (/etc/valkey/valkey.conf, service valkey-server), bound to localhost only and protected with a password.
  • Service management — cipi service … manages valkey-server (the names redis-server, redis, and valkey are still accepted as aliases). It is added to the unattended-upgrades blacklist, so Cipi manages it instead of an automatic upgrade.
  • Credentials — stored under valkey_user / valkey_password in /etc/cipi/server.json (the legacy redis_* keys are still read as a fallback). Host: 127.0.0.1, Port: 6379.
  • Password reset — cipi reset valkey-password regenerates the password and restarts the service (cipi reset redis-password stays as an alias).

Migrating from Redis (4.5.6 / 4.5.7)

Existing servers are switched to Valkey automatically on cipi self-update — no app .env editing required. The migration reuses the current Redis password (recovered from server.json or /etc/redis/redis.conf), forces an RDB SAVE and snapshots dump.rdb/AOF, purges redis-server, installs valkey-server + valkey-tools on the same port with the same requirepass / bind, restores the dataset, and rewrites server.json (redis_* → valkey_*) and the unattended-upgrades blacklist — so cache, sessions, and queued jobs survive the switch.

v4.5.7 corrects the package name to valkey-server (the Ubuntu 24.04 daemon package; 4.5.6 initially used valkey) and makes the migration fully self-contained and safe. It auto-enables the universe APT component when the package isn't found, runs a post-start health check (PING → PONG with the password), and rolls back to redis-server — restoring both the saved password and the dataset — if Valkey can't be installed or doesn't come up healthy. The dataset snapshot is kept until the switch is verified, then cleaned up. The migration is idempotent: servers already on Valkey skip it.

Laravel integration

New apps use the database driver for cache, sessions and queues: Valkey is one instance with one password for every app of the server, and whoever has the password can read — and flush — every app's keys. The database driver keeps each app inside its own database and user. Switch an app to Valkey when you want it (faster cache and queues, Horizon, Reverb scaling) and trust every app on the server with that.

The password is in the installation summary; cipi reset valkey-password sets a new one and prints it (every app that uses Valkey then needs it). Add these variables with cipi app env myapp. The names stay REDIS_* — that is what phpredis and Laravel's redis driver expect, and Valkey answers on the very same socket:

env
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=the-valkey-password
REDIS_PORT=6379
REDIS_PREFIX=myapp_   # one per app, so keys never collide

Then set the drivers for each use case:

  • Cache — CACHE_STORE=redis
  • Session — SESSION_DRIVER=redis
  • Queue — QUEUE_CONNECTION=redis (then cipi worker restart myapp)
  • Broadcasting — BROADCAST_CONNECTION=redis

The phpredis extension is installed with every PHP version Cipi installs; predis/predis works too, as a pure-PHP fallback. Both talk to Valkey transparently.

Self-Update

Cipi can update itself from GitHub without affecting any app, database, or configuration.

bash
cipi self-update --check   # check for a new version
cipi self-update           # update to latest

Update process

  1. Downloads the latest version from GitHub
  2. Backs up the current installation to /opt/cipi.bak.YYYYMMDDHHMMSS/
  3. Replaces CLI and lib scripts
  4. Runs any pending migration scripts in order (e.g. new Nginx directives, new packages)
  5. Updates the version file

Migration scripts live in lib/migrations/ and are named by version (e.g. 4.1.0.sh, 5.0.18.sh). When updating from v4.0.0 to v4.2.0, Cipi automatically runs 4.1.0.sh and 4.2.0.sh in order. Your apps, databases, and configurations are never touched.

Recent migrations improve reliability without changing app data: 5.0.6 — default IP whitelist file and regenerated API sudoers; 5.0.9 — cipi php switch in sudoers for PUT /api/php/default; 5.0.13 — reclaim API/GUI ownership after update; 5.0.14–5.0.17 — timed GitHub/Packagist panel package updates (no more hung cipi self-update on API/GUI Composer VCS clones); 5.0.18 — repair Panel GUI after symlink/open_basedir HTTP 500 (cipi gui fix-permissions). Run cipi self-update to reach 5.1.0.

Migration 5.1.0

The 5.1.0 migration is the largest of the 5.x line. On an existing server it:

  • installs the automatic-deploy wrapper and repoints each app's webhook cron at it;
  • backfills the CLI 99-cipi.ini and rewrites FPM pools so they inherit the server-wide file — see cipi ini;
  • converts the hardcoded nightly backup job into a default backup profile, carrying over its existing --weeks retention;
  • takes over the backup schedule with the managed crontab block;
  • claims the :443 default server when nothing else does.

Every step degrades to a warning and carries on. That matters: on an early 5.1.0 build a grep that matched nothing could fail the migration under set -o pipefail, and a failed migration makes cipi self-update refuse the release and retry it, failing again, every night.

Migrations 5.4.0 and 5.4.1

5.4.0 turns on the deploy audit ledger for existing apps: it installs cipi-deploy-audit, adds one sudoers rule per app (validated with visudo and restored if rejected), appends the audit hooks to each deploy.php without touching the rest of the file, switches the deploy-trigger cron from rm to mv, and writes the audit start marker.

It also moves servers off Node 20, which reached end of life in April 2026:

  • Fresh installs: setup.sh installs Node 22 from NodeSource.
  • Servers still on Node 20 (the NodeSource package, or cipi node default 20) are switched with cipi node default 22, which downloads and verifies the official build and links it into /usr/local/bin ahead of /usr/bin. The NodeSource package is not touched, so cipi node default system restores 20. Laravel asset builds, cipi app run npm and deploy.post use 22 from their next run.
  • Servers on another major, or with no Node at all, are left as they are.
  • A failed download leaves the server on 20, prints how to retry and lets the update carry on. A node_default notification is sent.

5.4.1 regenerates /etc/sudoers.d/cipi-api so the panel API can drive redirects, proxies and Node apps. Neither migration deploys, reloads or restarts anything.

Migration 5.5.0

The 5.5.0 migration moves Laravel apps from dated log files to one laravel.log — see log retention. It runs for every Laravel app; custom and Node apps are not touched:

  1. Rewrites /etc/logrotate.d/cipi-app-logs with the new storage/logs/*[!0-9].log pattern.
  2. In shared/.env, LOG_CHANNEL=daily becomes single, and so does a daily inside LOG_STACK. Any other channel (stack, stderr, slack, …) is left as it is. The rewrite runs as the app user and goes through a copy that replaces the .env in one rename, with the same owner and mode: the file is never truncated in place, so a write that fails (a full disk) leaves it exactly as it was. An .env the app user cannot rewrite is reported with a warning.
  3. Where the .env changed, so that no process keeps the old channel in memory:
    • artisan config:cache as the app user, if the current release has a cached config. Other .env edits that were waiting for a deploy become active with it.
    • SIGTERM to the app's running Supervisor programs (queue workers, Horizon, Octane, Reverb). They finish the job in hand and Supervisor starts them again; stopped programs stay stopped. Octane and Reverb drop their connections for the few seconds of the restart, as on a deploy.
    • One systemctl reload of PHP-FPM per PHP version in use by those apps.
  4. Folds the dated files into laravel.log, oldest first: laravel-<date>.log, .log.N, .log.N.gz and the empty stubs. It runs as the app user. A file is removed only after its content is in laravel.log; an existing laravel.log is appended to, never replaced; a file a process still has open, or an archive that cannot be read, is left where it is and named in the output.
Unlike the 5.4 migrations, this one restarts processes: running workers, Horizon, Octane and Reverb get a graceful SIGTERM, and PHP-FPM is reloaded. The nightly cipi self-update (03:50) will apply it unattended — if you would rather watch Octane and Reverb reconnect, run cipi self-update yourself first. The migration also needs free disk space for one uncompressed copy of an app's dated logs while it folds them; if that fails, the app's files are left as they were. A second run finds nothing to do.

Everything else in 5.5.0 needs no migration step: cipi disk, cipi firewall attempts, cipi ssh apps, the named Cloudflare accounts and the soft disk limits change nothing until they are used, and the tab-completion fixes arrive with the completion files self-update rewrites on every run.

Migration 5.5.1

From 5.5.1 Cipi writes the HTTPS server block of every vhost itself and certbot only issues and renews (wildcard domains). The migration brings existing servers in line:

  1. Writes the certbot deploy hook /etc/letsencrypt/renewal-hooks/deploy/cipi-reload-nginx (nginx -t -q && systemctl reload nginx), so nginx serves a renewed certificate whether certbot.timer or Cipi's weekly cron renewed it.
  2. Removes --nginx from the certbot renew line of root's crontab: on the command line it overrode how each certificate was issued, and would have renewed a DNS-01 wildcard over HTTP-01.
  3. Writes /etc/nginx/snippets/cipi-ssl.conf (TLS 1.2/1.3, Mozilla intermediate ciphers), included by every HTTPS block Cipi writes.
  4. Apps whose certificate renews over DNS-01 but are not recorded as DNS-01 — the install stopped at the old certbot install step — get ssl_dns_provider and ssl_dns_account; a certificate issued with --wildcard gets ssl_wildcard. The next cipi ssl install keeps DNS-01 and the wildcard.
  5. Rewrites, with the HTTPS block written by Cipi, the vhost of every app that has a certificate and a wildcard name, a Cloudflare Origin CA certificate, or no HTTPS in its vhost at all. One app at a time, with nginx -t after each: the previous file is kept in /var/lib/cipi/vhost-backup-5.5.1 and put back if nginx refuses the new one.

Other apps keep their certbot-written vhost until it is next regenerated (any alias, www, basic auth, redirect or proxy change), which switches it. No certificate is requested or renewed, and nothing is deployed. cipi ssl status then shows, per app, what it is served with and which of its names the certificate does not cover.

Migration 5.5.2

From 5.5.2 the panel API can run cipi disk. The migration regenerates /etc/sudoers.d/cipi-api so www-data may run cipi disk and cipi disk * (--json, db --json). Nothing else on the server changes, and nothing is deployed. cipi disk itself has existed since 5.5.0; until this sudoers line, GET /api/disk and GET /api/disk/dbs (API 1.33.0+, ability disk-view) answer 503. Setting a soft limit was already on the API in 1.32.0.

The same release also ships the cipi.yml fixes in the CLI itself: deploy.node_build, predeploy_snapshot, cipi yml generate --save, removal of backup profiles the file no longer lists, and a cipi.yml line on the deploy-success mail. Those arrive with the updated scripts and need no further migration step. See cipi.yml.

When the update itself fails

Up to 5.0.x, cipi self-update reported only “Download failed” — git's stderr was discarded, so the one message that explains what happened (no DNS, no outbound HTTPS, a missing branch, a full disk, an expired CA bundle) never reached anyone. Since v5.1.0 the real error is printed, the likely cause is named, and the command to reproduce it by hand is shown. The clone also runs under a 180-second timeout instead of being able to hang indefinitely, and a missing git is reported as such. An unattended nightly update now also sends the self_update notification, so it no longer lands without a word. Since v5.2.1 that mail is decided from a snapshot taken before /etc/cipi/version is rewritten, and is sent only when that snapshot differs from the downloaded version. A nightly refresh that stays on the same release is silent. 5.2.1 itself has no migration: self-update copies the libs and refreshes shell completion.

For example, the 4.5.5 migration retro-fits existing apps with the new ll='ls -al' shell alias: it appends the alias to each app's ~/.bashrc once (only when missing, preserving ownership), so apps created before 4.5.5 get it on the next cipi self-update.

Automatic maintenance crons

Cipi schedules several root-level jobs during installation. App-level crontabs (scheduler, deploy trigger) are separate — see User crontab.

Schedule Job
Daily 02:00 cipi backup run — S3 backups for all apps
Daily 03:00 cipi backup prune --weeks=4
Daily 03:30 cipi php upgrade — security patches for all installed PHP versions (wrapped by cipi-cron-notify; weekly on Sundays before 5.6.3)
Daily 03:50 cipi self-update (wrapped by cipi-cron-notify)
Sun 04:10 cipi ssl renew
Daily 04:15 Panel API maintenance (cipi-api-maintain — prune jobs/metrics)
Daily 04:30 cipi api update — soft-update panel Laravel + cipi/api

Wildcard domains & certificates

Yes, Cipi does wildcards — one app answering on every <tenant>.myapp.com, with one certificate that covers all of them. It takes two separate things, and most problems come from having only one of them:

  • Routing — Nginx sends *.myapp.com to the app when the pattern is one of its names: cipi alias add myapp '*.myapp.com' (or a wildcard primary domain). Works since v5.1.0, whatever DNS or certificate you use.
  • Certificate — Let's Encrypt validates a wildcard name over DNS-01 only: it asks for a TXT record in the zone. Cipi creates that record through the Cloudflare API, the only DNS provider it automates: cipi ssl install myapp --dns=cloudflare. HTTP-01 (the default, through port 80) can never issue a wildcard.

Since v5.5.1 Cipi writes the HTTPS server block of the vhost itself; certbot only issues and renews the certificate. Before that, a wildcard certificate was issued and then failed to install (Which server blocks would you like to modify? — certbot's nginx installer cannot be driven non-interactively for a wildcard name), and the next vhost change dropped HTTPS without a word. If that happened to you, cipi self-update: the 5.5.1 migration installs the certificate that is already on disk.

Which setup is yours

DNS of the zone Wildcard certificate Cloudflare SSL/TLS mode Commands
Cloudflare, proxied (orange cloud)
— recommended for a SaaS
Let's Encrypt over DNS-01 (proxy can stay on)
— or Cloudflare Origin CA
Full (strict) steps below
Cloudflare, DNS only
(grey cloud)
Let's Encrypt over DNS-01 not used
(traffic does not go through Cloudflare)
steps below, skip the SSL/TLS mode
Another DNS provider not by Cipi — move the DNS to Cloudflare (free),
list the subdomains, or bring your own certificate
— without Cloudflare
Cloudflare Tunnel
(cipi zt hostname add)
not needed: Cloudflare terminates HTTPS,
the tunnel talks HTTP to :80
set by the tunnel cipi zt

With Cloudflare — step by step

  1. DNS records in the Cloudflare dashboard: A @ → <server-ip> and A * → <server-ip> (AAAA too if the server has IPv6). The * record also covers www, app, admin… unless a record with that exact name exists. Proxied or DNS only: both work, wildcard records can be proxied on every plan.
  2. API token — Cloudflare → My Profile → API Tokens → Create Token → template Edit zone DNS, Zone Resources: Include → Specific zone → myapp.com. The only permission needed is Zone → DNS → Edit.
  3. Give it to Cipi, once per server (several accounts: --name=).
  4. Route the subdomains to the app with a wildcard alias. Quote it, so the shell does not expand the *.
  5. Issue the certificate over DNS-01. Cipi asks for myapp.com + *.myapp.com + any other alias the wildcard does not cover, writes the HTTPS vhost and redirects every subdomain from HTTP to HTTPS. It takes about a minute (Cipi waits 30 seconds for the TXT record to propagate).
  6. Proxied records only: Cloudflare → SSL/TLS → Overview → Full (strict). Also check Rules → Configuration Rules / Page Rules: a rule that sets SSL to Flexible for a hostname wins over the global setting.
  7. Check — cipi ssl status lists every app with the certificate it is served with and the names that certificate does not cover.
bash
cipi ssl dns set --token=YOUR_CLOUDFLARE_TOKEN          # step 3
cipi alias add myapp '*.myapp.com'                        # step 4
cipi ssl install myapp --dns=cloudflare                 # step 5
cipi ssl status                                          # step 7
curl -sI https://tenant1.myapp.com | head -1             # HTTP/2 200 (or your app's answer)

Renewals need nothing: each certificate renews the way it was issued (certbot.timer twice a day, plus Cipi's weekly cron), with the Cloudflare token it was issued with, and nginx reloads after every renewal. A certificate issued over DNS-01 is always reissued over DNS-01 — cipi ssl install myapp without flags keeps it (--http goes back to HTTP-01 on purpose).

--wildcard adds myapp.com + *.myapp.com to the certificate even when the app does not serve *.myapp.com — useful to cover many explicit aliases with one name. It does not route anything: subdomains reach the app only through the wildcard alias. The flag is remembered for later reissues; --no-wildcard drops it.

Cloudflare proxy: the SSL/TLS mode decides everything

With the orange cloud, the visitor talks HTTPS to Cloudflare, and Cloudflare opens a second connection to your server. The SSL/TLS mode says how:

  • Flexible — never with Cipi. Cloudflare connects to http:// on port 80. As soon as the app has a certificate, Cipi answers port 80 with a redirect to HTTPS, which Cloudflare fetches again over HTTP: an endless loop (ERR_TOO_MANY_REDIRECTS). Without a certificate it "works", but Laravel sees plain HTTP and builds http:// URLs.
  • Full — Cloudflare connects over HTTPS and accepts any certificate. Works, but does not protect the second hop.
  • Full (strict) — HTTPS with a valid certificate for the hostname: the Let's Encrypt certificate from Cipi, or a Cloudflare Origin CA one. The right setting.

Order for a new site behind the proxy: issue the certificate first with --dns=cloudflare (DNS-01 does not care about the proxy, the firewall or port 80), then switch to Full (strict). HTTP-01 behind the proxy depends on Cloudflare settings (Always Use HTTPS, WAF rules, Under Attack mode, cipi zt lock http) — you do not need to turn the proxy off and on again if you use DNS-01. The edge certificate Cloudflare shows to visitors (Universal SSL, free) covers myapp.com and *.myapp.com: one level of subdomains. Deeper names (a.b.myapp.com) need Cloudflare's Advanced Certificate Manager at the edge, and their own wildcard at the origin.

You see What it means on a Cipi server Fix
ERR_TOO_MANY_REDIRECTS SSL/TLS mode Flexible (or a Configuration Rule setting it for that host) Full (strict)
525 SSL handshake failed No app on the server has that hostname, or the app has no certificate: the catch-all default server refuses the TLS handshake cipi alias add myapp '*.myapp.com', then cipi ssl install myapp --dns=cloudflare
526 Invalid SSL certificate Full (strict) and the origin certificate does not cover that hostname (e.g. a tenant with a certificate issued without the wildcard) cipi ssl status → “not covered” → cipi ssl install myapp --dns=cloudflare
520 / empty reply on a subdomain Flexible mode and the hostname matches no app: port 80's catch-all closes the connection (444) wildcard alias, Full (strict)
500 from the app on a tenant Nginx and the certificate are fine — the request reached Laravel (tenant resolver, .env, logs: cipi app logs myapp) application side

Alternative behind the proxy: Cloudflare Origin CA

A certificate signed by Cloudflare, valid 15 years, trusted only by Cloudflare: fine for proxied records with Full (strict), a browser warning for a DNS-only record. It covers the app's names, wildcard alias included. It needs the cipi zt API token (Zone → SSL and Certificates → Edit), not the DNS-01 one. Since 5.5.1 it works on an app that never had HTTPS, and survives every vhost change.

bash
cipi zt token set --token=ZT_TOKEN --account=ACCOUNT_ID
cipi alias add myapp '*.myapp.com'
cipi zt origin-cert myapp       # reissue after adding names

Without Cloudflare

When the zone is hosted elsewhere, Cipi cannot create the TXT record, so it cannot issue a wildcard certificate. Routing still works (cipi alias add myapp '*.myapp.com' plus a * record at your provider), but HTTPS needs one of these:

  1. Move the DNS to Cloudflare (recommended) — free plan, records set to DNS only: traffic does not change, only who answers DNS. Then follow the Cloudflare steps and skip the SSL/TLS mode.
  2. List the subdomains — when tenants are few and known, add each one as an alias (no wildcard) and let HTTP-01 issue one certificate for all of them: cipi alias add myapp acme.myapp.com, then cipi ssl install myapp. Every name needs its own DNS record (or the * record), port 80 must be reachable, a certificate holds at most 100 names, and every reissue counts toward Let's Encrypt's limit of 50 certificates per domain per week — not a fit for self-service signup.
  3. Bring your own certificate — issue it with the certbot DNS plugin of your provider (Route 53, DigitalOcean, OVH, Gandi, …) under the certificate name Cipi expects: the app's primary domain (without *. for a wildcard primary). Cipi finds it in /etc/letsencrypt/live/<name>/ and serves it; certbot renews it with your plugin and Cipi's hook reloads nginx. Do not run cipi ssl install on that app afterwards: without --dns=cloudflare it reissues over HTTP-01, without the wildcard.
bash
# option 3, example with Route 53 (credentials as the plugin documents them)
apt install python3-certbot-dns-route53
certbot certonly --dns-route53 -d myapp.com -d '*.myapp.com' --cert-name myapp.com
cipi alias add myapp '*.myapp.com'      # rewrites the vhost with the certificate
cipi ssl force myapp                    # or this, if the alias was already there

Multi-tenant apps: good to know

  • Other apps still win on their exact names. With *.myapp.com on one app, api.myapp.com can still be a separate app: Nginx prefers an exact server_name to a wildcard.
  • Unknown hosts are closed by cipi nginx default-server (on by default) instead of reaching your tenant resolver.
  • Laravel: set SESSION_DOMAIN=.myapp.com only if a login must be shared across subdomains; resolve the tenant from the Host header. APP_URL is set to https://www.myapp.com for a wildcard primary.
  • Depth: Nginx's *.myapp.com also matches a.b.myapp.com, certificates do not — keep tenants one label deep.
  • One app per tenant is the alternative when tenants need isolation (own database, own backups, movable to another server): create each tenant as its own Cipi app with its exact domain through the Cipi API, and its DNS record through the Cloudflare API — every tenant then gets a plain HTTP-01 certificate.

Edit Nginx config

To customise the Nginx vhost for an app, edit the site config directly. After changes, test and reload Nginx.

bash
sudo nano /etc/nginx/sites-available/<app>
sudo nginx -t && sudo systemctl reload nginx

Uninstall Cipi

Cipi does not provide a built-in uninstall command. If you need to completely remove Cipi from a server, follow the steps below in order. This procedure removes every component that Cipi installs — users, services, packages, configs, and data.

This is a destructive and irreversible operation. All apps, databases, SSL certificates, and server configurations managed by Cipi will be permanently deleted. Back up everything you need before proceeding. After uninstalling, the recommended approach is to reprovision the server from scratch.

1 — Stop and remove all apps

For each app managed by Cipi, remove its system user, home directory, database, nginx vhost, PHP-FPM pool, and supervisor config.

bash
# List all app users (members of cipi-apps group)
grep cipi-apps /etc/group

# For EACH app user, remove everything
supervisorctl stop <app_user>:*
rm -f /etc/supervisor/conf.d/<app_user>.conf
rm -f /etc/nginx/sites-enabled/<app_user>
rm -f /etc/nginx/sites-available/<app_user>
rm -f /etc/php/*/fpm/pool.d/<app_user>.conf
rm -f /etc/sudoers.d/cipi-<app_user>
mysql -e "DROP DATABASE IF EXISTS <app_user>; DROP USER IF EXISTS '<app_user>'@'localhost'; DROP USER IF EXISTS '<app_user>'@'127.0.0.1';"
userdel -r <app_user>

2 — Remove the Cipi user and groups

bash
userdel -r cipi
groupdel cipi-ssh 2>/dev/null
groupdel cipi-apps 2>/dev/null

3 — Remove Cipi binaries, libraries, and data

bash
rm -f /usr/local/bin/cipi
rm -f /usr/local/bin/cipi-worker
rm -f /usr/local/bin/cipi-cron-notify
rm -f /usr/local/bin/cipi-auth-notify
rm -rf /opt/cipi
rm -rf /etc/cipi
rm -rf /var/log/cipi

4 — Remove Cipi API (if installed)

bash
systemctl stop cipi-queue 2>/dev/null
systemctl disable cipi-queue 2>/dev/null
rm -f /etc/systemd/system/cipi-queue.service
systemctl daemon-reload

5 — Remove Cipi cron jobs

bash
# Edit root crontab and remove all Cipi entries
crontab -e
# Remove lines referencing: cipi self-update, certbot renewal, cache cleanup, RAM drop

6 — Remove Cipi configuration files

bash
# Sudoers
rm -f /etc/sudoers.d/cipi-sudo
rm -f /etc/sudoers.d/cipi-api

# Logrotate
rm -f /etc/logrotate.d/cipi-app-logs
rm -f /etc/logrotate.d/cipi-http-logs
rm -f /etc/logrotate.d/cipi-security-logs

# Unattended upgrades
rm -f /etc/apt/apt.conf.d/50cipi-unattended-upgrades
rm -f /etc/apt/apt.conf.d/20cipi-auto-upgrades

# System profile and MOTD
rm -f /etc/profile.d/cipi-env.sh
echo "" > /etc/motd

# MariaDB custom config
rm -f /etc/mysql/mariadb.conf.d/99-cipi.cnf

# PHP custom config (all versions)
rm -f /etc/php/*/fpm/conf.d/99-cipi.ini

# Nginx default page
rm -f /etc/nginx/sites-available/default
rm -f /etc/nginx/sites-enabled/default

7 — Purge installed packages

Remove all packages that Cipi installed. Skip any package you want to keep for other purposes.

bash
systemctl stop nginx mariadb valkey-server fail2ban supervisor
systemctl stop php*-fpm

apt purge -y nginx* mariadb-server mariadb-client valkey-server \
    fail2ban supervisor certbot python3-certbot-nginx \
    php8.4* php8.5* nodejs

apt autoremove -y
apt autoclean

8 — Remove APT repositories

bash
add-apt-repository --remove ppa:ondrej/php -y
rm -f /etc/apt/sources.list.d/php-sury.list
rm -f /etc/apt/sources.list.d/mariadb.list
rm -f /etc/apt/sources.list.d/nodesource.list
rm -f /etc/apt/keyrings/mariadb-keyring.pgp
apt update

9 — Remove Composer and Deployer

bash
rm -f /usr/local/bin/composer
rm -f /usr/local/bin/dep

10 — Remove swap file

bash
swapoff /var/swap.1
rm -f /var/swap.1
# Remove the swap entry from /etc/fstab
sed -i '/swap\.1/d' /etc/fstab

11 — Restore SSH and PAM defaults

Cipi hardens SSH (disables root login and password auth) and adds PAM hooks. If you need to restore defaults:

bash
# Restore sshd_config to allow password auth (if needed)
sed -i 's/^PasswordAuthentication no/PasswordAuthentication yes/' /etc/ssh/sshd_config
sed -i 's/^PermitRootLogin no/PermitRootLogin yes/' /etc/ssh/sshd_config

# Remove Cipi PAM hooks
sed -i '/cipi-auth-notify/d' /etc/pam.d/sshd
sed -i '/cipi-auth-notify/d' /etc/pam.d/sudo

# Restore sysctl
sed -i '/vm.swappiness/d' /etc/sysctl.conf
sysctl -p

systemctl restart sshd

12 — Reset firewall

bash
ufw disable
ufw reset
After a full uninstall, the server will be stripped of its web stack and security hardening. The recommended approach is to reprovision the server from a clean OS image rather than trying to reconfigure the same machine. Use this guide primarily to clean up before a fresh start, or to selectively remove Cipi components while keeping packages you still need.