Cipi Agent
Installing the Cipi Agent
Cipi Agent (cipi/agent on Packagist) is the official Laravel companion for
Cipi. It bridges your application and the server control panel with:
- Webhook-triggered deploys from GitHub, GitLab, Bitbucket, Gitea and Azure DevOps, recorded in the deploy audit ledger
- Health monitoring (app, database, cache, queue with failed jobs, storage, live release and commit)
- An in-app MCP server for AI assistants (Cursor, VS Code, Claude Code, Claude Desktop, any MCP client) — 11 tools plus optional panel tools
cipi.ymltooling — validate, inspect and generate the declarative server configuration with the server's own rules- A GDPR-oriented database anonymizer for MySQL/MariaDB and PostgreSQL
- An optional bridge to the panel API through
cipi/sdk(rollback, audit ledger, database backups)
On a Cipi-managed server, cipi app create injects the required .env
variables automatically. Health check, MCP, cipi.yml validation and the anonymizer work
on any Laravel host; automated deploys, infrastructure logs and release information expect a
Cipi-managed environment.
deploy_status, db_schema, env_check,
cipi_yml, anonymizer), resources, secret redaction,
php artisan cipi:yml, a PostgreSQL anonymizer that actually works, consistent and
unique fake values, --scan and an audit for the anonymization config, more Git
providers, audit-ledger claims on every deploy, and the panel_* tools via
cipi/sdk. Wire-compatible with 1.x — see Upgrading from
1.x.Requirements
| Requirement | Version |
|---|---|
| PHP | 8.3+ |
| Laravel | 12 or 13 |
| Database (anonymizer) | MySQL / MariaDB or PostgreSQL |
| CLI tools (anonymizer) | mysqldump (or mariadb-dump) / pg_dump on the server |
| Optional | cipi/sdk ^1.0 for the panel tools, ext-zlib for gzip dumps |
composer require cipi/agent
The service provider auto-discovers — no config/app.php change is needed. After install,
commit and push; Cipi deploys the update on the next release.
Optional — publish the config file (non-Cipi or custom defaults):
php artisan vendor:publish --tag=cipi-agent-config # cipi-config still works; cipi/sdk shares that tag php artisan cipi:status # verify config, release, features and DB connectivity
/cipi/* on the app domain). The server-level
cipi/api package runs on a separate API vhost and
manages the whole server — see Agent vs Cipi API.Artisan commands
| Command | Description |
|---|---|
| php artisan cipi:status | Agent configuration, the app's environment (CIPI_ENV, agent 2.1.0 / Cipi 5.8.0+), live release and commit, feature state, cipi.yml validity, database connectivity |
| php artisan cipi:deploy-key | Print the SSH deploy key for this app |
| php artisan cipi:mcp [--json] | MCP endpoint, tools, resources and setup snippets for Cursor, VS Code, Claude Code and Claude Desktop |
| php artisan cipi:generate-token {type} | Generate a secure token and write it to .env. Type: mcp, health or anonymize |
| php artisan cipi:service {type} --enable|--disable | Toggle a service in .env (the configuration cache is rebuilt when one exists). Type: mcp, health or anonymize |
| php artisan cipi:yml validate|show|generate|example|schema | Validate, inspect or generate cipi.yml with the server's rules (2.0) |
| php artisan cipi:init-anonymize [--scan] | Create /home/{app_user}/.db/anonymization.json from the example, or propose it from the live database schema (2.0) |
| php artisan cipi:anonymize-audit [config] | Check the anonymization config against the database: missing tables/columns, unknown transformations, uncovered personal data (2.0) |
| php artisan cipi:anonymize [config] [output] [--gzip] [--check] | Run an anonymized database dump directly on the server (no HTTP) |
Upgrading from 1.x
composer require cipi/agent:^2.0. Existing MCP clients, webhooks, health monitors and
the anonymizer API keep working unchanged. Behaviour that did change:
passwordtransformation now sets every row to the hash ofoptions.password(defaultpassword), computed once, instead of re-hashing the stored hash — the anonymized copy is finally usable for login. Setoptions.passwordif you relied on a specific value.- Health no longer reports
degradedwhen deploy metadata is missing or the last automatic deploy failed (the previous release is still live); the information is inchecks.deploy. - Deploy trigger file gained
source,actor,ip,refandrequest_idfor the audit ledger; the 1.x keys are still written. db_queryadditionally blocksALTER,RENAME,CREATE …, administrative statements and multi-statement input;CIPI_MCP_DB_WRITE=falsemakes it read-only.artisanadditionally blocksdb:wipe,migrate:fresh,migrate:reset,pailandhorizon:*.- PostgreSQL dumps switch from
customtoplainformat so that they can actually be transformed. - Publishing —
--tag=cipi-agent-configpublishes only this package's config;cipi-configis shared withcipi/sdkand still works.
Webhook — Automatic Deploys
The agent exposes a POST endpoint at /cipi/webhook. When your Git provider sends a push
event, the agent verifies the signature and writes a .deploy-trigger file. The app
user's crontab (installed by Cipi) picks it up within a minute, moves it aside and runs
cipi-app-deploy, which wraps Deployer: clone, composer install, migrations,
symlink swap, worker restart, cipi.yml reconciliation, post-deploy steps and the
post-deploy healthcheck. A GitHub ping answers pong; events that are not a
push (pull requests, tags on Bitbucket, …) are acknowledged with 202 ignored.
This design means the webhook response is instant (no HTTP timeout waiting for deployment to
complete) and Deployer runs with the correct user permissions — no sudo required.
Configure your Git provider
| Provider | Webhook URL | Authentication | Push event |
|---|---|---|---|
| GitHub | https://yourdomain.com/cipi/webhook | X-Hub-Signature-256 HMAC-SHA256 — use CIPI_WEBHOOK_TOKEN as Secret |
push (ping → pong) |
| GitLab | https://yourdomain.com/cipi/webhook | X-Gitlab-Token header — same token value |
Push Hook |
| Bitbucket Cloud | https://yourdomain.com/cipi/webhook | X-Hub-Signature sha256= HMAC with the token as secret |
repo:push |
| Gitea / Forgejo | https://yourdomain.com/cipi/webhook | X-Gitea-Signature HMAC-SHA256 |
push |
| Azure DevOps | https://yourdomain.com/cipi/webhook | X-Gitlab-Token header (Cipi registers the service hook that way) |
git.push |
On Cipi-managed servers cipi app create / cipi git register the webhook
for you. Custom setups can also send ?token= or a Bearer token.
The token to use is stored in .env as CIPI_WEBHOOK_TOKEN. You can also
retrieve it any time with:
cipi deploy myapp --webhook
Branch filtering
Only a push to the branch named in .env deploys:
CIPI_DEPLOY_BRANCH=main
Pushes to any other branch receive a skipped response and no deploy is triggered (since
2.1.0 the webhook answer also names the app's environment). Without
the key, every push deploys. Since Cipi 5.7.2 the key is written at
cipi app create with the app's deploy branch and kept in step by
cipi app edit --branch and cipi sync import; migration 5.7.2 adds it to
existing Laravel apps that lack it and leaves a value already there alone. Since 5.8.0
a deploy.branch applied from
cipi.yml rewrites it too, and the app's environment label sits next to it as
CIPI_ENV.
What the audit ledger records
Since 2.0 the trigger file carries what the payload said about the push — provider, actor
(pusher), commit, delivery id and the client IP — in the format cipi-app-deploy reads:
{"source":"github","actor":"octocat","ip":"140.82.115.3","ref":"main@abcdef123456","request_id":"8d2f…"}
Cipi stores these under claimed in the root-owned, hash-chained
deploy audit ledger (cipi deploy <app> --audit),
next to the facts root establishes on its own (release, commit, process chain). The MCP
deploy tool writes the same file with source: mcp and the actor the
assistant was given, so every deploy says who asked for it.
Health Check
The agent also exposes a GET endpoint at /cipi/health that returns a JSON payload with
the status of the app (debug, maintenance mode), database, cache, queue (pending and failed
jobs), writable storage with disk usage, and the deploy state: live release, commit, whether a deploy
is queued or running and how the last automatic deploy ended. Useful for external monitoring
services such as UptimeRobot. Protected by the CIPI_HEALTH_TOKEN Bearer token —
generate one with php artisan cipi:generate-token health. Since 2.1.0
environment is the app's environment label (CIPI_ENV, the one
cipi app create --env sets on Cipi 5.8.0+).
curl -H "Authorization: Bearer YOUR_CIPI_HEALTH_TOKEN" \
https://yourdomain.com/cipi/health
{
"status": "healthy",
"app_user": "myapp",
"php": "8.5",
"laravel": "13.35.0",
"environment": "production",
"checks": {
"app": { "ok": true, "version": "2.1.0", "debug": false, "maintenance": false },
"database": { "ok": true, "driver": "mysql", "database": "myapp" },
"cache": { "ok": true, "driver": "database" },
"queue": { "ok": true, "connection": "database", "pending_jobs": 0, "failed_jobs": 0 },
"storage": { "ok": true, "disk_free_gb": 31.2, "disk_used_percent": 41 },
"deploy": {
"ok": true,
"release": "20261009103000",
"commit": "0123456789abcdef0123456789abcdef01234567",
"short_commit": "0123456",
"commit_source": "REVISION",
"in_progress": false,
"pending": false,
"last_deploy": { "status": "ok", "trigger": "webhook", "branch": "main", "duration_seconds": 42 }
}
},
"timestamp": "2026-10-09T10:00:00+00:00"
}
status is degraded (HTTP 503) when the database, cache, queue or storage check
fails. Deploy metadata is informational: a failed last deploy is reported under
checks.deploy.attention without degrading the status — the previous release is still
serving — and the MCP health / deploy_status tools expose the same fields.
The deployed commit is resolved from the first available source:
- Deployer's
REVISIONfile in the live release (/home/{app_user}/current/REVISION) /home/{app_user}/.cipi/deploy.jsonor.cipi/last_commit.git/HEADorgit rev-parse HEAD(apps not deployed by Cipi)
last_deploy comes from the banners cipi-app-deploy writes to
/home/{app_user}/logs/deploy.log (trigger, branch, release, duration, exit code).
Authentication
The Bearer token is resolved in order: CIPI_HEALTH_TOKEN (dedicated), then
CIPI_WEBHOOK_TOKEN (fallback). Disable the endpoint entirely with
php artisan cipi:service health --disable or CIPI_HEALTH_CHECK=false.
Monitoring integrations
The health endpoint works with any HTTP checker that supports Bearer tokens — e.g.
UptimeRobot, Better Stack, Grafana, or custom
cron + curl. Poll checks.queue.pending_jobs for queue backlog alerts,
checks.queue.failed_jobs for stuck jobs and checks.storage.disk_used_percent
next to Cipi's own soft disk limits.
MCP Server
cipi-agent includes a built-in MCP server (Model Context Protocol)
that exposes your application to AI assistants such as Cursor,
VS Code (with GitHub Copilot), Claude Code and Claude
Desktop — or any MCP client. The endpoint speaks Streamable HTTP with JSON-RPC 2.0 and is
protected by the CIPI_MCP_TOKEN Bearer token.
Since 2.0 it speaks every current MCP revision: the handshake-based revisions
2024-11-05, 2025-03-26, 2025-06-18 and 2025-11-25
(initialize, what today's clients use) and the stateless revision
2026-07-28 (server/discover, per-request _meta,
resultType, Mcp-Method / Mcp-Name header validation). Every tool
declares a title, behaviour annotations (readOnlyHint, destructiveHint, …)
and a JSON Schema, returns text and structuredContent, and reports failures with
isError. GET and DELETE answer 405 (no SSE stream, no
sessions), notifications get 202, and the Origin header is validated against
the app host.
The MCP endpoint is available at POST /cipi/mcp and is disabled by default. To enable
it:
php artisan cipi:service mcp --enable
php artisan cipi:generate-token mcp
php artisan cipi:mcp # endpoint, tools, resources and client snippets
Available tools
The server exposes eleven tools scoped to this application, plus five
panel tools when cipi/sdk is configured. Tools are listed
in a fixed order so clients can cache the list:
| Tool | Mode | What it does |
|---|---|---|
health |
read-only | Same report as GET /cipi/health: app, database, cache, queue (pending and failed jobs), storage, deploy state |
app_info |
read-only | Versions, drivers, Cipi endpoints, enabled features, the app's environment (CIPI_ENV, agent 2.1.0 / Cipi 5.8.0+), live release and commit, whether a cipi.yml exists — never secrets |
deploy |
action | Queue a zero-downtime deploy; records actor, ref and request_id as audit-ledger claims; refuses while a deploy is running |
deploy_status |
read-only | Live release and commit, the releases kept for rollback, queued/running state, outcome of the last automatic deploy, optional tail of the deploy log; the app's environment since 2.1.0 |
logs |
read-only | laravel, nginx, php, worker, horizon, reverb, deploy or all; severity and keyword filters; stack traces intact; secrets redacted |
artisan |
can change data | Run an Artisan command (--no-interaction is added); interactive, long-running and data-destroying commands are blocked |
db_query |
configurable | SELECT / WITH / SHOW / DESCRIBE / EXPLAIN as table or JSON, auto-capped; INSERT / UPDATE / DELETE unless CIPI_MCP_DB_WRITE=false |
db_schema |
read-only | Tables with row counts, or one table's columns, indexes, foreign keys and the columns that look like personal data |
env_check |
read-only | Which .env keys are set or empty, compared with .env.example and the env.required of cipi.yml — names only, never values |
cipi_yml |
read-only | validate, show, generate or example for cipi.yml; validates a draft passed as content before you commit it |
anonymizer |
action | audit, config, scan, transformations, or start an anonymized dump (e-mail required) |
panel_* |
see below | Rollback, deploy audit ledger, database backup, job status, app and server status — through the panel API |
logs tool parameters
| Parameter | Values | Description |
|---|---|---|
type |
laravel, nginx, php, worker, horizon, reverb, deploy, all |
Log file(s) to read — the same types as cipi app logs, plus Horizon and Reverb |
lines |
1–500 (default 50) | Lines per file before filtering |
level |
debug … emergency |
Minimum severity — Laravel entries only (error = error, critical, alert, emergency) |
search |
any string | Case-insensitive keyword filter; multi-line entries stay intact |
Resources
Files the assistant benefits from reading whole, exposed as MCP resources:
cipi://cipi.yml (the committed file), cipi://cipi.yml/schema (JSON Schema),
cipi://cipi.yml/example (the commented template in the app's namespace),
cipi://anonymization.json and cipi://anonymization.json/schema.
Blocked operations (MCP safety)
- Artisan:
serve,tinker,pail,queue:work,queue:listen,schedule:work,horizon,horizon:work,horizon:supervisor,octane:start,reverb:start,db,db:wipe,migrate:fresh,migrate:reset— extend the list withcipi.mcp_blocked_artisanin the published config - SQL: DDL (
DROP,ALTER,TRUNCATE,CREATE …,RENAME),GRANT/REVOKE, file I/O,SET GLOBAL,KILL/SHUTDOWN, PostgreSQL file functions and multi-statement input; reads withoutLIMITare capped atCIPI_MCP_MAX_ROWS(default 100, max 500);CIPI_MCP_DB_WRITE=falsemakes the tool read-only - Redaction: logs and command output are prefixed with a production-content
warning and common secrets (env assignments, bearer tokens, DSNs,
APP_KEY, provider keys, Cipi tokens) are masked — the same guard as the panel API MCP (CIPI_MCP_REDACT) - Origin: a browser
Originthat is not the app host is refused with403(DNS-rebinding guard); extend withCIPI_MCP_ALLOWED_ORIGINS
Setup instructions
Run the cipi:mcp Artisan command to get the endpoint URL and ready-to-paste
configuration snippets for your AI client (--json prints just the Cursor/VS Code
configuration):
php artisan cipi:mcp
Cursor
Add the following to ~/.cursor/mcp.json (or go to Cursor → Settings → MCP):
{
"mcpServers": {
"cipi-myapp": {
"type": "http",
"url": "https://yourdomain.com/cipi/mcp",
"headers": {
"Authorization": "Bearer YOUR_CIPI_MCP_TOKEN"
}
}
}
}
Replace cipi-myapp with your app user name, yourdomain.com with your
actual domain, and YOUR_CIPI_MCP_TOKEN with the token from your
.env. Cursor connects natively over HTTP — no bridge needed.
VS Code
VS Code (with GitHub Copilot) supports MCP natively since version 1.102. Add the following to
.vscode/mcp.json in your project (or run MCP: Open User Configuration
for a global setup). The token is asked once and stored by VS Code — nothing to commit:
{
"inputs": [
{ "type": "promptString", "id": "cipi-token", "description": "Cipi MCP token for myapp", "password": true }
],
"servers": {
"cipi-myapp": {
"type": "http",
"url": "https://yourdomain.com/cipi/mcp",
"headers": {
"Authorization": "Bearer ${input:cipi-token}"
}
}
}
}
Claude Code
claude mcp add --transport http cipi-myapp https://yourdomain.com/cipi/mcp \
--header "Authorization: Bearer YOUR_CIPI_MCP_TOKEN"
Claude Desktop
Claude Desktop requires the mcp-remote bridge to convert stdio to HTTP. Add the
following to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"cipi-myapp": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://yourdomain.com/cipi/mcp",
"--header",
"Authorization: Bearer YOUR_CIPI_MCP_TOKEN"
]
}
}
}
Install mcp-remote globally once with:
npm install -g mcp-remote
What you can do with it
Once connected, your AI assistant can interact with the Cipi-managed application in natural language. For example:
User: Is production healthy, and what commit is live? Claude: Calling health and deploy_status... Status: healthy — database, cache, queue (0 pending, 0 failed) and storage OK. Live release 20261009103000, commit 0123456 (webhook deploy, 42 s, OK). User: Show me the last errors and tell me which job is failing. Claude: Calling logs (type: laravel, level: error, lines: 200)... 3 entries: InvoiceJob — SQLSTATE[42S22]: column invoices.paid_at not found. Calling artisan (migrate:status)... 2026_10_08_add_paid_at is pending. User: Which columns of the users table look like personal data? Claude: Calling db_schema (table: users)... email → fakeEmail, phone → fakePhoneNumber, remember_token → null, password → password. User: Validate this cipi.yml draft, then queue a deploy and record that Jane asked. Claude: Calling cipi_yml (validate, content: …)... valid, 0 warnings. Calling deploy (actor: jane@example.com)... queued — Deployer runs within 1 minute.
Panel tools via cipi/sdk
The agent only knows the app it runs in. With the PHP SDK installed and a Sanctum token created on the server with the abilities you want to allow, the same MCP server gains tools that no in-app process could offer — rolling a release back, reading the deploy audit ledger, taking a server-side database backup:
composer require cipi/sdk # on the server, once: cipi api token create # abilities: apps-view, deploy-manage, dbs-manage, status-view
CIPI_BASE_URL=https://api.myserver.com
CIPI_TOKEN=your-sanctum-token
# CIPI_PANEL_APP=myapp # app name on the panel, default: CIPI_APP_USER
| Tool | Panel operation | Token ability |
|---|---|---|
panel_status |
The app as the panel sees it (domain, PHP, repository, branch, workers, aliases, limits) plus the server snapshot | apps-view, status-view |
panel_deploy_audit |
The hash-chained deploy audit ledger (cipi deploy --audit) |
deploy-manage |
panel_rollback |
cipi deploy --rollback — code symlink only, migrations stay; wait=true blocks until the job ends |
deploy-manage |
panel_db_backup |
cipi db backup server-side snapshot, e.g. right before a risky data fix |
dbs-manage |
panel_job |
Status, structured result and CLI output of an asynchronous panel job | any |
The tools appear automatically when the SDK is installed and CIPI_BASE_URL /
CIPI_TOKEN are set (CIPI_PANEL=false hides them). Both packages read
config/cipi.php; publish the agent's copy with --tag=cipi-agent-config.
Scope the panel token to exactly these abilities — it is the one credential that reaches beyond
this app.
CIPI_MCP_TOKEN secret. Anyone with the token can trigger deploys,
read logs, run database queries, and run Artisan commands through the MCP endpoint. If you
suspect a leak, regenerate the token with php artisan cipi:generate-token mcp —
the configuration cache is rebuilt for you; Octane and workers need a restart.
POST /cipi/mcp on
the app domain, 11 tools + 5 panel tools, one app's DB, logs, Artisan and cipi.yml)
vs panel API MCP (POST /mcp on the API domain, 73 tools in
cipi/api 1.31, whole server). Use Agent MCP for app-specific debugging; use
panel API MCP to create apps, manage SSL, or list all
databases.cipi.yml tooling
cipi.yml is the declarative file committed with the app that
drives its server configuration: PHP version, aliases, php.ini overrides, limits, basic auth, extra
databases, workers (queues, Horizon, Reverb), scheduler, healthcheck, deploy recipe (the deploy
branch too, since Cipi 5.8.0) and post-deploy steps, redirects, proxies, SSL, required
.env names, crons and backup profiles. On the server,
cipi yml validate | plan | apply reconcile it —
reading, since Cipi 5.8.0, a
cipi-<env>.yml for the app's environment
before cipi.yml, so one repository can carry a staging and a production file. Since
agent 2.1.0 the package's own locator does the same — cipi:yml validate
and show pick cipi-<env>.yml first — and its validator knows
deploy.branch.
Since 2.0 the agent ships the same parser and validator — a line-for-line port of the server's YAML-subset parser and schema checks, verified against the server's Python on a corpus of valid and invalid files — so you get the server's verdict, and the server's exact error messages, locally and in CI before anything is committed.
php artisan cipi:yml validate # ./cipi.yml, then the server locations; exit 1 on errors php artisan cipi:yml validate --json # machine-readable, for CI php artisan cipi:yml validate --strict # warnings (env.required missing in .env) also fail php artisan cipi:yml show # the normalized document, server defaults applied php artisan cipi:yml generate --write # a cipi.yml inferred from this Laravel app php artisan cipi:yml example --write # the commented template, in the app's namespace php artisan cipi:yml schema --write # JSON Schema for editor autocompletion
Generate from the application
cipi yml generate <app> on the server prints what is configured today.
php artisan cipi:yml generate is the other direction — a starting point derived from
the code for an app that has never run on Cipi: Horizon or plain queue workers
(QUEUE_CONNECTION), Reverb, Scout with Meilisearch, scheduled tasks, the /up
health route, CIPI_PHP_VERSION, extra databases in the app's namespace and the
credential-looking keys of .env.example for env.required. Everything else is
left as commented examples. The output is run through the validator before it is returned, so it is
never a file the server would reject.
Validate before the server does
Unknown keys, values outside their bounds, databases or backup profiles outside the app's namespace,
forbidden runners in deploy.post — every rule the server applies is applied here, with
the same path: message output. The validator also reads the local .env and
warns about each env.required name that is missing or empty, because the server blocks
the plan while one is. Namespace rules need the app name: CIPI_APP_USER, or
--app=<name> outside the server.
php artisan cipi:yml validate INFO cipi.yml is valid (/var/www/shop/cipi.yml) WARN env.required: STRIPE_KEY is not set in .env — the server blocks the plan while it is missing See what applying it would change on the server: cipi yml plan shop
Editor support
cipi:yml schema --write publishes cipi.schema.json (JSON Schema 2020-12,
also available with vendor:publish --tag=cipi-schemas). Point the YAML language server
at it with a first-line comment and get completion and inline errors while you type:
# yaml-language-server: $schema=./cipi.schema.json
version: 1
From the assistant
The MCP cipi_yml tool runs the same actions (validate, show,
generate, example) and accepts a draft as content, so an AI
assistant can propose a change, validate it and hand you a file the server accepts — without
writing to the repository itself. The env_check tool reports which
env.required names are missing on the server, with no values.
cipi.yml key — deploy.branch in 5.8.0, known to the agent since 2.1.0 — update
cipi/agent as well so php artisan cipi:yml validate knows it; until
then the server remains authoritative.Database Anonymizer
cipi-agent includes a built-in database anonymizer that creates sanitized copies of
your production database — ideal for sharing with developers, QA teams, or staging environments
without exposing real user data. It supports MySQL / MariaDB and
PostgreSQL (since 2.0 the pg_dump output is streamed through its
COPY blocks and INSERT statements), uses Faker-based
transformations configured via a JSON file, and runs as a background job so large databases do not
block HTTP requests. The real data never lingers: the original dump is deleted as soon as it has
been processed, outputs are 0600, and database passwords travel in the environment,
never on the command line.
This feature lives inside your Laravel application (the cipi/agent
package). It is separate from the server-level database backup API exposed by
cipi api — see
Agent vs Cipi API below.
cipi-cli db anonymize (cipi-cli
1.5.0+) drives this whole flow from your laptop through the Cipi API — no SSH,
no token to paste. See From your laptop with cipi-cli
below.Use cases
- Local development — give every developer a realistic dataset without copying production emails, addresses, or payment notes
- Staging / preview environments — refresh a non-production database from production structure and volume, with PII replaced
- QA and demos — reproduce bugs that depend on relational data without GDPR risk
- Vendor or contractor access — share a SQL dump when a full VPN + production access is not acceptable
- Developer laptops —
cipi-cli db anonymize myapp --email you@example.comrequests a dump through the Cipi API, with no SSH session and no token to copy around (see From your laptop with cipi-cli) - CI pipelines — run
cipi:anonymizeon the server or triggerPOST /cipi/dbfrom a secure automation step
Prerequisites
| Requirement | Why |
|---|---|
composer require cipi/agent |
The anonymizer is part of the agent package, not the Cipi server CLI |
| Queue worker running | POST /cipi/db dispatches AnonymizeDatabaseJob — without a
worker the job never runs. As root: cipi worker list myapp; as the app user:
sudo cipi-worker status myapp
|
mysqldump (or mariadb-dump) / pg_dump |
The native dump tool for your DB driver, found on PATH or set with
CIPI_MYSQLDUMP / CIPI_PG_DUMP; ext-zlib for
gzip output |
Laravel mail (MAIL_* in app .env) |
Success and failure notifications are sent via Laravel's mailer — if SMTP is missing or misconfigured, the anonymization job can still finish but no email is delivered and the download link is only in that message |
anonymization.json on the server |
Must exist at /home/{app_user}/.db/ or
/home/{app_user}/.cipi/ before triggering a job
|
Agent vs Cipi API
Both Cipi components touch databases, but they solve different problems:
Agent anonymizer (cipi/agent) |
Cipi API backups (cipi/api) |
|
|---|---|---|
| Scope | One Laravel app's database (from the app's .env) |
Any database on the Cipi server (MariaDB vault) |
| Runs on | Inside the app (PHP + queue worker) | On the Cipi host via sudo cipi db … jobs |
| Output | SQL dump with Faker-transformed sensitive columns | Full compressed backup — real data, unchanged |
| Auth | CIPI_ANONYMIZER_TOKEN (per app) |
Sanctum token with dbs-manage (per server) |
| Typical endpoint | POST https://myapp.com/cipi/db |
POST https://api.example.com/api/dbs/{name}/backup |
| GDPR / PII | Designed for safe sharing — only configured columns are transformed | Disaster recovery and cloning — treat backups as production-secret |
DbBackup when you need a faithful snapshot for
restore. Use the agent anonymizer when people need data that looks
real but must not contain real identities. You can use both on the same project: backup for ops,
anonymize for humans.How it works
- An authenticated
POST /cipi/dbrequest (with a recipientemail, optionallygzip) validatesanonymization.jsonand queuesAnonymizeDatabaseJob - The job
- dumps the database with
mysqldumporpg_dump --format=plain(password viaMYSQL_PWD/PGPASSWORD, never on the command line) - streams the dump: MySQL extended
INSERTs are tokenized value by value, PostgreSQLCOPY … FROM stdinblocks field by field — only the columns listed inanonymization.jsonare rewritten, the rows oftruncatetables are dropped, everything else is copied byte for byte - deletes the original dump, writes
storage/cipi/anonymized_{jobId}.sql(.sql.gzwith gzip) with permissions0600
- dumps the database with
- On success, Laravel sends an email with a time-limited download URL
(
CIPI_ANONYMIZER_TTL, default 15 minutes) and a summary: size, rows transformed per table, tables emptied, warnings GET /cipi/db/{token}serves the file — no Bearer token; the signed URL itself is the credential- On failure, a plain-text error email is sent to the same address
The sequence is the same whichever client sends the request — curl, a CI job, or
cipi-cli db anonymize: the client only changes
who assembles the URL and the token.
Email notifications
The HTTP API does not return the download URL in the JSON response — email is the only
delivery channel for POST /cipi/db. Understanding who receives it and
what must be configured avoids silent failures.
Who receives the email?
Exactly the address you pass in the JSON body — nothing else:
{ "email": "developer@example.com" }
- Success → HTML email with the signed download link (15 minutes)
- Failure → plain-text email with the error and job ID
- No CC, BCC, or fallback to the Cipi admin,
CIPI_APP_USER, or a fixed address in.env - Whoever holds
CIPI_ANONYMIZER_TOKENchooses the recipient on each request
Laravel mail must work
Notifications use Laravel's Mail facade and your application's
MAIL_* settings — the same config as password resets or contact forms. This is
independent of Cipi server SMTP (cipi smtp configure for backup/deploy
alerts on the host).
Typical production .env entries:
MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=...
MAIL_PASSWORD=...
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@myapp.example.com
MAIL_FROM_NAME="${APP_NAME}"
storage/cipi/anonymized_{jobId}.sql on the server even when mail failed. The API
still returned {"status":"queued"} immediately — that only means the job was
queued, not that email delivery succeeded. Check storage/logs/laravel.log for mail
errors, verify MAIL_*, and send a test message before relying on
POST /cipi/db in production.
Quick mail test (as the app user, before your first export):
php artisan tinker --execute="Mail::raw('Cipi anonymizer mail test', fn (\$m) => \$m->to('you@example.com')->subject('Mail test'));"
If that message does not arrive, fix Laravel mail first — or use the CLI path
(php artisan cipi:anonymize) which writes the file directly and skips email.
Setup — step by step
Run these commands on the server as the app user (SSH:
ssh myapp@your-server or sudo su - myapp as root — see
SSH as the app user):
cipi-cli apps artisan myapp cipi:service anonymize --enable,
… cipi:generate-token anonymize, … cipi:init-anonymize (token ability
apps-artisan). Only editing anonymization.json still happens on the
server — see From your laptop with cipi-cli.1. Install the agent (if not already in composer.json):
composer require cipi/agent
# commit, push, deploy — or run on the current release
2. Enable the service and create a token:
php artisan cipi:service anonymize --enable php artisan cipi:generate-token anonymize
3. Create the configuration file — from the live schema (recommended) or from the built-in example:
php artisan cipi:init-anonymize --scan # proposes a config from your tables and columns php artisan cipi:init-anonymize # or: the generic example to edit by hand
This creates /home/{app_user}/.db/anonymization.json (permissions 0640).
With --scan the agent reads the schema and proposes a transformation for every column
that looks like personal data — e-mails, names, phones, addresses, IPs, tokens, passwords, tax ids,
card data, free-text notes — and empties the usual operational tables (sessions,
jobs, failed_jobs, password_reset_tokens,
personal_access_tokens, Telescope, Pulse…). Foreign keys and timestamps are never
touched. The file lives outside the Git repository — it is never deployed with your
code. Use --force to overwrite, --stdout to print, --path for
another location.
4. Review the config and audit it against the database (see Configuration):
php artisan cipi:anonymize-audit
The audit fails on tables or columns that do not exist and on unknown transformations, warns about
password columns not using password, and lists every column that looks like personal
data but is not covered — with a suggested transformation for each. Run it again whenever a
migration adds a column.
5. Verify queue and mail: confirm the worker runs jobs and Laravel can send to the
address you will pass in POST /cipi/db (see
Email notifications).
php artisan cipi:status # DB connectivity php artisan queue:work --once # optional: confirm worker can run jobs # send a test email — must arrive before using POST /cipi/db php artisan tinker --execute="Mail::raw('Mail test', fn (\$m) => \$m->to('you@example.com')->subject('Mail test'));"
6. Trigger your first anonymized export via HTTP, cipi-cli or Artisan (see examples below).
Configuration
Valid paths (first match wins):
CIPI_ANONYMIZER_CONFIG— an explicit path, when set/home/{app_user}/.db/anonymization.json— recommended/home/{app_user}/.cipi/anonymization.json— alternative
The JSON file has three top-level keys: transformations (required),
truncate (optional) and options (optional). A JSON Schema is published
with vendor:publish --tag=cipi-schemas and served to assistants as
cipi://anonymization.json/schema.
{
"transformations": {
"users": {
"name": "fakeName",
"email": { "type": "fakeEmail", "unique": true, "consistent": true },
"password": "password",
"remember_token": "null",
"phone": "mask:3,2"
},
"orders": {
"customer_email": { "type": "fakeEmail", "consistent": true },
"card_last_four": "numerify:####",
"internal_notes": "fakeParagraph"
}
},
"truncate": ["sessions", "jobs", "failed_jobs", "password_reset_tokens", "personal_access_tokens"],
"options": {
"hash_algorithm": "auto",
"password": "password",
"faker_locale": "en_US",
"consistent": true,
"gzip": false
}
}
Under transformations, each key is a table name. Nested keys are
column names; a value is a transformation name ("fakeEmail"), a name
with an argument after a colon ("fixed:ACME", "numerify:###",
"mask:1,2", "hash:32"), or an object with type plus the
unique / consistent flags. Columns not listed keep their original
values, so you can anonymize PII while preserving foreign keys, enums and business-logic fields.
NULL stays NULL (except with fixed).
consistent— the same original value becomes the same fake value in every table and every run with the sameseed, so denormalized e-mails and names still join (users.email↔orders.customer_emailabove).unique— no two rows of a column receive the same value; on by default forfakeEmail,fakeSafeEmail,fakeUserName,fakeUuid,fakeTokenandfakeIban, the columns that usually carry a unique index.truncate— the table structure is kept, its rows are dropped from the dump: sessions, queue tables, tokens, Telescope and Pulse data.password— every row gets the hash ofoptions.password(defaultpassword), computed once, so developers can log in to the anonymized copy.hash_algorithm: autouses the app's Hash driver.
Supported transformations
php artisan cipi:anonymize --transformations prints the catalogue. The MCP
anonymizer tool (action transformations) returns the same list.
| Transformation | Output |
|---|---|
fakeName / fakeFirstName / fakeLastName |
Person names |
fakeUserName |
User name (unique) |
fakeEmail / fakeSafeEmail |
E-mail address (unique); fakeSafeEmail uses example.com/net/org |
fakeCompany / fakeJobTitle |
Company name, job title |
fakeAddress / fakeStreetAddress / fakeCity / fakeState / fakePostcode |
Postal address pieces |
fakeCountry / fakeCountryCode |
Country name / ISO code |
fakePhoneNumber |
Phone number |
fakeDate / fakeDateTime |
Y-m-d / Y-m-d H:i:s |
fakeUrl / fakeDomain |
URL, domain name |
fakeParagraph / fakeSentence / fakeText[:len] / fakeWord |
Lorem-style text (notes, bios, ticket bodies) |
fakeIban[:CC] / fakeCreditCardNumber |
Banking data in test ranges |
fakeIpv4 / fakeIpv6 / fakeMacAddress / fakeUserAgent |
Network identifiers, browser user agent |
fakeUuid / fakeToken[:length] / fakeIdentifier |
UUID v4 (unique), random hex token (unique), alphanumeric id for tax ids and passports |
fakeLatitude / fakeLongitude / fakeNumber[:digits] / fakeBoolean |
Coordinates, random integer, random true/false — numeric when the column is numeric |
numerify:### / lexify:??? / bothify:?# |
Patterns: # → digit, ? → letter |
password |
Hash of options.password (bcrypt, argon2 or the app's Hash driver), computed once |
null / empty / fixed:value / redact |
NULL, empty string, a constant, the string [REDACTED] |
hash[:len] / mask:first,last / keep |
SHA-256 of the original (seeded), keep the first/last characters (j*******om), leave untouched |
Options
| Option | Default | Description |
|---|---|---|
hash_algorithm |
auto |
auto (the app's Hash driver), bcrypt, argon / argon2id, argon2i, argon2d |
password |
password |
Plaintext every password column is set to (hashed once) |
faker_locale |
en_US |
Faker locale for names, addresses, phone formats (e.g. it_IT, de_DE) |
consistent |
false |
Default for every column: same original → same fake, across tables and runs with the same seed |
seed |
null |
Seed for consistent mode and hash; change it to get a different, still consistent, dataset |
gzip |
false |
Compress the output (.sql.gz); POST /cipi/db and cipi:anonymize --gzip can override it |
connection |
null |
A config/database.php connection to dump instead of the default one |
dump_args |
[] |
Extra flags for mysqldump / pg_dump (one flag per entry, e.g. --skip-triggers) |
preserve_ids |
true |
Accepted for compatibility — ids are never transformed |
metadata, settings, and audit tables.HTTP API — endpoints
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | /cipi/db |
Bearer CIPI_ANONYMIZER_TOKEN |
Queue an anonymization job ({"email": …, "gzip": true|false}); the config is
validated first; email sent when complete |
| POST | /cipi/db/user |
Bearer CIPI_ANONYMIZER_TOKEN |
Resolve users.id from email (debug helper) |
| GET | /cipi/db/{token} |
Signed URL (from email) | Download the .sql (or .sql.gz) dump; expires after
CIPI_ANONYMIZER_TTL minutes (default 15) |
When the anonymizer is disabled (CIPI_ANONYMIZER=false), routes return
404 — the endpoints are hidden entirely.
Practical examples (curl)
Set variables once (replace with your app domain and token from .env):
export APP_URL="https://myapp.example.com" export CIPI_ANONYMIZER_TOKEN="your-token-from-env"
1. Queue an anonymization job
curl -sS -X POST "${APP_URL}/cipi/db" \ -H "Authorization: Bearer ${CIPI_ANONYMIZER_TOKEN}" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{"email": "developer@example.com"}'
Successful response (200):
{
"status": "queued",
"message": "Database anonymization job has been queued. You will receive an email with download instructions when complete.",
"email": "developer@example.com",
"link_valid_minutes": 15
}
The HTTP call returns immediately with status: queued — that does not
guarantee the notification email was sent. Processing can take minutes on large databases (job
timeout: 1 hour). The completion message goes only to the email in your JSON body; if
nothing arrives, check storage/logs/laravel.log for mail transport errors,
php artisan queue:failed for a failed job, and that
MAIL_* is configured (see
Email notifications).
2. Download the dump (from email link)
The completion email contains a URL like:
https://myapp.example.com/cipi/db/AbCdEf...?expires=1710000000&signature=...
Save it with curl (paste the full URL from the email — no Bearer header):
curl -sS -L -o anonymized.sql "PASTE_FULL_SIGNED_URL_FROM_EMAIL" # Import locally (MySQL example) mysql -u root -p myapp_local < anonymized.sql
Expired or invalid links return 410 Gone or 404. Request a new export with
POST /cipi/db if the 15-minute window passed.
3. Look up a user ID by email
After anonymization, emails are fake — but user IDs stay the same. Use this before anonymizing to map a known production email to an ID you can find later in the dump:
curl -sS -X POST "${APP_URL}/cipi/db/user" \ -H "Authorization: Bearer ${CIPI_ANONYMIZER_TOKEN}" \ -H "Content-Type: application/json" \ -d '{"email": "customer@production.com"}'
{
"user_id": 42,
"email": "customer@production.com",
"found_at": "2026-06-10T14:22:01+00:00"
}
This queries the live users table — run only when you are allowed to touch production
data. It does not modify anything.
4. Error responses (troubleshooting)
| HTTP | Meaning | Fix |
|---|---|---|
| 403 | Invalid or missing Bearer token | Regenerate with php artisan cipi:generate-token anonymize |
| 404 | Service disabled or config file missing | cipi:service anonymize --enable and
cipi:init-anonymize
|
| 422 | Missing or invalid email in JSON body |
Send {"email":"you@example.com"} |
| 400 | Invalid anonymization.json — the response lists every error (unknown
transformation, bad option, table both truncated and transformed, …) |
Fix the file; php artisan cipi:anonymize-audit prints the same list |
| 500 | Token not configured, DB error, or dump tool missing | Check .env, mysqldump/pg_dump, Laravel logs
|
| — | API returned queued but no email (job may have succeeded) |
Verify MAIL_* and send a test with
php artisan tinker; read storage/logs/laravel.log for SMTP
errors — or use cipi:anonymize on the server to get the file without mail
|
From your laptop with cipi-cli
cipi-cli db anonymize (cipi-cli
1.5.0+) is the same POST /cipi/db flow driven from your terminal
through the Cipi API: you name the app, the CLI finds the
URL and the token, the agent does the rest. No SSH session, nothing exported, no Bearer token in
your shell history.
How it works
- Resolve the app —
GET /api/apps/{app}on the Cipi API (abilityapps-view). Custom and Node apps are refused: the anonymizer needs a Laravel app withcipi/agentinstalled. - Read the app
.env—GET /api/apps/{app}/env(apps-env):CIPI_ANONYMIZERmust betrue,CIPI_ANONYMIZER_TOKENbecomes the Bearer token,CIPI_ROUTE_PREFIX(defaultcipi) andAPP_URLbuild the endpoint. Anything missing stops here, with the exact command that fixes it. - Build the endpoint —
<APP_URL>/<prefix>/db, falling back tohttps://<primary domain>whenAPP_URLis not set.--urland--tokenoverride either value. - Call the agent —
POSTwithAuthorization: Bearer,Accept: application/jsonand{"email": …}. Redirects are never followed (a 301 would turn the POST into a GET on another host): the CLI reports theLocationand asks for--url. - Queued — the agent answers
status: queued. From here the worker, the email and the 15-minute link behave exactly as described above. The CLI does not poll: the agent has no job-status endpoint, email is the only channel. - Download —
cipi-cli db anonymize download "<signed url>"fetches the link from the email: the file name comes from the server,-opicks another,-o -streams to stdout, an existing file is never overwritten without--force, and an expired link (410) or unknown token (404) tells you to request a new dump.
Commands
# One-time setup: the Artisan steps above, run remotely through the Cipi API cipi-cli apps artisan myapp cipi:service anonymize --enable cipi-cli apps artisan myapp cipi:generate-token anonymize cipi-cli apps artisan myapp cipi:init-anonymize # then edit /home/myapp/.db/anonymization.json on the server (it never leaves it) # Request a dump: the agent emails the signed link cipi-cli prod db anonymize myapp --email dev@example.com → Requesting anonymized dump of 'myapp' via https://myapp.example.com/cipi/db ✓ Anonymization job queued for 'myapp' # Download it from the link in the email cipi-cli db anonymize download "https://myapp.example.com/cipi/db/AbCdEf...?expires=...&signature=..." -o myapp.sql ✓ Saved myapp.sql (24.5 MB) # Or straight into a local database cipi-cli db anonymize download "<signed url>" -o - | mysql -u root myapp_local
What the CLI tells you
Every failure names the fix. The messages map to the HTTP errors in the table above:
| Message | Fix |
|---|---|
The anonymizer is disabled on 'myapp' (CIPI_ANONYMIZER is not true) |
cipi-cli apps artisan myapp cipi:service anonymize --enable |
CIPI_ANONYMIZER_TOKEN is not set on 'myapp' |
cipi-cli apps artisan myapp cipi:generate-token anonymize |
'myapp' is a custom app / is a Node app |
The anonymizer needs a Laravel app with cipi/agent installed |
Invalid anonymizer token (403) |
Regenerate the token, or pass --token when the server .env is stale |
Configuration file not found (404) |
cipi-cli apps artisan myapp cipi:init-anonymize, then edit
/home/myapp/.db/anonymization.json on the server |
HTTP 404 — the anonymizer endpoint is not exposed by the app |
Install cipi/agent and enable the service. If .env was edited by hand the
cached config may still say false: run cipi:service anonymize
--enable, which rebuilds the configuration cache (agent 1.5.4+) |
the app redirected (HTTP 301) to … |
Pass --url with the canonical URL (for example the www host) |
the download link has expired (410) |
Request a new dump — links last 15 minutes |
apps env), a
Sanctum token with apps-view and apps-env (plus
apps-artisan for the setup commands) and cipi/agent
1.1.1+. --json prints the result for scripts. Full reference:
CLI client → db.Artisan — run on the server without HTTP
For scripts, cron, or one-off exports on the server. Without arguments the command uses the server
config and writes to storage/cipi/anonymized_<timestamp>.sql:
php artisan cipi:anonymize # server config → storage/cipi/ php artisan cipi:anonymize --gzip # .sql.gz php artisan cipi:anonymize /home/myapp/.db/anonymization.json /home/myapp/export.sql php artisan cipi:anonymize --check # validate + audit, no dump php artisan cipi:anonymize --transformations # list the catalogue php artisan cipi:anonymize-audit [--json] # config vs live schema
The command reports the dump dialect, output size, rows transformed per table, tables emptied,
duration and any warnings (for example an INSERT it could not parse, left unchanged), and
exits non-zero on failure. It does not send email — copy the file via SCP or your own secure
channel.
Comparison curl: Cipi API raw backup
For reference, a non-anonymized server backup via Cipi API looks like this (different host, token, and semantics):
export CIPI_API_URL="https://api.myserver.com" export CIPI_API_TOKEN="sanctum-token-with-dbs-manage" curl -sS -X POST "${CIPI_API_URL}/api/dbs/myapp_db/backup" \ -H "Authorization: Bearer ${CIPI_API_TOKEN}" \ -H "Accept: application/json"
That returns 202 with a job_id — poll GET /api/jobs/{id} for
the backup path on the server. The archive contains real production data; restrict
access accordingly.
Security and GDPR tips
- Store
CIPI_ANONYMIZER_TOKENin secrets management — anyone with it can queue dumps and query/cipi/db/user - Rotate the token after team changes:
php artisan cipi:generate-token anonymize - Disable when not needed:
php artisan cipi:service anonymize --disable(endpoints return 404) - Download links expire after
CIPI_ANONYMIZER_TTLminutes (default 15) — forward emails carefully - Every password in the dump is the hash of
options.password— tell the recipients, and never reuse a real password there - Prefer
consistent: truewith a privateseed: the dataset stays joinable without the fake values being guessable from the real ones - Run
cipi:anonymize-auditafter every migration — a newemailorphonecolumn is copied verbatim until it is listed - With
cipi-clinothing is stored on the laptop: the client readsCIPI_ANONYMIZER_TOKENthrough the Cipi API on every run (apps-envability) — so any Sanctum token holdingapps-envcan read it; scope those tokens too - Document which columns are transformed for your DPA / privacy policy
- Test the dump: grep for a known production email — it should not appear if
fakeEmailwas set on that column
/home/{app_user}/.db/ is already excluded from deploys). Never commit
anonymization.json to version control.
Security
Cipi Agent uses defense in depth: each feature has its own Bearer token and can be toggled off independently. When disabled, routes return 404 (hidden, not 403).
Token isolation
| Feature | Token variable | Endpoint |
|---|---|---|
| Webhook deploy | CIPI_WEBHOOK_TOKEN |
POST /cipi/webhook |
| Health check | CIPI_HEALTH_TOKEN (fallback: webhook token) |
GET /cipi/health |
| MCP server | CIPI_MCP_TOKEN |
POST /cipi/mcp |
| DB anonymizer | CIPI_ANONYMIZER_TOKEN |
POST /cipi/db, POST /cipi/db/user |
| Panel tools (optional) | CIPI_TOKEN — Sanctum token from cipi api token create |
Outbound, to the panel API via cipi/sdk |
Webhook verification
- GitHub —
X-Hub-Signature-256HMAC-SHA256 (X-Hub-SignatureSHA-1 legacy) - Bitbucket —
X-Hub-Signaturesha256=HMAC - GitLab and Azure DevOps —
X-Gitlab-Tokenheader comparison - Gitea —
X-Gitea-SignatureHMAC-SHA256
All comparisons are constant-time. What the agent writes about a deploy (actor, commit, delivery id, IP) is recorded by Cipi as a claim in the audit ledger, never as a fact.
MCP safety
- Blocked Artisan commands and SQL statements (see MCP server), one
statement per call, reads capped at
CIPI_MCP_MAX_ROWS, optional read-only mode (CIPI_MCP_DB_WRITE=false) - Secret redaction in logs and command output (
CIPI_MCP_REDACT) Originvalidation against the app host (CIPI_MCP_ALLOWED_ORIGINS),405onGET/DELETE, no sessions to hijack- Tool failures are reported with
isError, protocol errors with the JSON-RPC codes the clients expect; the file pathscipi_ymlmay read are confined to the app and its home
Anonymizer safety
- Config outside the repository (
/home/{app_user}/.db/,0640), validated before a job is queued - Database passwords via
MYSQL_PWD/PGPASSWORD, never on the command line; the original dump is deleted right after processing; outputs are0600 - Signed, time-limited download links (
signedmiddleware); downloads confined tostorage/cipi
Source code and releases: github.com/cipi-sh/agent (MIT).
ENV Variables
These variables are automatically injected by Cipi into the app's .env during
cipi app create. Toggle optional features with
php artisan cipi:service {type} --enable|--disable or set them manually.
| Variable | Description | Default |
|---|---|---|
| CIPI_WEBHOOK_TOKEN | Secret for webhook authentication (GitHub / Bitbucket / Gitea HMAC, GitLab / Azure token) | auto-generated |
| CIPI_APP_USER | Linux username for this app (paths, deploy trigger, logs) | auto-set |
| CIPI_HOME | Override the app home directory | /home/<app_user> |
| CIPI_PHP_VERSION | PHP version reported in the health check and used by cipi:yml generate |
system PHP |
| CIPI_DEPLOY_SCRIPT | Path to Deployer config | ~/.deployer/deploy.php |
| CIPI_DEPLOY_BRANCH | Branch that triggers a deploy (empty = any branch). Written by Cipi since 5.7.2 | empty |
| CIPI_ENV | The app's environment label (cipi app create --env, Cipi 5.8.0+), reported by cipi:status, app_info, deploy_status, the webhook answer and the health report (agent 2.1.0); the server uses it to pick cipi-<env>.yml |
production |
| CIPI_ROUTE_PREFIX | URL prefix for all agent routes | cipi |
| CIPI_LOG_CHANNEL | Laravel log channel for deploy events | null |
| CIPI_HEALTH_CHECK | Enable /cipi/health |
true |
| CIPI_HEALTH_TOKEN | Bearer token for health (falls back to webhook token) | none |
| CIPI_MCP | Enable /cipi/mcp |
false |
| CIPI_MCP_TOKEN | Bearer token for MCP | none |
| CIPI_MCP_ALLOWED_ORIGINS | Browser origins allowed on the MCP endpoint, comma-separated (* = any) |
the app host |
| CIPI_MCP_DB_WRITE | Allow INSERT / UPDATE / DELETE through db_query |
true |
| CIPI_MCP_MAX_ROWS | Default row cap for db_query (max 500) |
100 |
| CIPI_MCP_REDACT | Redact common secrets in logs and command output sent over MCP | true |
| CIPI_ANONYMIZER | Enable anonymizer at /cipi/db |
false |
| CIPI_ANONYMIZER_TOKEN | Bearer token for anonymizer | none |
| CIPI_ANONYMIZER_CONFIG | Explicit path of anonymization.json |
~/.db/anonymization.json |
| CIPI_ANONYMIZER_TTL | Minutes a download link stays valid | 15 |
| CIPI_MYSQLDUMP / CIPI_PG_DUMP | Dump binaries, when not on PATH |
from PATH |
| CIPI_PANEL | Expose the panel_* MCP tools when cipi/sdk is installed and configured |
true |
| CIPI_PANEL_APP | App name on the panel | CIPI_APP_USER |
| CIPI_BASE_URL / CIPI_TOKEN | Panel API URL and Sanctum token, read by cipi/sdk |
none |
php artisan cipi:generate-token {type} to generate tokens for
mcp, health, or anonymize. Use
php artisan cipi:service {type} --enable|--disable to toggle services — the
command updates your .env in place.