This skill should be used when performing operational actions against a Coolify instance using MCP tools — deploying applications, checking deployment status, viewing logs, diagnosing errors, managing environment variables, restarting services, checking server health, or performing any hands-on Coolify management task. Trigger when: "deploy my app", "check Coolify status", "show me Coolify logs", "what's running on Coolify", "restart my app on Coolify", "check server health", "why is my deploy failing", "list my Coolify apps", "add env var to Coolify", "Coolify deployment status", "roll back my deploy", "check my databases", "what resources are on my server".
How this skill is triggered — by the user, by Claude, or both
Slash command
/rad-coolify-orchestrator:coolify-actionsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Operational playbooks for managing a Coolify instance using MCP tools. Each workflow maps a user intent to a specific sequence of `coolify_*` tool calls.
Operational playbooks for managing a Coolify instance using MCP tools. Each workflow maps a user intent to a specific sequence of coolify_* tool calls.
Requires: The
coolifyMCP server (bundled with this plugin via@radoriginllc/coolify-mcp). SetCOOLIFY_URLandCOOLIFY_API_TOKENenvironment variables. If MCP tools are not available, fall back to providing the equivalentcurlcommands from the coolify-cicd skill.
Before any workflow, confirm the MCP connection is live:
coolify_healthcheck — expect a "connected" responseIntent: "What's on my Coolify?", "list my apps", "what resources do I have?"
coolify_list_all_resources
For more detail on a specific category:
coolify_list_applications — all apps with statuscoolify_list_databases — all databasescoolify_list_services — one-click servicescoolify_list_servers — all managed serverscoolify_list_projects — project organizationPresent results as a summary table: name, status, type, domain.
Intent: "deploy my app", "trigger a deployment", "push to production"
Step 1: coolify_list_applications → find the app UUID
Step 2: coolify_deploy(uuid: "<APP_UUID>") → trigger deploy, capture deployment_uuid
Step 3: coolify_get_deployment(uuid: "<DEPLOYMENT_UUID>") → poll status
Polling pattern: After triggering deploy, wait 10-15 seconds, then poll coolify_get_deployment. Repeat until status is finished, failed, or cancelled. Report the result.
Force rebuild (skip cache): coolify_deploy(uuid: "<APP_UUID>", force: true)
Batch deploy by tag: coolify_deploy(tag: "backend") — deploys all resources with that tag.
Intent: "why did my deploy fail?", "deployment error", "build failed"
Step 1: coolify_list_applications → find app UUID
Step 2: coolify_list_deployments(uuid: "<APP_UUID>", take: 5) → get recent deployments
Step 3: coolify_get_deployment(uuid: "<FAILED_DEPLOYMENT_UUID>") → get full logs
Read the logs field in the deployment response. Look for:
undefined, ENOENT, KeyErrorENOMEM, KilledIf the build succeeded but the app isn't serving, continue to Workflow 5 (diagnose HTTP errors).
Intent: "show me logs", "what's in the logs?", "check logs for errors"
Step 1: coolify_list_applications → find app UUID
Step 2: coolify_get_application_logs(uuid: "<APP_UUID>", lines: 200)
Scan for error patterns: ERROR, Error, FATAL, Unhandled, stack traces, exit codes. Summarize findings for the user.
Intent: "getting a 502", "bad gateway", "site is down", "504 timeout"
This is a multi-step diagnostic. Follow the decision tree:
Step 1: coolify_list_applications → find app UUID and check status
Step 2: coolify_get_application(uuid: "<APP_UUID>") → check config (port, domain, health check)
Step 3: coolify_get_application_logs(uuid: "<APP_UUID>", lines: 100) → check for crashes
Step 4: coolify_list_deployments(uuid: "<APP_UUID>", take: 3) → check recent deploy status
Decision logic:
coolify_restart_applicationdocker logs coolify-proxy)See coolify-troubleshoot skill for the full diagnostic decision tree with all edge cases.
Intent: "add an env var", "update environment variable", "check what env vars are set"
List env vars:
Step 1: coolify_list_applications → find app UUID
Step 2: coolify_list_env_vars(uuid: "<APP_UUID>")
Add a new env var:
coolify_create_env_var(
uuid: "<APP_UUID>",
key: "DATABASE_URL",
value: "postgresql://..."
)
Update an existing env var (matched by key):
coolify_update_env_var(uuid: "<APP_UUID>", key: "DATABASE_URL", value: "postgresql://new-host...")
Delete an env var (needs the env var's own UUID, from the list call):
Step 1: coolify_list_env_vars(uuid: "<APP_UUID>") → find the env var UUID
Step 2: coolify_delete_env_var(uuid: "<APP_UUID>", env_uuid: "<ENV_UUID>")
Important: Env var changes take effect on the next deploy, not on restart — a restart reuses the existing container with the old values:
coolify_deploy(uuid: "<APP_UUID>")
Security reminder: Never set secrets as build-time variables unless using Docker Build Secrets. See coolify-security skill for the decision tree.
Intent: "how's my server?", "check server health", "is my server okay?"
Step 1: coolify_list_servers → list all servers with status
Step 2: coolify_get_server(uuid: "<SERVER_UUID>") → detailed server info
Step 3: coolify_get_server_resources(uuid: "<SERVER_UUID>") → all resources on server
Report: server reachability, number of running resources, any resource in error/stopped state.
For CPU/memory/disk metrics, the Coolify API does not expose Sentinel data — advise checking the dashboard UI at Servers → Metrics, or see coolify-observability for Grafana/Prometheus setup.
Intent: "restart my app", "stop the database", "start the service"
Applications: coolify_start_application, coolify_stop_application, coolify_restart_application
Databases: coolify_start_database, coolify_stop_database, coolify_restart_database
Services: coolify_start_service, coolify_stop_service, coolify_restart_service
Always confirm with the user before stopping production resources.
Intent: "roll back", "revert to previous version", "undo the deploy"
Step 1: coolify_list_deployments(uuid: "<APP_UUID>", take: 10) → find last successful deploy
Step 2: Identify the commit SHA or image tag from the last "finished" deployment
Step 3: coolify_update_application(uuid: "<APP_UUID>", settings: {"docker_registry_image_tag": "<PREVIOUS_TAG>"})
Step 4: coolify_deploy(uuid: "<APP_UUID>")
Limitation: Rollback only works if the previous Docker image still exists locally on the server. Automated Docker cleanup may have pruned it.
For git-based apps, rollback by updating the branch or commit reference rather than the image tag.
Cancel a bad deploy in progress: if a broken deployment is still building, cancel it instead of waiting it out:
Step 1: coolify_list_running_deployments → find the in-progress deployment UUID
Step 2: coolify_cancel_deployment(uuid: "<DEPLOYMENT_UUID>")
Intent: "check my databases", "are backups running?", "database status"
Step 1: coolify_list_databases → list all databases with status
Step 2: coolify_get_database(uuid: "<DB_UUID>") → detailed config and backup info
Step 3: coolify_list_database_backups(uuid: "<DB_UUID>") → scheduled backup configs
Step 4: coolify_list_backup_executions(uuid: "<DB_UUID>", scheduled_backup_uuid: "<BACKUP_UUID>") → run history
Check the execution history for failed runs and the timestamp of the last successful backup. Note: the API manages scheduled backups (POST /databases/{uuid}/backups creates a schedule, not a one-off run) — triggering an immediate manual backup still requires the Coolify dashboard.
| Intent | Tool | Key Params |
|---|---|---|
| List everything | coolify_list_all_resources | — |
| Find an app | coolify_list_applications | — |
| Deploy | coolify_deploy | uuid, tag, force |
| Check deploy status | coolify_get_deployment | uuid (deployment UUID) |
| Cancel a deploy | coolify_cancel_deployment | uuid (deployment UUID) |
| What's deploying now | coolify_list_running_deployments | — |
| View logs | coolify_get_application_logs | uuid, lines |
| App details | coolify_get_application | uuid |
| Restart | coolify_restart_application | uuid |
| Env vars | coolify_list_env_vars | uuid |
| Add env var | coolify_create_env_var | uuid, key, value |
| Update env var | coolify_update_env_var | uuid, key, value |
| Delete env var | coolify_delete_env_var | uuid, env_uuid |
| Update app config | coolify_update_application | uuid, settings |
| Service lifecycle | coolify_start/stop/restart_service | uuid |
| Backup configs | coolify_list_database_backups | uuid |
| Backup run history | coolify_list_backup_executions | uuid, scheduled_backup_uuid |
| Server health | coolify_get_server | uuid |
| Server resources | coolify_get_server_resources | uuid |
| Anti-Pattern | Consequence |
|---|---|
| Deploying without checking current status first | May deploy over a running debug session or ongoing rollback |
| Polling deployment status in a tight loop (< 5 seconds) | Overloads Coolify's database; use 10-15 second intervals |
| Restarting apps to "fix" problems without checking logs first | Masks the root cause; problem recurs on next deploy |
| Adding env vars without redeploying | Changes don't take effect until the next deploy — restarting is not enough |
| Stopping a database without checking which apps depend on it | Apps crash with connection errors |
Using force: true on every deploy | Defeats build caching; 3-10x slower builds for no benefit |
references/workflow-recipes.md — Extended workflows: bulk operations, multi-app coordination, automated health checksnpx claudepluginhub radorigin-llc/rad-claude-skills --plugin rad-coolify-orchestratorGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.