Control Panel (GUI)

The optional web control panel

Cipi is, and always will be, CLI-first. Everything a server needs — apps, databases, SSL, deploys, backups, firewall — is a single cipi command away over SSH. But from v4.7.0 Cipi also ships an optional web control panel: a self-hosted Laravel dashboard that manages one or more Cipi servers from the browser, over the same REST API the CLI client and WHMCS module use.

The panel is a thin visual layer on top of the API — it does not replace the CLI or add a proprietary control plane. Anything you do in the browser, you can still do from the terminal, and vice versa. A single panel can drive many servers, so it doubles as a lightweight multi-server cockpit.

What you can do from the panel

• Manage apps — create, edit, suspend/unsuspend, and delete Laravel and custom apps.
• Issue and renew SSL certificates.
• Browse application and server logs.
• Run database operations.
• Register and switch between multiple servers from one login.

Control Panel (GUI)

Requirements

The panel talks to your servers exclusively through the Cipi REST API. Before installing it, make sure each server you want to manage has the API enabled with a token that covers the full ability set.

• A running Cipi server (Ubuntu 24.04 / 26.04) to host the panel — this can be one of the servers you manage or a small dedicated box.
• A domain (or subdomain) pointed at that server, e.g. panel.example.com.
• cipi api enabled on every server you want to control, each with a full-ability token.

PHP, the FPM pool, the Nginx vhost and the scheduler are all provisioned for you by the installer — you do not set up a Laravel environment by hand.

Control Panel (GUI)

Installation — cipi gui <domain>

One command provisions the whole panel on a Cipi server: a dedicated PHP-FPM pool, an Nginx vhost for your domain, and a scheduler cron job. The Laravel app is bundled at /opt/cipi/gui, the same model used by the cipi-api package.

cipi gui panel.example.com

The installer prompts interactively for the first administrator account — an email and a password. The password must satisfy the panel's policy:

• Minimum 12 characters.
• At least one uppercase, one lowercase, one digit, and one special character.
• No more than 4 identical consecutive characters.

Configuration is written to /etc/cipi/gui.json. Once the command finishes, open your domain in a browser and log in with the admin account you just created.

Control Panel (GUI)

SSL — cipi gui ssl

Issue a free Let's Encrypt certificate for the panel's domain and switch it to HTTPS. The panel is HTTPS-aware and sets the correct forwarded headers behind the Cipi Nginx vhost.

cipi gui ssl

The certificate renews automatically through the same ACME renewal that Cipi uses for app domains.

Control Panel (GUI)

Two-factor authentication (TOTP)

The panel uses classic session login and supports optional TOTP two-factor authentication. Each administrator can enrol an authenticator app (Google Authenticator, 1Password, Aegis, …) from their profile. 2FA is opt-in per user, not forced.

If an administrator loses access to their second factor, an operator with shell access can clear it from the server with cipi gui reset-user, which rewrites the account and removes the 2FA enrolment.

Control Panel (GUI)

Updating — gui update vs gui upgrade

The panel ships as the cipi/gui Composer package, so updates are ordinary Composer updates plus migrations. Two commands cover the common cases:

cipi gui update — soft update

Runs composer update cipi/gui, applies database migrations, and refreshes the compiled theme. This is the day-to-day update path.

cipi gui update

cipi gui upgrade — full rebuild

Rebuilds the panel from scratch. Use it after a major release, or if an environment has drifted and a clean reinstall of the app code is the fastest way back to a known-good state.

cipi gui upgrade

cipi gui refresh-theme — theme only

Recompiles and reloads the panel theme without touching code or the database — handy after a theme tweak.

cipi gui refresh-theme

Control Panel (GUI)

Operations

cipi gui status

Report the panel's current status — whether it is installed, its domain, and the health of its services.

cipi gui status

cipi gui fix-permissions

Repair the panel's PHP-FPM open_basedir restriction and all runtime file permissions. Run it if the panel starts throwing permission or autoload errors after an update.

cipi gui fix-permissions

cipi gui reset-user

Rewrite an administrator's email, name and password, and clear their 2FA enrolment — the recovery path when someone is locked out. reset-password is an alias for the same command.

cipi gui reset-user

Control Panel (GUI)

Removing the panel — cipi gui remove

Uninstall the panel and its Nginx vhost, PHP-FPM pool and scheduler. Your servers and apps are untouched — the panel is just a client of the API. uninstall is an alias, and --force skips the confirmation prompt.

cipi gui remove
cipi gui remove --force

Removing the panel is the ultimate expression of its optionality: uninstall it any time and Cipi is back to a pure CLI, exactly as it was before.

Control Panel (GUI)

Architecture

The panel is a standard Laravel 12 application distributed as the cipi/gui package from its own repository (cipi-sh/gui) and installed via a Composer VCS entry tracking dev-main. It lives at /opt/cipi/gui, mirroring how the cipi-api package is bundled.

Because it holds no local queue worker and stores no server state of its own, the panel stays stateless with respect to your infrastructure: it authenticates to each server's API, submits jobs, and polls their status. Tear the panel down and rebuild it elsewhere without touching a single managed server.