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.yml tooling — 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.

New in cipi/agent 2.0 (October 2026): MCP revisions up to 2026-07-28 with tool annotations and structured results, five new tools (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
bash
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):

bash
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
Agent vs panel API: this package runs inside each Laravel app (/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.
After installing the package, commit and push. Cipi will pick it up on the next deploy automatically.

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:

  • password transformation now sets every row to the hash of options.password (default password), computed once, instead of re-hashing the stored hash — the anonymized copy is finally usable for login. Set options.password if you relied on a specific value.
  • Health no longer reports degraded when deploy metadata is missing or the last automatic deploy failed (the previous release is still live); the information is in checks.deploy.
  • Deploy trigger file gained source, actor, ip, ref and request_id for the audit ledger; the 1.x keys are still written.
  • db_query additionally blocks ALTER, RENAME, CREATE …, administrative statements and multi-statement input; CIPI_MCP_DB_WRITE=false makes it read-only. artisan additionally blocks db:wipe, migrate:fresh, migrate:reset, pail and horizon:*.
  • PostgreSQL dumps switch from custom to plain format so that they can actually be transformed.
  • Publishing — --tag=cipi-agent-config publishes only this package's config; cipi-config is shared with cipi/sdk and 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:

bash
cipi deploy myapp --webhook

Branch filtering

Only a push to the branch named in .env deploys:

env
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:

json
{"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+).

bash
curl -H "Authorization: Bearer YOUR_CIPI_HEALTH_TOKEN" \
    https://yourdomain.com/cipi/health
json
{
  "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:

  1. Deployer's REVISION file in the live release (/home/{app_user}/current/REVISION)
  2. /home/{app_user}/.cipi/deploy.json or .cipi/last_commit
  3. .git/HEAD or git 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:

bash
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 with cipi.mcp_blocked_artisan in 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 without LIMIT are capped at CIPI_MCP_MAX_ROWS (default 100, max 500); CIPI_MCP_DB_WRITE=false makes 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 Origin that is not the app host is refused with 403 (DNS-rebinding guard); extend with CIPI_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):

bash
php artisan cipi:mcp

Cursor

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

json
{
  "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:

json
{
  "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

bash
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:

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:

bash
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:

conversation
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:

bash
composer require cipi/sdk
# on the server, once:
cipi api token create     # abilities: apps-view, deploy-manage, dbs-manage, status-view
env
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.

The MCP server does not require SSH access to the VPS. It works entirely over HTTPS with its own Bearer token. This makes it ideal for teams where developers should be able to monitor, debug and deploy without root access.
Keep your 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.
Two MCP servers in Cipi: Agent MCP (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.

bash
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.

bash
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
# 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.

The local validator and the server validator are the same schema. When a Cipi release adds a 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.

Prefer the terminal? 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.com requests 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:anonymize on the server or trigger POST /cipi/db from 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
Use Cipi API 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

  1. An authenticated POST /cipi/db request (with a recipient email, optionally gzip) validates anonymization.json and queues AnonymizeDatabaseJob
  2. The job
    • dumps the database with mysqldump or pg_dump --format=plain (password via MYSQL_PWD / PGPASSWORD, never on the command line)
    • streams the dump: MySQL extended INSERTs are tokenized value by value, PostgreSQL COPY … FROM stdin blocks field by field — only the columns listed in anonymization.json are rewritten, the rows of truncate tables are dropped, everything else is copied byte for byte
    • deletes the original dump, writes storage/cipi/anonymized_{jobId}.sql (.sql.gz with gzip) with permissions 0600
  3. 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
  4. GET /cipi/db/{token} serves the file — no Bearer token; the signed URL itself is the credential
  5. 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:

json
{ "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_TOKEN chooses 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:

env
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}"
Job succeeded, inbox empty? The dump may already exist under 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):

bash
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):

No SSH? Steps 2 and 3 are Artisan commands, so they also run from your laptop through the Cipi API: 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):

bash
composer require cipi/agent
# commit, push, deploy — or run on the current release

2. Enable the service and create a token:

bash
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:

bash
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):

bash
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).

bash
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.

json
{
  "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 same seed, so denormalized e-mails and names still join (users.email ↔ orders.customer_email above).
  • unique — no two rows of a column receive the same value; on by default for fakeEmail, fakeSafeEmail, fakeUserName, fakeUuid, fakeToken and fakeIban, 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 of options.password (default password), computed once, so developers can log in to the anonymized copy. hash_algorithm: auto uses 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
Anonymization is opt-in per column. If a table holds PII in a JSON column, blob, or column you forgot to list, that data is copied verbatim. Review schema regularly — especially 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):

bash
export APP_URL="https://myapp.example.com"
export CIPI_ANONYMIZER_TOKEN="your-token-from-env"

1. Queue an anonymization job

bash
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):

json
{
  "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:

text
https://myapp.example.com/cipi/db/AbCdEf...?expires=1710000000&signature=...

Save it with curl (paste the full URL from the email — no Bearer header):

bash
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:

bash
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"}'
json
{
  "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

  1. Resolve the app — GET /api/apps/{app} on the Cipi API (ability apps-view). Custom and Node apps are refused: the anonymizer needs a Laravel app with cipi/agent installed.
  2. Read the app .env — GET /api/apps/{app}/env (apps-env): CIPI_ANONYMIZER must be true, CIPI_ANONYMIZER_TOKEN becomes the Bearer token, CIPI_ROUTE_PREFIX (default cipi) and APP_URL build the endpoint. Anything missing stops here, with the exact command that fixes it.
  3. Build the endpoint — <APP_URL>/<prefix>/db, falling back to https://<primary domain> when APP_URL is not set. --url and --token override either value.
  4. Call the agent — POST with Authorization: Bearer, Accept: application/json and {"email": …}. Redirects are never followed (a 301 would turn the POST into a GET on another host): the CLI reports the Location and asks for --url.
  5. 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.
  6. Download — cipi-cli db anonymize download "<signed url>" fetches the link from the email: the file name comes from the server, -o picks 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

bash
# 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
Requirements: Cipi 5.0.3+ / API 1.14+ (for 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:

bash
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):

bash
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_TOKEN in 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_TTL minutes (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: true with a private seed: the dataset stays joinable without the fake values being guessable from the real ones
  • Run cipi:anonymize-audit after every migration — a new email or phone column is copied verbatim until it is listed
  • With cipi-cli nothing is stored on the laptop: the client reads CIPI_ANONYMIZER_TOKEN through the Cipi API on every run (apps-env ability) — so any Sanctum token holding apps-env can 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 fakeEmail was set on that column
The anonymization config maps your database schema. Keep it outside your repository (default path /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-256 HMAC-SHA256 (X-Hub-Signature SHA-1 legacy)
  • Bitbucket — X-Hub-Signature sha256= HMAC
  • GitLab and Azure DevOps — X-Gitlab-Token header comparison
  • Gitea — X-Gitea-Signature HMAC-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)
  • Origin validation against the app host (CIPI_MCP_ALLOWED_ORIGINS), 405 on GET/DELETE, no sessions to hijack
  • Tool failures are reported with isError, protocol errors with the JSON-RPC codes the clients expect; the file paths cipi_yml may 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 are 0600
  • Signed, time-limited download links (signed middleware); downloads confined to storage/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
Use 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.