Apps

cipi app create

cipi app create supports two app types: Laravel (default) and Custom (--custom). Laravel apps get a fully isolated environment: Linux user, PHP-FPM pool or Laravel Octane (FrankenPHP) since v5.0, Nginx vhost, database (MariaDB by default; optional PostgreSQL since v4.8.0), Supervisor worker, crontab entry, Deployer zero-downtime releases, SSH deploy key, and auto-compiled .env. Custom apps are simpler — see custom apps for details.

Laravel app (default — PHP-FPM)

$ cipi app create

Laravel Octane (FrankenPHP)

$ cipi app create --octane
$ cipi app create --octane=frankenphp   # explicit (same as --octane)

See Laravel Octane for requirements, convert, and how the vhost differs from FPM.

Non-interactive (flags)

$ cipi app create \
    --user=myapp \
    --domain=myapp.com \
    --repository=git@github.com:you/myapp.git \
    --branch=main \
    --php=8.5

# Laravel Octane (FrankenPHP) — v5.0+
$ cipi app create --user=myapp --domain=myapp.com \
    --repository=git@github.com:you/myapp.git --octane

# optional PostgreSQL (v4.8.0+, after cipi db install pgsql)
$ cipi app create --user=myapp --domain=myapp.com \
    --repository=git@github.com:you/myapp.git --engine=pgsql

Apps

Laravel Octane (FrankenPHP)

Since v5.0, Laravel apps can serve HTTP via Laravel Octane with the FrankenPHP server instead of a per-app PHP-FPM pool. Octane and classic FPM apps run side by side on the same Cipi server.

What Cipi configures

• Allocates a localhost port in 8100–8999 and stores octane / octane_port in apps.json
• Nginx vhost uses proxy_pass to Octane and serves static files from current/public — no per-app FPM pool
• Supervisor program ${app}-octane alongside queue workers
• Deployer template laravel-octane.php restarts / reloads Octane on deploy
• .env: OCTANE_SERVER=frankenphp, OCTANE_HTTPS=true

App requirements

Your Laravel repository must include laravel/octane and run php artisan octane:install --server=frankenphp. Octane starts after the first successful deploy.

# create an Octane app
$ cipi app create --user=myapp --domain=myapp.com \
    --repository=git@github.com:you/myapp.git --octane

# convert an existing FPM app → Octane (or the reverse)
$ cipi app convert myapp --to=octane
$ cipi app convert myapp --to=fpm

# tune Octane workers (also see app limits)
$ cipi app limits myapp --octane-workers=4

cipi app convert --to=octane|fpm rewrites the pool / vhost / Supervisor / Deployer template / .env, and re-applies SSL when a certificate is already present.

cipi app create --custom

Creates a custom app with classic deploy (no zero-downtime): code is deployed into htdocs — no current/shared symlinks. Ideal for static sites, SPAs (Vue, React, Svelte), WordPress, other CMS, or any non-Laravel PHP project or framework.

During creation you only choose the document root (default /, or e.g. www, dist, public). Nginx is pre-configured with index index.html index.php, try_files $uri $uri/ /index.php?$args, and error_page 404 /404.html — no prompts for try_files or entry point.

Git optional (SFTP-only)

The Git repository is optional for custom apps. Laravel apps still require a repository. If you skip the repository for a custom app, Cipi creates /home/<app>/htdocs with a placeholder index.html and does not configure a deploy key or webhook — you upload files with SFTP (or SCP/rsync) to ~/htdocs as the app user. The onboarding output explains this “no repo — SFTP only” workflow. If you do provide a repository, behavior is unchanged: use cipi deploy <app> to pull code into htdocs.

What’s included and what you add

Custom apps have no database, no .env, no cron, and no queue workers. When a repository is configured, a deploy key and (with Git auto-setup) webhook are shown; for SFTP-only apps, those are omitted. The post-creation summary lists SSH access and next steps accordingly.

If your custom app needs a database (e.g. WordPress, Drupal), create one with cipi db create --name=<app> after deployment. See cipi db for backup, restore, and password management.

With Git — non-interactive example:

$ cipi app create --custom --user=mysite --domain=mysite.com \
    --repository=git@github.com:you/mysite.git --docroot=dist

SFTP-only — omit --repository and --branch:

$ cipi app create --custom --user=mysite --domain=mysite.com --docroot=dist

With a repository, use cipi deploy <app> to deploy; code is cloned into /home/<app>/htdocs.

app list / app show / app edit / app delete

cipi app fix-permissions

The panel already had cipi api fix-permissions and cipi gui fix-permissions; apps did not. A blunt chown -R app:app /home/<app> is wrong: nginx writes vhost logs as www-data into logs/ (2775 setgid), the home must stay 750 so www-data (in the app group) can read the docroot, .ssh must be 700 or OpenSSH StrictModes refuses the deploy key, and shared/.env is 640. This command reapplies that layout — ownership of the tree except logs/, then the log/ACL helper, storage dirs 775, Composer auth.json 640, cipi-databases.env 600. One named app, or every app.

$ cipi app fix-permissions myapp
$ cipi app fix-permissions          # every app on this server

cipi deploy already runs the log-ACL helper before Deployer. fix-permissions is the full home, on demand, after someone unpacked a zip as root or chmod'd .ssh to 775. Available since v5.2.1. No migration: cipi self-update copies the libs and refreshes shell completion. The panel sudoers file lists the new command so a future GUI can call it; existing servers pick that line up the next time sudoers is rewritten (the CLI runs as root and does not need it).

cipi app reverb

Laravel Reverb is Laravel's first-party WebSocket server. Cipi has run it since v5.0; v5.1.2 is the release that made it work in production — generated credentials, a scheme derived from the certificate, raised connection limits, and a proxy rule that no longer swallows your own routes.

Enabling Reverb on a Laravel app wires four things:

$ cipi app reverb enable myapp
$ cipi app reverb enable myapp --restart-supervisor   # also apply the new open-file limit now
$ cipi app reverb status myapp
$ cipi app reverb disable myapp

Reverb is Laravel only — enable refuses a --custom app. Running enable again on an app that already has Reverb is safe and useful: it does not reallocate the port or touch the credentials, it re-derives the public host and scheme and fills in any .env key that went missing.

Enabling it end to end

# 1. In the project, on your machine — require the package and the client side,
#    then commit. `install:broadcasting` writes resources/js/echo.js and config/reverb.php.
$ composer require laravel/reverb
$ php artisan install:broadcasting

# 2. On the server — allocate the port, the Supervisor program and the nginx proxy.
$ cipi app reverb enable myapp

# 3. A certificate, so clients get wss:// instead of ws:// (skip if the app already has one).
$ cipi ssl install myapp

# 4. Deploy: composer install, the Node build, then Reverb starts on the new release.
$ cipi deploy myapp
$ cipi app reverb status myapp

Order matters only in that the Node build has to run after reverb enable: Vite bakes VITE_REVERB_* into the bundle at build time. Cipi's node_build step runs after Deployer has linked the shared .env, so a deploy that follows enable produces a frontend that can find the socket. Change the domain or install a certificate later and you need another deploy for the bundle to catch up.

What Cipi writes in .env

# Laravel Reverb — managed by Cipi (cipi app reverb status myapp)
# Where the Supervisor program listens. Cipi owns this pair outright.
REVERB_SERVER_HOST=127.0.0.1
REVERB_SERVER_PORT=9000

BROADCAST_CONNECTION=reverb

# Generated once on the first enable, then never touched again.
REVERB_APP_ID=482913
REVERB_APP_KEY=3f9c1ab27de40518b6c4
REVERB_APP_SECRET=a71f0e5c8d24b93a6f10c7e5482db9af

# The public side — derived from what nginx actually serves.
REVERB_HOST=myapp.com
REVERB_PORT=443
REVERB_SCHEME=https

# Read by Vite at build time and baked into the frontend bundle.
VITE_REVERB_APP_KEY="${REVERB_APP_KEY}"
VITE_REVERB_HOST="${REVERB_HOST}"
VITE_REVERB_PORT="${REVERB_PORT}"
VITE_REVERB_SCHEME="${REVERB_SCHEME}"

Before 5.1.2 the three credentials were left blank for you to invent — and an empty REVERB_APP_KEY is exactly what stops reverb:start from booting. They are now generated on the first enable and an existing non-empty value always wins, so an app that arrived with its own credentials keeps them. Cipi never rotates them: a new key would disconnect every live client and invalidate any frontend bundle already built against the old one.

Connecting from the frontend

The stock resources/js/echo.js from install:broadcasting already reads exactly the variables Cipi writes — nothing to change:

import Echo from 'laravel-echo';
import Pusher from 'pusher-js';

window.Pusher = Pusher;

window.Echo = new Echo({
    broadcaster: 'reverb',
    key: import.meta.env.VITE_REVERB_APP_KEY,
    wsHost: import.meta.env.VITE_REVERB_HOST,
    wsPort: import.meta.env.VITE_REVERB_PORT ?? 80,
    wssPort: import.meta.env.VITE_REVERB_PORT ?? 443,
    forceTLS: (import.meta.env.VITE_REVERB_SCHEME ?? 'https') === 'https',
    enabledTransports: ['ws', 'wss'],
});

Because nginx fronts Reverb on the app's own domain and port, there is no extra port to open in the firewall and no second certificate to manage. cipi app reverb status prints the exact URL a client ends up dialling.

ws:// or wss://

Cipi derives the public host, port and scheme from what the server actually serves rather than assuming HTTPS:

Installing a certificate later — HTTP-01 or DNS-01 — moves the app's Reverb settings to wss:// on the spot, and a domain change re-derives them too. Before 5.1.2 these values were hardcoded to https/443 at enable time, which on an app without a certificate meant a browser silently refusing the connection as mixed content, with nothing in the Reverb log to explain it. reverb status now warns when the app has a certificate but the .env still says ws://.

Concurrent connections and open files

Every open WebSocket costs one file descriptor inside Reverb and two connections inside nginx, and the stock soft limit of 1024 stops an app at roughly a thousand concurrent clients — with nothing in any log to say why. Since 5.1.2 Cipi raises both ceilings:

nginx picks its new limits up on the reload Cipi performs. Supervisor picks its own up only on a restart, which also restarts every queue worker on the server — so Cipi configures the drop-in, tells you it is pending, and leaves the decision to you:

$ systemctl restart supervisor
# or, in one go, at enable time:
$ cipi app reverb enable myapp --restart-supervisor

The proxy read timeout was another silent limit: it used to be exactly Reverb's 60-second ping interval, so every idle client was a coin flip between the ping and the timeout. It now sits well clear of it, and Reverb's own ping/prune cycle is what reaps dead connections.

cipi app reverb status

Reports the port, what Supervisor is doing with the process, the URL a client should be dialling, and the three failure modes that leave nothing in any log:

$ cipi app reverb status myapp
  Reverb: enabled 127.0.0.1:9000
myapp-reverb                     RUNNING   pid 21847, uptime 3 days, 4:12:07
  Clients dial: wss://myapp.com:443/app/3f9c1ab27de40518b6c4
  Open files: 65535 (supervisor)

The process log is /home/<app>/logs/reverb.log, and supervisorctl status myapp-reverb / restart myapp-reverb control the program directly.

Disabling

cipi app reverb disable stops and removes the Supervisor program, regenerates the vhost without the proxy block, re-applies SSL, and — since 5.1.2 — points BROADCAST_CONNECTION back at whatever the app was broadcasting through before Reverb took over, falling back to log. Previously it left BROADCAST_CONNECTION=reverb behind, so every broadcast failed against a server that was no longer running.

Only REVERB_SERVER_HOST and REVERB_SERVER_PORT are removed from the .env. The credentials stay: they are what a re-enable — or a frontend bundle already built against them — depends on.

Cloning and cipi.yml

cipi app clone used to copy the source's REVERB_* keys into the clone's .env — pointing a staging frontend at the production socket and handing it the production app secret — while never starting a Reverb for it. Since 5.1.2 a cloned Reverb app gets its own port, its own credentials and its own domain, the way it already got its own Octane.

Reverb can also be declared in the project file with workers.reverb: true|false, planned and applied by cipi yml apply like Horizon and the queue workers, and emitted by cipi yml generate. Declaring it on a --custom app is refused up front.

workers:
  horizon: false
  reverb: true             # adds a Reverb WebSocket server to this app

cipi app clone

Since v5.0, clone an existing Laravel app into a new staging (or review) app with its own domain. Sets cloned_from in apps.json; does not copy webhook or git IDs. If the source has Reverb, the clone gets its own port, credentials and public host (since v5.1.2) — it no longer inherits the production socket. See cipi app reverb. Since v5.2.2, a cloned Scout app gets its own Meilisearch key and SCOUT_PREFIX; the source's MEILISEARCH_* keys are excluded from the copied .env, because a clone that inherited them would reindex into production. See cipi search.

$ cipi app clone myapp --domain=staging.myapp.com
$ cipi app clone myapp --domain=staging.myapp.com --name=myapp-stg --branch=develop --with-db
$ cipi app clone myapp --domain=staging.myapp.com --no-db

cipi app limits

Since v5.0, set per-app resource limits with hard caps enforced by Cipi.

$ cipi app limits myapp --fpm-max-children=20 --memory-limit=256M
$ cipi app limits myapp --octane-workers=4 --worker-procs=3
$ cipi app limits myapp   # show current limits

app suspend / app unsuspend

Available since v4.5.8. Take an app offline without deleting it — useful for billing holds, maintenance windows, or staging sites you want fully dark. Suspending swaps the Nginx vhost for a static HTTP 503 page served from /var/www/cipi-suspended/.

$ cipi app suspend myapp      # take offline (503 page)
$ cipi app unsuspend myapp    # restore normal vhost

Behaviour

• HTTPS included — certbot clones the suspension vhost into the :443 block, so HTTPS also shows the offline page
• Let's Encrypt still works — the /.well-known/acme-challenge/ path stays public so certificates can be issued or renewed while suspended
• Survives vhost regeneration — alias changes, PHP edits, and SSL installs respect the suspended flag
• Visible in listings — cipi app list marks suspended apps; cipi domains appends ⏸ suspended on each row

Also available via the REST API (POST /api/apps/{name}/suspend), cipi-cli (apps suspend), and the WHMCS module (Suspend / Unsuspend buttons). Requires token ability apps-suspend for API access.

cipi basicauth

Available since v4.5.2. Protect any app — Laravel or custom — behind an Nginx username/password prompt. Useful for staging sites, internal tools, or apps that aren't ready for public traffic yet.

Credentials are hashed with openssl passwd -apr1 (no apache2-utils needed) and stored in /etc/nginx/cipi-basicauth/<app>.htpasswd; the enabled state lives in apps.json. The auth_basic directives are injected per location block, so protection survives vhost regeneration (alias changes, PHP edits) and is cloned into the :443 block by certbot — HTTPS is covered too. ACME challenges stay public, so certificate issuance and renewal are never blocked. Basic auth is removed automatically on cipi app delete.

Managing ENV variables

Every Laravel app has a single .env file living at /home/<app>/shared/.env. Custom apps have no .env. It is created and pre-populated by Cipi during app create with the database credentials, APP_KEY, APP_URL, cache/session/queue settings, and the webhook token. The shared/ directory is symlinked into every release, so the same .env is always active regardless of which release is current.

Edit interactively via CLI

The safest way to change ENV values is through Cipi itself — it opens the file in nano as the app user, with the correct permissions:

$ cipi app env myapp

Save with Ctrl+O then exit with Ctrl+X. Changes take effect immediately for new requests — no restart needed for most values. If you change queue connection or cache driver, restart the workers:

$ cipi worker restart myapp

Non-interactive flags (v5.0.3+)

Since v5.0.3, scripts, the panel API, and the web GUI can manage .env without opening an editor:

$ cipi app env myapp --show
$ cipi app env myapp --show --json
$ cipi app env myapp --get=APP_URL
$ cipi app env myapp --set=APP_DEBUG=false
$ cipi app env myapp --unset=LEGACY_KEY

REST: GET|PUT /api/apps/{name}/env (ability apps-env, API 1.14+). MCP: AppEnvShow, AppEnvUpdate.

Edit directly via SSH

You can also edit the file directly over SSH as root or as the app user:

# as root
$ nano /home/myapp/shared/.env

# or switch to the app user first
$ su - myapp
$ nano ~/shared/.env

Key ENV variables set by Cipi

Adding your own variables

Add any custom variable at the bottom of the file as you normally would in a Laravel project. They are preserved across deploys because the .env lives in shared/ and is never overwritten by Deployer.

# your custom variables
STRIPE_KEY=sk_live_...
STRIPE_SECRET=sk_live_...
MAIL_MAILER=smtp
MAIL_HOST=smtp.mailgun.org

cipi app run

Since v5.0.3, run a whitelisted non-interactive command as the app user — useful from the CLI, panel API, and web GUI “App commands”. Editors, pagers, shells, and REPLs are blocked (nano, vim, less, bash, tinker, …). Interactive flags (e.g. tail -f, php -a) are rejected.

$ cipi app run myapp composer install --no-dev
$ cipi app run myapp npm ci
$ cipi app run myapp ls -la shared
$ cipi app run --commands          # list allowed binaries
$ cipi app run --commands --json

Allowed binaries include composer, npm/npx/yarn/pnpm, ls/ll, cat/head/tail, filesystem helpers, archives, git, php, node, and find. REST: POST /api/apps/{name}/run (async job, ability apps-run) and GET /api/run-commands (API 1.14+). MCP: AppRun, AppRunCommands.

cipi app logs

Tail application logs in real-time. Logs are rotated daily and kept for 14 days. By default, all logs are shown including Laravel daily logs (laravel-YYYY-MM-DD.log) from shared/storage/logs/.

$ cipi app logs myapp                  # all logs (incl. Laravel daily logs)
$ cipi app logs myapp --type=nginx     # Nginx access + error
$ cipi app logs myapp --type=php       # PHP-FPM errors
$ cipi app logs myapp --type=worker    # queue worker output
$ cipi app logs myapp --type=deploy    # deploy history
$ cipi app logs myapp --type=laravel   # Laravel application logs

app artisan & app tinker

Run Artisan commands and Tinker as the app user with the correct PHP version and open_basedir context — exactly as they would run during a deploy.

$ cipi app artisan myapp migrate:status
$ cipi app artisan myapp queue:retry all
$ cipi app artisan myapp db:seed --class=ProductionSeeder
$ cipi app artisan myapp cache:clear
$ cipi app tinker myapp

SSH as the app user

Each app runs under its own isolated Linux user. Sometimes you need to work directly inside that user's environment — inspect files, run one-off scripts, or debug something that only reproduces as the correct user.

Direct SSH as app user (recommended)

App users can SSH directly to the server with the password generated at app creation:

# connect as the app user (password auth)
$ ssh myapp@your-server-ip

# you are directly inside the app user's shell
myapp@server:~$ pwd
/home/myapp

myapp@server:~$ cd ~/current
myapp@server:~$ ls

The password is shown when the app is created (or use cipi app reset-password myapp to regenerate it). This works for SFTP clients, IDE remote sessions, and terminal access.

Via cipi (admin path)

If you are already connected as cipi, you can switch directly to any app user:

$ ssh cipi@your-server-ip
cipi@server:~$ sudo su - myapp

myapp@server:~$ pwd
/home/myapp

Reset the app user password

If you need to regenerate an app user's password (e.g. for direct SSH or SFTP), use:

$ cipi app reset-password myapp

The new password is displayed on screen — save it immediately.

Useful commands once logged in as the app user

# navigate to the active release
myapp@server:~$ cd ~/current

# run artisan directly with the correct PHP version
myapp@server:~$ /usr/bin/php8.5 ~/current/artisan tinker

# inspect the shared .env
myapp@server:~$ cat ~/shared/.env

# tail all logs
myapp@server:~$ tail -f ~/logs/*.log

# check active releases (ll is a built-in alias for ls -al)
myapp@server:~$ ll ~/releases/

Every app user's .bashrc defines a handy ll='ls -al' alias (since v4.5.5) for quicker directory listings over SSH, alongside the deploy and composer shortcuts. Apps created before 4.5.5 receive the ll alias automatically on the next cipi self-update via the 4.5.5 migration.