coolify-operator

Files (3)

• .env.example
• SKILL.md
• evals.json · evals/

SKILL.md (first lines)

# Coolify Operator

Skill for operating Coolify instances through the **official CLI** or **REST API**. Coolify is a self-hosted open-source platform alternative to Heroku/Vercel/Netlify for deploying applications, databases, and services.

**Pinned upstream:** coolify-cli **v1.11.0** (`3738289a2a47050fa70007a571fbed00cb1c6d6e`) — Coolify v4 surface. Prefer command forms from `llms.txt` / `llms-full.txt` on that tag.

**Release notes reviewed:** Coolify v4.5.3 (October 2026). This records upstream changes; it does not assert that every homelab instance has been upgraded.

### CLI v1.11.0 Highlights

- **New:** `coolify server hostinger catalog|data-centers|templates|ssh-keys|post-install-scripts <cloud_token_uuid>` — inspect plans/prices, data centers, OS templates, SSH keys, and post-install scripts before provisioning (`catalog` alias: `plans`)
- **New:** `coolify server hostinger create` — buys a Hostinger VPS and adds it as a Coolify server. Paid and recurring: see **Server Provisioning on Hostinger** under Servers
- **New:** `coolify cloud-token create --provider hostinger` — Hostinger joins hetzner, digitalocean, and vultr
- **Security:** sensitive fields (tokens, passwords, private keys, secrets, IPs, emails) are now masked as `********` in `json` and `pretty` output too, not only in `table`; `-s` / `--show-sensitive` reveals them in every format. Scripts that read secrets from `--format json` must add `-s`
- **Changed:** `coolify context get` now uses the token-free view — it never prints the saved API token, in any format, even with `--show-sensitive`

### CLI v1.10.0 Highlights

- **New:** `coolify database import start|upload|status` and `coolify service database import ...` — restore backups from a local file, a previous upload, S3, or a server path
- **New:** `coolify audit list` — team audit log (admins/owners)
- **New:** `coolify integration-token create` + `coolify app secret-manager set` — Doppler / Infisical / Vault secret managers
- **New:** `coolify app previews logs`, `coolify teams update --build-server-fallback`, `coolify project environments get`
- **New:** `sqlite` database type (`--sqlite-databases`)
- `coolify service application logs` accepts `-n, --lines`

### CLI v1.9.0 Highlights

- **New:** `coolify app previews list|get|create|update` (preview deployments API, Coolify v4.4.0+)
- **New:** `coolify server registry list|login|check|logout` — Docker registry logins on servers
- **New:** `coolify mcp enable|disable` — toggle the instance MCP endpoint (requires a root team API token)
- **New:** `coolify server remove --force` / `--delete-from-provider`
- **New:** `--server-role deployment|build|both` on `server add` / `server update` (`--is-build-server` deprecated)
- **Changed:** `coolify server get <uuid> --resources` now calls `GET /servers/{uuid}/resources` and prints a flat list (`uuid`, `name`, `type`, `status`) instead of the server details
- GitHub App commands also accept the numeric app ID

### CLI v1.8.0 Highlights

- **New:** Commands for instance-wide SMTP/Resend settings (`coolify settings email get/update`)
- **Security:** API tokens redacted by default in `context list` output (use `--show-sensitive` to reveal); since v1.11.0 every output format masks sensitive fields, see CLI v1.11.0 Highlights
- **Fix:** `is_buildtime` field now correctly sent on app env create/update
- **Breaking:** `--retention-max-storage-locally` and `--retention-max-storage-s3` accept **numeric GB** (e.g., `1`, `10.5`), not unit-suffixed strings

## When to use this skill

- Connect to Coolify instances (via CLI contexts or API)
- Create, list, and manage applications, services, databases, and servers
- Deploy, restart, or stop resources
- View logs and deployment status
- Manage environment variables, shared envs, and storage
- Configure backups for databases
- Operate multiple Coolify instances (contexts)
- Integrate with GitHub / GitLab Apps for private repositories
- Configure notifications and instance email (SMTP/Resend)
- Manage cloud-init scripts and provision servers (Hetzner, DigitalOcean, Vultr, and Hostinger since CLI v1.11.0)
- Restore database backups (database import), read the team audit log, configure external secret managers, and manage Docker registry logins on servers

---

## Recent Changes (v4.5.x)

Highlights for operators, based on the [v4.5.0](https://github.com/coollabsio/coolify/releases/tag/v4.5.0) through [v4.5.3](https://github.com/coollabsio/coolify/releases/tag/v4.5.3) releases:

- **Security and access:** v4.5.0 encrypts secrets at rest, scopes deployment queries to the caller's team, and enforces instance IP allow-lists on the MCP endpoint. v4.5.1 uses Cloudflare's client IP for API allow-lists and audit logs when requests pass through Cloudflare. Confirm the source IP behavior before tightening allow-lists behind a proxy.
- **Sensitive API data:** v4.5.2 gates application commands/configuration, service configuration, custom database config, and custom Docker options by team role or the API token's `read:sensitive` ability. Grant that ability only when the operator needs those fields; treat returned values as secrets.
- **Service deletion:** v4.5.1 removed “Remove from Coolify only”. The `delete_from_coolify_only` services API option now returns HTTP 422. Do not use it as a way to unregister an unreachable service; ordinary deletion is designed to work when its server cannot be reached.
- **Timeouts and retries:** v4.5.3 stops retrying HTTP requests that timed out after being sent, to avoid duplicate actions. For state-changing API calls, a timeout is an unknown outcome: inspect the resource/deployment state before manually retrying.
- **Deploy/build fixes:** v4.5.3 preserves a Dockerfile `HEALTHCHECK`, fixes Compose builds whose required variable exists only at runtime, and fixes concurrent Railpack builds. If a deployment fails on these paths, first confirm the instance includes this release before changing the app configuration.
- **Preview variables:** v4.5.2 preserves production values when an existing PR preview is redeployed; newly created previews use their own variables. Check preview-specific environment values when diagnosing differences between a new preview and a redeploy.
- **Updates and recovery:** v4.5.0 adds an automatic database backup before Coolify updates. Still confirm backup health and recovery requirements before a maintenance window. v4.5.1 also adds per-server security patching in beta; inspect server scope and policy before enabling it.
- **v4.4 users:** v4.4.7 fixes multiple critical dependency CVEs. Upgrade at least to that patch if staying on the 4.4 line, or follow the appropriate security patch for the installed release line.

### New REST API operations in v4.5.0

Comparing the official OpenAPI specs for v4.4.7 and v4.5.0, these operations were added. The v4.5.0–v4.5.3 specs show no further added or removed REST operations:

| Operation | Purpose |
|---|---|
| `GET /hostinger/data-centers` | List Hostinger VPS data centers |
| `GET /hostinger/catalog` | List Hostinger VPS plans and prices |
| `GET /hostinger/templates` | List Hostinger OS templates |
| `GET /hostinger/ssh-keys` | List SSH keys in the connected Hostinger account |
| `GET /hostinger/post-install-scripts` | List Hostinger post-install scripts |
| `POST /servers/hostinger` | Purchase a Hostinger VPS and create its Coolify server record |
| `POST /servers/{uuid}/migrate` | Start a server migration to another Coolify instance |
| `GET /servers/{uuid}/transfer` | Check transfer progress/status |
| `GET /servers/import/check` | Check whether a transfer bundle can be imported |
| `POST /servers/import` | Import a server transfer bundle |
| `POST /servers/{uuid}/transfer/complete` | Mark a server transfer complete |

Server migrations run in the background. Check transfer status before treating a migration as complete. Hostinger provisioning can incur provider charges, so inspect the selected plan and data center before calling `POST /servers/hostinger`.

**Other v4.5.0 API contract changes (existing routes):** application updates accept `dockerfile` and `github_app_uuid`; database updates apply `redis_password` and `instant_deploy`; service creation accepts `connect_to_docker_network`. The application write API uses `domains` rather than `fqdn`, and `force_domain_override` is honored for `docker_compose_domains` on create.

### Built-in MCP server (v4.5.0+)

Coolify exposes its MCP server at `https://<coolify-host>/mcp` using Streamable HTTP. This is separate from the REST API base `/api/v1`. The instance MCP setting and the token's team MCP setting must both allow access. The endpoint also obeys the instance IP allow-list.

```bash
# Enable or disable the instance MCP endpoint (requires a root team API token)
coolify mcp enable
coolify mcp disable

# REST API equivalents
curl -sS -X POST -H "Authorization: Bearer $COOLIFY_KEY" "$COOLIFY/mcp/enable"
curl -sS -X POST -H "Authorization: Bearer $COOLIFY_KEY" "$COOLIFY/mcp/disable"
```

Create a team-scoped token and configure the MCP client with the instance URL plus `/mcp` and `Authorization: Bearer <token>`. Use `read` for inventory/inspection, add `read:sensitive` only for supported sensitive output, and add `deploy` for deploy/start/stop/restart/cancel actions. Avoid `root` for routine MCP use. Resource-management tools include inventory and discovery (`get_infrastructure_overview`, `search_resources`, `list_unhealthy_resources`), plus application, database, service, deployment, log, and lifecycle operations. Ask `coolify_help` or inspect MCP tool capabilities on the connected instance because available tools depend on version and token permissions. MCP responses do not return environment values or file contents; log summaries are limited and best-effort redacted.

The v4.5.0 release also notes that MCP API-token creation works while REST API access is disabled. This does not remove MCP's own instance/team enablement and IP-allow-list checks.

**Coolify application console command:** v4.5.0 adds Laravel Artisan `php artisan app-key:reencrypt` to re-encrypt stored secrets after rotating `APP_KEY`. It is not a `coolify` CLI subcommand; run it only in the Coolify application container as part of a planned key rotation, after reviewing the release instructions and taking a recoverable backup.

**CLI/API coverage:** the pinned coolify-cli v1.11.0 documents `coolify mcp enable|disable`, and since v1.11.0 it also covers Hostinger provisioning (`coolify server hostinger catalog|data-centers|templates|ssh-keys|post-install-scripts` and `coolify server hostinger create`, see **Server Provisioning on Hostinger** under Servers). Server transfer/migration is still not exposed by the CLI. Use the REST API/OpenAPI schema for those request bodies and permissions; do not invent a CLI equivalent.

### Operational checks after upgrading to v4.5.x

1. Verify the deployed Coolify version before relying on new behavior; the `coolify_version` metadata above tracks reviewed release notes, not the state of each instance.
2. For Cloudflare-proxied API access, validate the IP seen by Coolify before changing allow-lists, and confirm the access path still works.

From fabricioctelles/skills, Apache-2.0.

More from fabricioctelles/skills