{"id":50516518,"url":"https://github.com/cipi-sh/agent","last_synced_at":"2026-06-03T00:31:43.241Z","repository":{"id":341684953,"uuid":"1171095810","full_name":"cipi-sh/agent","owner":"cipi-sh","description":"Cipi Agent for Laravel applications","archived":false,"fork":false,"pushed_at":"2026-03-16T20:12:54.000Z","size":120,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-20T18:12:40.895Z","etag":null,"topics":["ai","automation","cipi","database","databases","deploy","deployment","devops","gdpr-compliant","git","integration","laravel","mcp","mcp-server","package","php","pipeline","tool","vps","webhook"],"latest_commit_sha":null,"homepage":"https://cipi.sh/docs/agent","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cipi-sh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-02T21:43:17.000Z","updated_at":"2026-04-03T21:58:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cipi-sh/agent","commit_stats":null,"previous_names":["andreapollastri/cipi-agent","cipi-sh/agent"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/cipi-sh/agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipi-sh%2Fagent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipi-sh%2Fagent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipi-sh%2Fagent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipi-sh%2Fagent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cipi-sh","download_url":"https://codeload.github.com/cipi-sh/agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipi-sh%2Fagent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33843611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","automation","cipi","database","databases","deploy","deployment","devops","gdpr-compliant","git","integration","laravel","mcp","mcp-server","package","php","pipeline","tool","vps","webhook"],"created_at":"2026-06-03T00:31:42.694Z","updated_at":"2026-06-03T00:31:43.235Z","avatar_url":"https://github.com/cipi-sh.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eCipi Agent for Laravel\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  The official Laravel companion package for the \u003ca href=\"https://cipi.sh\"\u003e\u003cstrong\u003eCipi\u003c/strong\u003e\u003c/a\u003e server control panel.\u003cbr\u003e\n  Automated deployments, health monitoring, AI-powered management, and database anonymization — all in one package.\n\u003c/p\u003e\n\n---\n\n## What is Cipi Agent?\n\n**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:\n\n- **Webhook-triggered deployments** from GitHub and GitLab\n- **Real-time health monitoring** of your app, database, cache, and queue\n- **An MCP server** that lets AI assistants (Cursor, Claude Desktop) manage your production app\n- **A database anonymizer** that creates safe, privacy-compliant dumps for local development\n\nAll 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.\n\n\u003e **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.\n\n---\n\n## Table of Contents\n\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Webhook Deploy](#webhook-deploy)\n- [Health Check](#health-check)\n- [MCP Server](#mcp-server)\n- [Database Anonymizer](#database-anonymizer)\n- [Artisan Commands](#artisan-commands)\n- [Security](#security)\n- [Documentation](#documentation)\n- [License](#license)\n\n---\n\n## Requirements\n\n| Requirement | Version                                      |\n| ----------- | -------------------------------------------- |\n| PHP         | 8.3 or higher                                |\n| Laravel     | 12 or higher                                 |\n| Database    | MySQL or PostgreSQL (for the anonymizer)     |\n| CLI tools   | `mysqldump` / `pg_dump` (for the anonymizer) |\n\n---\n\n## Installation\n\n```bash\ncomposer require cipi/agent\n```\n\nThe service provider is **auto-discovered** — no changes to `config/app.php` are needed.\n\nIf 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:\n\n```bash\nphp artisan vendor:publish --tag=cipi-config\n```\n\nVerify that everything is configured correctly:\n\n```bash\nphp artisan cipi:status\n```\n\n---\n\n## Configuration\n\nAll 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.\n\n| Variable                | Default                  | Description                                                        |\n| ----------------------- | ------------------------ | ------------------------------------------------------------------ |\n| `CIPI_WEBHOOK_TOKEN`    | `\"\"`                     | Secret token for webhook authentication (set by Cipi)              |\n| `CIPI_APP_USER`         | `\"\"`                     | Linux username for the app (set by Cipi)                           |\n| `CIPI_PHP_VERSION`      | system PHP               | PHP version reported in health check (set by Cipi)                 |\n| `CIPI_DEPLOY_SCRIPT`    | `~/.deployer/deploy.php` | Path to the Deployer config file (set by Cipi)                     |\n| `CIPI_DEPLOY_BRANCH`    | `null`                   | Only deploy pushes to this branch (`null` = any branch)            |\n| `CIPI_ROUTE_PREFIX`     | `cipi`                   | URL prefix for all Cipi Agent routes                               |\n| `CIPI_LOG_CHANNEL`      | `null`                   | Laravel log channel for deploy events                              |\n| `CIPI_HEALTH_CHECK`     | `true`                   | Enable/disable the health check endpoint                           |\n| `CIPI_HEALTH_TOKEN`     | `\"\"`                     | Bearer token for health check (falls back to `CIPI_WEBHOOK_TOKEN`) |\n| `CIPI_MCP`              | `false`                  | Enable/disable the MCP server endpoint                             |\n| `CIPI_MCP_TOKEN`        | `\"\"`                     | Bearer token for MCP access                                        |\n| `CIPI_ANONYMIZER`       | `false`                  | Enable/disable the database anonymizer                             |\n| `CIPI_ANONYMIZER_TOKEN` | `\"\"`                     | Bearer token for anonymizer access                                 |\n\nYou can toggle features directly from the CLI without editing `.env` manually:\n\n```bash\nphp artisan cipi:service mcp --enable\nphp artisan cipi:service health --disable\nphp artisan cipi:service anonymize --enable\n```\n\n---\n\n## Webhook Deploy\n\nThe 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.\n\n**Endpoint:** `POST /cipi/webhook`\n\n### Supported Git Providers\n\n| Provider   | Authentication method             |\n| ---------- | --------------------------------- |\n| **GitHub** | `X-Hub-Signature-256` HMAC-SHA256 |\n| **GitLab** | `X-Gitlab-Token` header           |\n\n### Setup\n\n1. In your Git provider settings, add a new webhook pointing to:\n\n   ```\n   https://yourdomain.com/cipi/webhook\n   ```\n\n2. Use the value of `CIPI_WEBHOOK_TOKEN` as the webhook secret.\n\n3. Select **push events** as the trigger.\n\n\u003e **Tip:** On Cipi-managed servers, the webhook is configured automatically when you connect your Git repository through the panel.\n\n### Branch Filtering\n\nTo deploy only when a specific branch is pushed:\n\n```env\nCIPI_DEPLOY_BRANCH=main\n```\n\nWhen set, pushes to other branches are acknowledged (HTTP 200) but do not trigger a deploy.\n\n---\n\n## Health Check\n\nA lightweight monitoring endpoint that returns the real-time status of your application and its dependencies.\n\n**Endpoint:** `GET /cipi/health`\n\n### Authentication\n\nProtected by Bearer token. The endpoint resolves the token in this order:\n\n1. `CIPI_HEALTH_TOKEN` (dedicated)\n2. `CIPI_WEBHOOK_TOKEN` (fallback)\n\nGenerate a dedicated token:\n\n```bash\nphp artisan cipi:generate-token health\n```\n\n### Usage\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_TOKEN\" https://yourdomain.com/cipi/health\n```\n\n### Response Example\n\n```json\n{\n  \"status\": \"healthy\",\n  \"app_user\": \"myapp\",\n  \"php\": \"8.3.0\",\n  \"laravel\": \"11.0.0\",\n  \"environment\": \"production\",\n  \"checks\": {\n    \"app\": { \"ok\": true, \"version\": \"2.1.0\", \"debug\": false },\n    \"database\": { \"ok\": true, \"database\": \"myapp_prod\" },\n    \"cache\": { \"ok\": true },\n    \"queue\": { \"ok\": true, \"connection\": \"redis\", \"pending_jobs\": 0 },\n    \"deploy\": {\n      \"ok\": true,\n      \"commit\": \"a1b2c3d4e5f6...\",\n      \"short_commit\": \"a1b2c3d\"\n    }\n  },\n  \"timestamp\": \"2026-03-07T10:00:00.000000Z\"\n}\n```\n\n### Deploy Commit Detection\n\nThe last deployed commit is resolved from the first available source:\n\n1. `/home/{app_user}/.cipi/deploy.json` (Cipi deploy metadata)\n2. `/home/{app_user}/.cipi/last_commit`\n3. `/home/{app_user}/logs/deploy.log`\n4. `.git/HEAD`\n5. `git rev-parse HEAD`\n\n### Integration with Monitoring Tools\n\nThe health endpoint is ideal for services like **UptimeRobot**, **Grafana**, **Better Stack**, or any monitoring solution that supports HTTP checks with Bearer token authentication.\n\n---\n\n## MCP Server\n\nThe **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.\n\n**Endpoint:** `POST /cipi/mcp`\n\n### Setup\n\n**1. Enable the MCP server:**\n\n```bash\nphp artisan cipi:service mcp --enable\n```\n\n**2. Generate a dedicated token:**\n\n```bash\nphp artisan cipi:generate-token mcp\n```\n\n**3. Get client configuration:**\n\n```bash\nphp artisan cipi:mcp\n```\n\nThis prints ready-to-paste configuration snippets for:\n\n- **Cursor** — native HTTP transport (direct connection)\n- **Claude Desktop** — via `mcp-remote` bridge\n\n### Available Tools\n\nThe MCP server exposes six tools that AI assistants can use to inspect and manage your application:\n\n#### `health` — Application Status\n\nReturns the same comprehensive status as the `/cipi/health` endpoint: app version, database connectivity, cache, queue health, and last deploy commit.\n\n#### `app_info` — Application Configuration\n\nReturns full application configuration and environment details, including Laravel version, PHP version, configured services, and environment settings.\n\n#### `deploy` — Trigger Deployment\n\nTriggers a zero-downtime deployment through the Cipi deploy pipeline. The AI assistant can deploy new versions after reviewing code changes or fixing issues.\n\n#### `logs` — Read Application Logs\n\nReads and filters application logs with support for all Cipi log types:\n\n| Parameter | Values                                                                          | Description                          |\n| --------- | ------------------------------------------------------------------------------- | ------------------------------------ |\n| `type`    | `laravel`, `nginx`, `php`, `worker`, `deploy`                                   | Log file to read                     |\n| `level`   | `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency` | Minimum severity (Laravel logs only) |\n| `search`  | any string                                                                      | Case-insensitive keyword filter      |\n\nMulti-line entries (stack traces) are kept intact during filtering.\n\n#### `artisan` — Run Artisan Commands\n\nExecutes Artisan commands remotely. Long-running and potentially dangerous commands are blocked for safety (see [Security](#security)).\n\n#### `db_query` — Execute SQL Queries\n\nRuns SQL queries against the application database:\n\n- **Read:** `SELECT`, `SHOW`, `DESCRIBE`, `EXPLAIN`\n- **Write:** `INSERT`, `UPDATE`, `DELETE`\n- **Blocked:** `DROP`, `TRUNCATE`, `GRANT`, `REVOKE`, file I/O operations\n\nResults are formatted as a readable ASCII table, capped at 100 rows.\n\n### Example Workflow\n\nWith the MCP server enabled, you can ask your AI assistant things like:\n\n- _\"Check the health of the production app\"_\n- _\"Show me the last 50 error logs\"_\n- _\"Run `php artisan migrate:status`\"_\n- _\"Query the users table to find accounts created today\"_\n- _\"Deploy the latest changes\"_\n\n---\n\n## Database Anonymizer\n\nCreates 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.\n\n### Setup\n\n**1. Enable the anonymizer:**\n\n```bash\nphp artisan cipi:service anonymize --enable\n```\n\n**2. Generate a token:**\n\n```bash\nphp artisan cipi:generate-token anonymize\n```\n\n**3. Initialize the configuration file:**\n\n```bash\nphp artisan cipi:init-anonymize\n```\n\nThis 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.\n\n**4. Edit the configuration** to match your actual tables and sensitive columns:\n\n```json\n{\n  \"transformations\": {\n    \"users\": {\n      \"name\": \"fakeName\",\n      \"email\": \"fakeEmail\",\n      \"password\": \"password\",\n      \"phone\": \"fakePhoneNumber\"\n    },\n    \"orders\": {\n      \"customer_notes\": \"fakeParagraph\"\n    }\n  },\n  \"options\": {\n    \"hash_algorithm\": \"auto\",\n    \"faker_locale\": \"en_US\"\n  }\n}\n```\n\n### Supported Transformations\n\n| Transformation    | Output                                                          |\n| ----------------- | --------------------------------------------------------------- |\n| `fakeName`        | Full name (e.g., \"John Smith\")                                  |\n| `fakeFirstName`   | First name                                                      |\n| `fakeLastName`    | Last name                                                       |\n| `fakeEmail`       | Email address                                                   |\n| `fakeCompany`     | Company name                                                    |\n| `fakeAddress`     | Full street address                                             |\n| `fakeCity`        | City name                                                       |\n| `fakePostcode`    | Postal code                                                     |\n| `fakePhoneNumber` | Phone number                                                    |\n| `fakeDate`        | Random date                                                     |\n| `fakeUrl`         | URL                                                             |\n| `fakeParagraph`   | Lorem ipsum paragraph                                           |\n| `password`        | Re-hashes using the project's algorithm (bcrypt / argon / auto) |\n\n### API Endpoints\n\n#### Queue an Anonymization Job\n\n```bash\ncurl -X POST https://yourdomain.com/cipi/db \\\n  -H \"Authorization: Bearer $CIPI_ANONYMIZER_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\": \"developer@example.com\"}'\n```\n\nThe anonymization runs **asynchronously**. When complete, an email is sent to the provided address with a **signed download link** valid for 15 minutes.\n\n#### Lookup a User by Email\n\nUseful when debugging an anonymized dump — find the original user ID for a given email:\n\n```bash\ncurl -X POST https://yourdomain.com/cipi/db/user \\\n  -H \"Authorization: Bearer $CIPI_ANONYMIZER_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\": \"user@example.com\"}'\n```\n\n```json\n{\n  \"user_id\": 123,\n  \"email\": \"user@example.com\",\n  \"found_at\": \"2026-03-07T10:00:00.000000Z\"\n}\n```\n\n#### Download the Dump\n\nThe email contains a signed URL in this format:\n\n```\nGET /cipi/db/{token}\n```\n\nThe link expires after 15 minutes and the file is cleaned up after download.\n\n### CLI Anonymization\n\nFor scripting or CI pipelines, you can run the anonymizer directly:\n\n```bash\nphp artisan cipi:anonymize /path/to/anonymization.json /path/to/output.sql\n```\n\n---\n\n## Artisan Commands\n\nCipi Agent provides a complete set of Artisan commands for managing all features from the terminal.\n\n### Status \u0026 Info\n\n| Command                       | Description                                                  |\n| ----------------------------- | ------------------------------------------------------------ |\n| `php artisan cipi:status`     | Show agent configuration and live database connectivity      |\n| `php artisan cipi:deploy-key` | Print the SSH deploy key for the current app                 |\n| `php artisan cipi:mcp`        | Print the MCP endpoint URL and client configuration snippets |\n\n### Token Management\n\n| Command                                     | Description                               |\n| ------------------------------------------- | ----------------------------------------- |\n| `php artisan cipi:generate-token mcp`       | Generate a secure `CIPI_MCP_TOKEN`        |\n| `php artisan cipi:generate-token health`    | Generate a secure `CIPI_HEALTH_TOKEN`     |\n| `php artisan cipi:generate-token anonymize` | Generate a secure `CIPI_ANONYMIZER_TOKEN` |\n\n### Service Toggle\n\n| Command                                        | Description                       |\n| ---------------------------------------------- | --------------------------------- |\n| `php artisan cipi:service mcp --enable`        | Enable the MCP server             |\n| `php artisan cipi:service mcp --disable`       | Disable the MCP server            |\n| `php artisan cipi:service health --enable`     | Enable the health check endpoint  |\n| `php artisan cipi:service health --disable`    | Disable the health check endpoint |\n| `php artisan cipi:service anonymize --enable`  | Enable the database anonymizer    |\n| `php artisan cipi:service anonymize --disable` | Disable the database anonymizer   |\n\n### Database Anonymizer\n\n| Command                                        | Description                                            |\n| ---------------------------------------------- | ------------------------------------------------------ |\n| `php artisan cipi:init-anonymize`              | Create `anonymization.json` from the built-in template |\n| `php artisan cipi:anonymize \u003cconfig\u003e \u003coutput\u003e` | Run an anonymized dump directly from the CLI           |\n\n---\n\n## Security\n\nCipi Agent is designed with a **defense-in-depth** approach. Every feature has its own authentication layer and can be independently enabled or disabled.\n\n### Token Isolation\n\nEach feature uses a **dedicated Bearer token**. Compromising one token does not grant access to other features:\n\n| Feature        | Token variable          | Middleware              |\n| -------------- | ----------------------- | ----------------------- |\n| Webhook deploy | `CIPI_WEBHOOK_TOKEN`    | `VerifyWebhookToken`    |\n| Health check   | `CIPI_HEALTH_TOKEN`     | `VerifyHealthToken`     |\n| MCP server     | `CIPI_MCP_TOKEN`        | `VerifyMcpToken`        |\n| DB anonymizer  | `CIPI_ANONYMIZER_TOKEN` | `VerifyAnonymizerToken` |\n\n### Feature Gating\n\nWhen a feature is disabled, its middleware returns **HTTP 404** — the endpoint appears to not exist at all, revealing nothing to potential attackers.\n\n### Webhook Signature Verification\n\nThe webhook endpoint uses provider-specific verification:\n\n- **GitHub** — HMAC-SHA256 signature validation\n- **GitLab** — secret token header comparison\n\n### MCP Safety Measures\n\n- **Blocked Artisan commands:** `serve`, `tinker`, `queue:work`, `queue:listen`, `schedule:work`, `horizon`, `octane:start`, `reverb:start`\n- **Blocked SQL operations:** `DROP`, `TRUNCATE`, `GRANT`, `REVOKE`, and file I/O\n- **Query result limits:** maximum 100 rows per query\n\n### Anonymizer Safety\n\n- **Signed download URLs** with 15-minute expiration\n- **Automatic file cleanup** after download\n- **Configuration stored outside the repository** (`/home/{app_user}/.db/`) with restricted permissions\n\n---\n\n## Documentation\n\nThis package is part of the **Cipi** ecosystem. For full documentation including server setup guides, panel configuration, and deployment workflows, visit:\n\n**[cipi.sh](https://cipi.sh)**\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n\u003cp align=\"center\"\u003e\n  Built with care by \u003ca href=\"https://web.ap.it\"\u003eAndrea Pollastri\u003c/a\u003e for the \u003ca href=\"https://cipi.sh\"\u003eCipi\u003c/a\u003e community.\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcipi-sh%2Fagent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcipi-sh%2Fagent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcipi-sh%2Fagent/lists"}