PHPackages                             cipi/agent - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. cipi/agent

ActiveLibrary[Database & ORM](/categories/database)

cipi/agent
==========

Cipi Agent for Laravel — webhook deploy, health check, and server integration

1.5.3(1mo ago)065↓100%MITPHPPHP ^8.3

Since Mar 2Pushed 1mo agoCompare

[ Source](https://github.com/cipi-sh/agent)[ Packagist](https://packagist.org/packages/cipi/agent)[ RSS](/packages/cipi-agent/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (4)Versions (13)Used By (0)

Cipi Agent for Laravel
======================

[](#cipi-agent-for-laravel)

 The official Laravel companion package for the [**Cipi**](https://cipi.sh) server control panel.
 Automated deployments, health monitoring, AI-powered management, and database anonymization — all in one package.

---

What is Cipi Agent?
-------------------

[](#what-is-cipi-agent)

**Cipi Agent** is a Laravel package designed to work alongside the [Cipi](https://cipi.sh) server control panel. While Cipi manages your server infrastructure (LEMP stack, SSL, PHP versions, domains, etc.), this package bridges the gap between your Laravel application and Cipi by providing:

- **Webhook-triggered deployments** from GitHub and GitLab
- **Real-time health monitoring** of your app, database, cache, and queue
- **An MCP server** that lets AI assistants (Cursor, Claude Desktop) manage your production app
- **A database anonymizer** that creates safe, privacy-compliant dumps for local development

All features are configurable via environment variables with zero boilerplate. When you create an application through the Cipi panel, the required environment variables are injected automatically.

> **Note:** This package is built to work with servers managed by [Cipi](https://cipi.sh). While some features (health check, MCP server) can work standalone, full functionality — including automated deployments and log access — requires a Cipi-managed environment.

---

Table of Contents
-----------------

[](#table-of-contents)

- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
- [Webhook Deploy](#webhook-deploy)
- [Health Check](#health-check)
- [MCP Server](#mcp-server)
- [Database Anonymizer](#database-anonymizer)
- [Artisan Commands](#artisan-commands)
- [Security](#security)
- [Documentation](#documentation)
- [License](#license)

---

Requirements
------------

[](#requirements)

RequirementVersionPHP8.3 or higherLaravel12 or higherDatabaseMySQL or PostgreSQL (for the anonymizer)CLI tools`mysqldump` / `pg_dump` (for the anonymizer)---

Installation
------------

[](#installation)

```
composer require cipi/agent
```

The service provider is **auto-discovered** — no changes to `config/app.php` are needed.

If your application runs on a Cipi-managed server, the required environment variables are already in place. Otherwise, you can publish the configuration file to customize defaults:

```
php artisan vendor:publish --tag=cipi-config
```

Verify that everything is configured correctly:

```
php artisan cipi:status
```

---

Configuration
-------------

[](#configuration)

All settings are driven by environment variables. When Cipi creates your application, it sets the core variables automatically. You only need to configure the optional features you want to enable.

VariableDefaultDescription`CIPI_WEBHOOK_TOKEN``""`Secret token for webhook authentication (set by Cipi)`CIPI_APP_USER``""`Linux username for the app (set by Cipi)`CIPI_PHP_VERSION`system PHPPHP version reported in health check (set by Cipi)`CIPI_DEPLOY_SCRIPT``~/.deployer/deploy.php`Path to the Deployer config file (set by Cipi)`CIPI_DEPLOY_BRANCH``null`Only deploy pushes to this branch (`null` = any branch)`CIPI_ROUTE_PREFIX``cipi`URL prefix for all Cipi Agent routes`CIPI_LOG_CHANNEL``null`Laravel log channel for deploy events`CIPI_HEALTH_CHECK``true`Enable/disable the health check endpoint`CIPI_HEALTH_TOKEN``""`Bearer token for health check (falls back to `CIPI_WEBHOOK_TOKEN`)`CIPI_MCP``false`Enable/disable the MCP server endpoint`CIPI_MCP_TOKEN``""`Bearer token for MCP access`CIPI_ANONYMIZER``false`Enable/disable the database anonymizer`CIPI_ANONYMIZER_TOKEN``""`Bearer token for anonymizer accessYou can toggle features directly from the CLI without editing `.env` manually:

```
php artisan cipi:service mcp --enable
php artisan cipi:service health --disable
php artisan cipi:service anonymize --enable
```

---

Webhook Deploy
--------------

[](#webhook-deploy)

The webhook endpoint receives push events from your Git provider and writes a `.deploy-trigger` flag file. The Cipi cron picks up this flag and runs [Deployer](https://deployer.org) for zero-downtime deployments.

**Endpoint:** `POST /cipi/webhook`

### Supported Git Providers

[](#supported-git-providers)

ProviderAuthentication method**GitHub**`X-Hub-Signature-256` HMAC-SHA256**GitLab**`X-Gitlab-Token` header### Setup

[](#setup)

1. In your Git provider settings, add a new webhook pointing to:

    ```
    https://yourdomain.com/cipi/webhook

    ```
2. Use the value of `CIPI_WEBHOOK_TOKEN` as the webhook secret.
3. Select **push events** as the trigger.

> **Tip:** On Cipi-managed servers, the webhook is configured automatically when you connect your Git repository through the panel.

### Branch Filtering

[](#branch-filtering)

To deploy only when a specific branch is pushed:

```
CIPI_DEPLOY_BRANCH=main
```

When set, pushes to other branches are acknowledged (HTTP 200) but do not trigger a deploy.

---

Health Check
------------

[](#health-check)

A lightweight monitoring endpoint that returns the real-time status of your application and its dependencies.

**Endpoint:** `GET /cipi/health`

### Authentication

[](#authentication)

Protected by Bearer token. The endpoint resolves the token in this order:

1. `CIPI_HEALTH_TOKEN` (dedicated)
2. `CIPI_WEBHOOK_TOKEN` (fallback)

Generate a dedicated token:

```
php artisan cipi:generate-token health
```

### Usage

[](#usage)

```
curl -H "Authorization: Bearer YOUR_TOKEN" https://yourdomain.com/cipi/health
```

### Response Example

[](#response-example)

```
{
  "status": "healthy",
  "app_user": "myapp",
  "php": "8.3.0",
  "laravel": "11.0.0",
  "environment": "production",
  "checks": {
    "app": { "ok": true, "version": "2.1.0", "debug": false },
    "database": { "ok": true, "database": "myapp_prod" },
    "cache": { "ok": true },
    "queue": { "ok": true, "connection": "redis", "pending_jobs": 0 },
    "deploy": {
      "ok": true,
      "commit": "a1b2c3d4e5f6...",
      "short_commit": "a1b2c3d"
    }
  },
  "timestamp": "2026-03-07T10:00:00.000000Z"
}
```

### Deploy Commit Detection

[](#deploy-commit-detection)

The last deployed commit is resolved from the first available source:

1. `/home/{app_user}/.cipi/deploy.json` (Cipi deploy metadata)
2. `/home/{app_user}/.cipi/last_commit`
3. `/home/{app_user}/logs/deploy.log`
4. `.git/HEAD`
5. `git rev-parse HEAD`

### Integration with Monitoring Tools

[](#integration-with-monitoring-tools)

The health endpoint is ideal for services like **UptimeRobot**, **Grafana**, **Better Stack**, or any monitoring solution that supports HTTP checks with Bearer token authentication.

---

MCP Server
----------

[](#mcp-server)

The **Model Context Protocol** (MCP) server lets AI assistants interact with your production Laravel application through a standard JSON-RPC 2.0 interface. Compatible with **Cursor**, **Claude Desktop**, and any MCP-compatible client.

**Endpoint:** `POST /cipi/mcp`

### Setup

[](#setup-1)

**1. Enable the MCP server:**

```
php artisan cipi:service mcp --enable
```

**2. Generate a dedicated token:**

```
php artisan cipi:generate-token mcp
```

**3. Get client configuration:**

```
php artisan cipi:mcp
```

This prints ready-to-paste configuration snippets for:

- **Cursor** — native HTTP transport (direct connection)
- **Claude Desktop** — via `mcp-remote` bridge

### Available Tools

[](#available-tools)

The MCP server exposes six tools that AI assistants can use to inspect and manage your application:

#### `health` — Application Status

[](#health--application-status)

Returns the same comprehensive status as the `/cipi/health` endpoint: app version, database connectivity, cache, queue health, and last deploy commit.

#### `app_info` — Application Configuration

[](#app_info--application-configuration)

Returns full application configuration and environment details, including Laravel version, PHP version, configured services, and environment settings.

#### `deploy` — Trigger Deployment

[](#deploy--trigger-deployment)

Triggers a zero-downtime deployment through the Cipi deploy pipeline. The AI assistant can deploy new versions after reviewing code changes or fixing issues.

#### `logs` — Read Application Logs

[](#logs--read-application-logs)

Reads and filters application logs with support for all Cipi log types:

ParameterValuesDescription`type``laravel`, `nginx`, `php`, `worker`, `deploy`Log file to read`level``debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency`Minimum severity (Laravel logs only)`search`any stringCase-insensitive keyword filterMulti-line entries (stack traces) are kept intact during filtering.

#### `artisan` — Run Artisan Commands

[](#artisan--run-artisan-commands)

Executes Artisan commands remotely. Long-running and potentially dangerous commands are blocked for safety (see [Security](#security)).

#### `db_query` — Execute SQL Queries

[](#db_query--execute-sql-queries)

Runs SQL queries against the application database:

- **Read:** `SELECT`, `SHOW`, `DESCRIBE`, `EXPLAIN`
- **Write:** `INSERT`, `UPDATE`, `DELETE`
- **Blocked:** `DROP`, `TRUNCATE`, `GRANT`, `REVOKE`, file I/O operations

Results are formatted as a readable ASCII table, capped at 100 rows.

### Example Workflow

[](#example-workflow)

With the MCP server enabled, you can ask your AI assistant things like:

- *"Check the health of the production app"*
- *"Show me the last 50 error logs"*
- *"Run `php artisan migrate:status`"*
- *"Query the users table to find accounts created today"*
- *"Deploy the latest changes"*

---

Database Anonymizer
-------------------

[](#database-anonymizer)

Creates anonymized database dumps by replacing sensitive data (names, emails, passwords, addresses) with realistic fake values generated by [Faker](https://fakerphp.github.io/). The resulting SQL file is safe to share with developers, use in CI pipelines, or load into local environments.

### Setup

[](#setup-2)

**1. Enable the anonymizer:**

```
php artisan cipi:service anonymize --enable
```

**2. Generate a token:**

```
php artisan cipi:generate-token anonymize
```

**3. Initialize the configuration file:**

```
php artisan cipi:init-anonymize
```

This creates `/home/{app_user}/.db/anonymization.json` from the built-in template. The file is stored **outside the project repository** to keep sensitive field mappings out of version control (permissions `0640`). Use `--force` to overwrite an existing file.

**4. Edit the configuration** to match your actual tables and sensitive columns:

```
{
  "transformations": {
    "users": {
      "name": "fakeName",
      "email": "fakeEmail",
      "password": "password",
      "phone": "fakePhoneNumber"
    },
    "orders": {
      "customer_notes": "fakeParagraph"
    }
  },
  "options": {
    "hash_algorithm": "auto",
    "faker_locale": "en_US"
  }
}
```

### Supported Transformations

[](#supported-transformations)

TransformationOutput`fakeName`Full name (e.g., "John Smith")`fakeFirstName`First name`fakeLastName`Last name`fakeEmail`Email address`fakeCompany`Company name`fakeAddress`Full street address`fakeCity`City name`fakePostcode`Postal code`fakePhoneNumber`Phone number`fakeDate`Random date`fakeUrl`URL`fakeParagraph`Lorem ipsum paragraph`password`Re-hashes using the project's algorithm (bcrypt / argon / auto)### API Endpoints

[](#api-endpoints)

#### Queue an Anonymization Job

[](#queue-an-anonymization-job)

```
curl -X POST https://yourdomain.com/cipi/db \
  -H "Authorization: Bearer $CIPI_ANONYMIZER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "developer@example.com"}'
```

The anonymization runs **asynchronously**. When complete, an email is sent to the provided address with a **signed download link** valid for 15 minutes.

#### Lookup a User by Email

[](#lookup-a-user-by-email)

Useful when debugging an anonymized dump — find the original user ID for a given email:

```
curl -X POST https://yourdomain.com/cipi/db/user \
  -H "Authorization: Bearer $CIPI_ANONYMIZER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'
```

```
{
  "user_id": 123,
  "email": "user@example.com",
  "found_at": "2026-03-07T10:00:00.000000Z"
}
```

#### Download the Dump

[](#download-the-dump)

The email contains a signed URL in this format:

```
GET /cipi/db/{token}

```

The link expires after 15 minutes and the file is cleaned up after download.

### CLI Anonymization

[](#cli-anonymization)

For scripting or CI pipelines, you can run the anonymizer directly:

```
php artisan cipi:anonymize /path/to/anonymization.json /path/to/output.sql
```

---

Artisan Commands
----------------

[](#artisan-commands)

Cipi Agent provides a complete set of Artisan commands for managing all features from the terminal.

### Status & Info

[](#status--info)

CommandDescription`php artisan cipi:status`Show agent configuration and live database connectivity`php artisan cipi:deploy-key`Print the SSH deploy key for the current app`php artisan cipi:mcp`Print the MCP endpoint URL and client configuration snippets### Token Management

[](#token-management)

CommandDescription`php artisan cipi:generate-token mcp`Generate a secure `CIPI_MCP_TOKEN``php artisan cipi:generate-token health`Generate a secure `CIPI_HEALTH_TOKEN``php artisan cipi:generate-token anonymize`Generate a secure `CIPI_ANONYMIZER_TOKEN`### Service Toggle

[](#service-toggle)

CommandDescription`php artisan cipi:service mcp --enable`Enable the MCP server`php artisan cipi:service mcp --disable`Disable the MCP server`php artisan cipi:service health --enable`Enable the health check endpoint`php artisan cipi:service health --disable`Disable the health check endpoint`php artisan cipi:service anonymize --enable`Enable the database anonymizer`php artisan cipi:service anonymize --disable`Disable the database anonymizer### Database Anonymizer

[](#database-anonymizer-1)

CommandDescription`php artisan cipi:init-anonymize`Create `anonymization.json` from the built-in template`php artisan cipi:anonymize  `Run an anonymized dump directly from the CLI---

Security
--------

[](#security)

Cipi Agent is designed with a **defense-in-depth** approach. Every feature has its own authentication layer and can be independently enabled or disabled.

### Token Isolation

[](#token-isolation)

Each feature uses a **dedicated Bearer token**. Compromising one token does not grant access to other features:

FeatureToken variableMiddlewareWebhook deploy`CIPI_WEBHOOK_TOKEN``VerifyWebhookToken`Health check`CIPI_HEALTH_TOKEN``VerifyHealthToken`MCP server`CIPI_MCP_TOKEN``VerifyMcpToken`DB anonymizer`CIPI_ANONYMIZER_TOKEN``VerifyAnonymizerToken`### Feature Gating

[](#feature-gating)

When a feature is disabled, its middleware returns **HTTP 404** — the endpoint appears to not exist at all, revealing nothing to potential attackers.

### Webhook Signature Verification

[](#webhook-signature-verification)

The webhook endpoint uses provider-specific verification:

- **GitHub** — HMAC-SHA256 signature validation
- **GitLab** — secret token header comparison

### MCP Safety Measures

[](#mcp-safety-measures)

- **Blocked Artisan commands:** `serve`, `tinker`, `queue:work`, `queue:listen`, `schedule:work`, `horizon`, `octane:start`, `reverb:start`
- **Blocked SQL operations:** `DROP`, `TRUNCATE`, `GRANT`, `REVOKE`, and file I/O
- **Query result limits:** maximum 100 rows per query

### Anonymizer Safety

[](#anonymizer-safety)

- **Signed download URLs** with 15-minute expiration
- **Automatic file cleanup** after download
- **Configuration stored outside the repository** (`/home/{app_user}/.db/`) with restricted permissions

---

Documentation
-------------

[](#documentation)

This package is part of the **Cipi** ecosystem. For full documentation including server setup guides, panel configuration, and deployment workflows, visit:

**[cipi.sh](https://cipi.sh)**

---

License
-------

[](#license)

MIT — see [LICENSE](LICENSE).

---

 Built with care by [Andrea Pollastri](https://web.ap.it) for the [Cipi](https://cipi.sh) community.

###  Health Score

45

—

FairBetter than 92% of packages

Maintenance95

Actively maintained with recent releases

Popularity12

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

12

Last Release

53d ago

PHP version history (2 changes)1.0PHP ^8.1

1.5PHP ^8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/449a18cf58263a03f804b68077a817e79b50bc24a6764e67242a3bcad337acdd?d=identicon)[cipi](/maintainers/cipi)

---

Top Contributors

[![andreapollastri](https://avatars.githubusercontent.com/u/18210420?v=4)](https://github.com/andreapollastri "andreapollastri (23 commits)")

---

Tags

aiawsclouddatabasedeploydevopsdigitaloceangdprgitgithubgitlablaravelpackagephppipelinetoolvpswebhookphpclilaravelserverlinuxdeploylempcipi

### Embed Badge

![Health badge](/badges/cipi-agent/health.svg)

```
[![Health](https://phpackages.com/badges/cipi-agent/health.svg)](https://phpackages.com/packages/cipi-agent)
```

###  Alternatives

[laravel-doctrine/orm

An integration library for Laravel and Doctrine ORM

8425.3M86](/packages/laravel-doctrine-orm)[laravel/wayfinder

Generate TypeScript representations of your Laravel actions and routes.

1.7k4.1M69](/packages/laravel-wayfinder)[nunomaduro/laravel-console-menu

Laravel Console Menu is an output method for your Laravel/Laravel Zero commands.

815412.0k48](/packages/nunomaduro-laravel-console-menu)[glushkovds/phpclickhouse-laravel

Adapter of the most popular library https://github.com/smi2/phpClickHouse to Laravel

2031.2M2](/packages/glushkovds-phpclickhouse-laravel)[cybercog/laravel-clickhouse

ClickHouse migrations for Laravel

163166.8k](/packages/cybercog-laravel-clickhouse)[sebastiaanluca/laravel-boolean-dates

Automatically convert Eloquent model boolean attributes to dates (and back).

40111.7k1](/packages/sebastiaanluca-laravel-boolean-dates)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)