Skill: visiongeist/coolify (version 2.1.1)

--- name: coolify description: Manage Coolify deployments, applications, databases, and services via the Coolify API. Use when the user wants to deploy, start, stop, restart, or manage applications hosted on Coolify. homepage: https://coolify.io user-invocable: true metadata: {"openclaw":{"emoji":"🚀","requires":{"bins":["node"],"env":["COOLIFY_TOKEN"]},"primaryEnv":"COOLIFY_TOKEN"}} --- # Coolify API Skill Comprehensive management of Coolify deployments, applications, databases, services, and infrastructure via the Coolify API. ## When to Use This Skill Use this skill when the user needs to: - Deploy applications to Coolify - Manage application lifecycle (start, stop, restart) - View application logs - Create and manage databases (PostgreSQL, MySQL, MongoDB, Redis, etc.) - Deploy Docker Compose services - Manage servers and infrastructure - Configure environment variables - Trigger and monitor deployments - Manage GitHub App integrations - Configure SSH private keys ## Prerequisites 1. **Coolify API Token** — Generate from Coolify dashboard: - Navigate to **Keys & Tokens** → **API tokens** - Create token with appropriate permissions (`read`, `write`, `deploy`) - Set `COOLIFY_TOKEN` environment variable 2. **bash, curl, jq** — Required for running bash scripts 3. **API Access** — Coolify Cloud (`app.coolify.io`) or self-hosted instance ## Quick Start ### Basic Commands ```bash # List all applications {baseDir}/scripts/coolify applications list # Get application details {baseDir}/scripts/coolify applications get --uuid abc-123 # Deploy an application {baseDir}/scripts/coolify deploy --uuid abc-123 --force # View application logs {baseDir}/scripts/coolify applications logs --uuid abc-123 # Restart an application {baseDir}/scripts/coolify applications restart --uuid abc-123 ``` --- ## Applications ### List Applications ```bash {baseDir}/scripts/coolify applications list ``` **Output:** ```json { "success": true, "data": [ { "uuid": "abc-123", "name": "my-app", "status": "running", "fqdn": "https://app.example.com" } ], "count": 1 } ``` ### Get Application Details ```bash {baseDir}/scripts/coolify applications get --uuid abc-123 ``` ### Application Lifecycle ```bash # Start {baseDir}/scripts/coolify applications start --uuid abc-123 # Stop {baseDir}/scripts/coolify applications stop --uuid abc-123 # Restart {baseDir}/scripts/coolify applications restart --uuid abc-123 ``` ### View Logs ```bash {baseDir}/scripts/coolify applications logs --uuid abc-123 ``` ### Environment Variables ```bash # List environment variables {baseDir}/scripts/coolify applications envs list --uuid abc-123 # Create environment variable {baseDir}/scripts/coolify applications envs create \ --uuid abc-123 \ --key DATABASE_URL \ --value "postgres://user:pass@host:5432/db" \ --is-runtime true \ --is-buildtime false # Update environment variable {baseDir}/scripts/coolify applications envs update \ --uuid abc-123 \ --env-uuid env-456 \ --value "new-value" # Bulk update environment variables {baseDir}/scripts/coolify applications envs bulk-update \ --uuid abc-123 \ --json '{"DATABASE_URL":"postgres://...","API_KEY":"..."}' # Delete environment variable {baseDir}/scripts/coolify applications envs delete \ --uuid abc-123 \ --env-uuid env-456 ``` ### Create Applications ```bash # Public Git repository {baseDir}/scripts/coolify applications create-public \ --project-uuid proj-123 \ --server-uuid server-456 \ --git-repository "https://github.com/user/repo" \ --git-branch main \ --name "My App" # Private GitHub App {baseDir}/scripts/coolify applications create-private-github-app \ --project-uuid proj-123 \ --server-uuid server-456 \ --github-app-uuid gh-789 \ --git-repository "user/repo" \ --git-branch main # Dockerfile {baseDir}/scripts/coolify applications create-dockerfile \ --project-uuid proj-123 \ --server-uuid server-456 \ --dockerfile-location "./Dockerfile" \ --name "My Docker App" # Docker Image {baseDir}/scripts/coolify applications create-dockerimage \ --project-uuid proj-123 \ --server-uuid server-456 \ --docker-image "nginx:latest" \ --name "Nginx" # Docker Compose {baseDir}/scripts/coolify applications create-dockercompose \ --project-uuid proj-123 \ --server-uuid server-456 \ --docker-compose-location "./docker-compose.yml" ``` --- ## Databases ### List Databases ```bash {baseDir}/scripts/coolify databases list ``` ### Get Database Details ```bash {baseDir}/scripts/coolify databases get --uuid db-123 ``` ### Database Lifecycle ```bash # Start {baseDir}/scripts/coolify databases start --uuid db-123 # Stop {baseDir}/scripts/coolify databases stop --uuid db-123 # Restart {baseDir}/scripts/coolify databases restart --uuid db-123 # Delete {baseDir}/scripts/coolify databases delete --uuid db-123 ``` ### Create Databases ```bash # PostgreSQL {baseDir}/scripts/coolify databases create-postgresql \ --project-uuid proj-123 \ --server-uuid server-456 \ --name "my-postgres" \ --postgres-user admin \ --postgres-password secret \ --postgres-db myapp # MySQL {baseDir}/scripts/coolify databases create-mysql \ --project-uuid proj-123 \ --server-uuid server-456 \ --name "my-mysql" # MariaDB {baseDir}/scripts/coolify databases create-mariadb \ --project-uuid proj-123 \ --server-uuid server-456 \ --name "my-mariadb" # MongoDB {baseDir}/scripts/coolify databases create-mongodb \ --project-uuid proj-123 \ --server-uuid server-456 \ --name "my-mongo" # Redis {baseDir}/scripts/coolify databases create-redis \ --project-uuid proj-123 \ --server-uuid server-456 \ --name "my-redis" # KeyDB {baseDir}/scripts/coolify databases create-keydb \ --project-uuid proj-123 \ --server-uuid server-456 \ --name "my-keydb" # ClickHouse {baseDir}/scripts/coolify databases create-clickhouse \ --project-uuid proj-123 \ --server-uuid server-456 \ --name "my-clickhouse" # Dragonfly {baseDir}/scripts/coolify databases create-dragonfly \ --project-uuid proj-123 \ --server-uuid server-456 \ --name "my-dragonfly" ``` ### Backups ```bash # List backup configurations {baseDir}/scripts/coolify databases backups list --uuid db-123 # Create backup configuration {baseDir}/scripts/coolify databases backups create \ --uuid db-123 \ --frequency "0 2 * * *" \ --enabled true # Get backup details {baseDir}/scripts/coolify databases backups get \ --uuid db-123 \ --backup-uuid backup-456 # Update backup {baseDir}/scripts/coolify databases backups update \ --uuid db-123 \ --backup-uuid backup-456 \ --frequency "0 3 * * *" # Trigger manual backup {baseDir}/scripts/coolify databases backups trigger \ --uuid db-123 \ --backup-uuid backup-456 # List backup executions {baseDir}/scripts/coolify databases backups executions \ --uuid db-123 \ --backup-uuid backup-456 # Delete backup configuration {baseDir}/scripts/coolify databases backups delete \ --uuid db-123 \ --backup-uuid backup-456 ``` --- ## Services (Docker Compose) ### List Services ```bash {baseDir}/scripts/coolify services list ``` ### Get Service Details ```bash {baseDir}/scripts/coolify services get --uuid service-123 ``` ### Service Lifecycle ```bash # Start {baseDir}/scripts/coolify services start --uuid service-123 # Stop {baseDir}/scripts/coolify services stop --uuid service-123 # Restart {baseDir}/scripts/coolify services restart --uuid service-123 # Delete {baseDir}/scripts/coolify services delete --uuid service-123 ``` ### Create Service ```bash {baseDir}/scripts/coolify services create \ --project-uuid proj-123 \ --server-uuid server-456 \ --name "My Service" \ --docker-compose '{"version":"3.8","services":{"web":{"image":"nginx"}}}' ``` ### Environment Variables ```bash # List {baseDir}/scripts/coolify services envs list --uuid service-123 # Create {baseDir}/scripts/coolify services envs create \ --uuid service-123 \ --key API_KEY \ --value "secret" # Update {baseDir}/scripts/coolify services envs update \ --uuid service-123 \ --env-uuid env-456 \ --value "new-secret" # Bulk update {baseDir}/scripts/coolify services envs bulk-update \ --uuid service-123 \ --json '{"API_KEY":"secret","DB_HOST":"localhost"}' # Delete {baseDir}/scripts/coolify services envs delete \ --uuid service-123 \ --env-uuid env-456 ``` --- ## Deployments ### Deploy Application ```bash # Deploy by UUID {baseDir}/scripts/coolify deploy --uuid abc-123 # Force rebuild {baseDir}/scripts/coolify deploy --uuid abc-123 --force # Deploy by tag {baseDir}/scripts/coolify deploy --tag production # Instant deploy (skip queue) {baseDir}/scripts/coolify deploy --uuid abc-123 --instant-deploy ``` ### List Deployments ```bash # List all running deployments {baseDir}/scripts/coolify deployments list # List deployments for specific application {baseDir}/scripts/coolify deployments list-for-app --uuid abc-123 ``` ### Get Deployment Details ```bash {baseDir}/scripts/coolify deployments get --uuid deploy-456 ``` ### Cancel Deployment ```bash {baseDir}/scripts/coolify deployments cancel --uuid deploy-456 ``` --- ## Servers ### List Servers ```bash {baseDir}/scripts/coolify servers list ``` ### Get Server Details ```bash {baseDir}/scripts/coolify servers get --uuid server-123 ``` ### Create Server ```bash {baseDir}/scripts/coolify servers create \ --name "Production Server" \ --ip "192.168.1.100" \ --port 22 \ --user root \ --private-key-uuid key-456 ``` ### Update Server ```bash {baseDir}/scripts/coolify servers update \ --uuid server-123 \ --name "Updated Name" \ --description "Production environment" ``` ### Validate Server ```bash {baseDir}/scripts/coolify servers validate --uuid server-123 ``` ### Get Server Resources ```bash # List all resources on server {baseDir}/scripts/coolify servers resources --uuid server-123 # Get domains configured on server {baseDir}/scripts/coolify servers domains --uuid server-123 ``` ### Delete Server ```bash {baseDir}/scripts/coolify servers delete --uuid server-123 ``` --- ## Projects ### List Projects ```bash {baseDir}/scripts/coolify projects list ``` ### Get Project Details ```bash {baseDir}/scripts/coolify projects get --uuid proj-123 ``` ### Create Project ```bash {baseDir}/scripts/coolify projects create \ --name "My Project" \ --description "Production project" ``` ### Update Project ```bash {baseDir}/scripts/coolify projects update \ --uuid proj-123 \ --name "Updated Name" ``` ### Delete Project ```bash {baseDir}/scripts/coolify projects delete --uuid proj-123 ``` ### Environments ```bash # List environments {baseDir}/scripts/coolify projects environments list --uuid proj-123 # Create environment {baseDir}/scripts/coolify projects environments create \ --uuid proj-123 \ --name "staging" # Get environment details {baseDir}/scripts/coolify projects environments get \ --uuid proj-123 \ --environment staging # Delete environment {baseDir}/scripts/coolify projects environments delete \ --uuid proj-123 \ --environment staging ``` --- ## Teams ### List Teams ```bash {baseDir}/scripts/coolify teams list ``` ### Get Current Team ```bash {baseDir}/scripts/coolify teams current ``` ### Get Team Members ```bash {baseDir}/scripts/coolify teams members ``` ### Get Team by ID ```bash {baseDir}/scripts/coolify teams get --id 1 ``` --- ## Security (Private Keys) ### List Private Keys ```bash {baseDir}/scripts/coolify security keys list ``` ### Get Private Key ```bash {baseDir}/scripts/coolify security keys get --uuid key-123 ``` ### Create Private Key ```bash {baseDir}/scripts/coolify security keys create \ --name "Production Key" \ --description "SSH key for production servers" \ --private-key "$(cat ~/.ssh/id_rsa)" ``` ### Update Private Key ```bash {baseDir}/scripts/coolify security keys update \ --uuid key-123 \ --name "Updated Key Name" ``` ### Delete Private Key ```bash {baseDir}/scripts/coolify security keys delete --uuid key-123 ``` --- ## GitHub Apps ### List GitHub Apps ```bash {baseDir}/scripts/coolify github-apps list ``` ### Get GitHub App ```bash {baseDir}/scripts/coolify github-apps get --uuid gh-123 ``` ### Create GitHub App ```bash {baseDir}/scripts/coolify github-apps create \ --name "My GitHub App" \ --app-id 123456 \ --installation-id 789012 \ --private-key "$(cat github-app-key.pem)" ``` ### Update GitHub App ```bash {baseDir}/scripts/coolify github-apps update \ --uuid gh-123 \ --name "Updated App Name" ``` ### Delete GitHub App ```bash {baseDir}/scripts/coolify github-apps delete --uuid gh-123 ``` ### List Repositories ```bash {baseDir}/scripts/coolify github-apps repos --uuid gh-123 ``` ### List Branches ```bash {baseDir}/scripts/coolify github-apps branches \ --uuid gh-123 \ --owner myorg \ --repo myrepo ``` --- ## Common Use Cases ### Deploy a New Application 1. **List available servers:** ```bash {baseDir}/scripts/coolify servers list ``` 2. **Create application:** ```bash {baseDir}/scripts/coolify applications create-public \ --project-uuid proj-123 \ --server-uuid server-456 \ --git-repository "https://github.com/user/repo" \ --git-branch main \ --name "My App" ``` 3. **Configure environment variables:** ```bash {baseDir}/scripts/coolify applications envs create \ --uuid <new-app-uuid> \ --key DATABASE_URL \ --value "postgres://..." \ --is-runtime true ``` 4. **Deploy:** ```bash {baseDir}/scripts/coolify deploy --uuid <new-app-uuid> ``` ### Set Up Database with Backups 1. **Create database:** ```bash {baseDir}/scripts/coolify databases create-postgresql \ --project-uuid proj-123 \ --server-uuid server-456 \ --name "production-db" ``` 2. **Configure daily backups:** ```bash {baseDir}/scripts/coolify databases backups create \ --uuid <db-uuid> \ --frequency "0 2 * * *" \ --enabled true ``` 3. **Trigger manual backup:** ```bash {baseDir}/scripts/coolify databases backups trigger \ --uuid <db-uuid> \ --backup-uuid <backup-uuid> ``` ### Monitor Application Health 1. **Check application status:** ```bash {baseDir}/scripts/coolify applications get --uuid abc-123 ``` 2. **View recent logs:** ```bash {baseDir}/scripts/coolify applications logs --uuid abc-123 ``` 3. **List recent deployments:** ```bash {baseDir}/scripts/coolify deployments list-for-app --uuid abc-123 ``` --- ## Troubleshooting ### "API token not configured" **Cause:** `COOLIFY_TOKEN` environment variable not set. **Solution:** ```bash export COOLIFY_TOKEN="your-token-here" ``` Or configure in OpenClaw config at `~/.openclaw/openclaw.json`: ```json { "skills": { "entries": { "coolify": { "apiKey": "your-token-here" } } } } ``` ### "Rate limit exceeded" **Cause:** Too many API requests in a short time. **Solution:** The client automatically retries with exponential backoff. Wait for the retry or reduce request frequency. ### "Application not found" **Cause:** Invalid or non-existent UUID. **Solution:** ```bash # List all applications to find correct UUID {baseDir}/scripts/coolify applications list ``` ### "connect ECONNREFUSED" **Cause:** Cannot connect to Coolify API. **Solution for self-hosted:** ```bash # Set custom API URL export COOLIFY_API_URL="https://your-coolify.example.com/api/v1" ``` **Solution for cloud:** Verify internet connection and that `app.coolify.io` is accessible. ### "Deployment failed" **Cause:** Build or deployment error. **Solution:** 1. Check deployment logs: ```bash {baseDir}/scripts/coolify deployments get --uuid deploy-456 ``` 2. Check application logs: ```bash {baseDir}/scripts/coolify applications logs --uuid abc-123 ``` 3. Verify environment variables are correct: ```bash {baseDir}/scripts/coolify applications envs list --uuid abc-123 ``` ### Node.js Not Found **Cause:** Node.js not installed or not in PATH. **Solution:** ```bash # macOS (via Homebrew) brew install node # Verify installation node --version ``` --- ## Output Format All commands return structured JSON: ### Success Response ```json { "success": true, "data": { ... }, "count": 42 } ``` ### Error Response ```json { "success": false, "error": { "type": "APIError", "message": "Application not found", "hint": "Use 'applications list' to find valid UUIDs" } } ``` --- ## Configuration ### Environment Variables | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `COOLIFY_TOKEN` | Yes | — | API token from Coolify dashboard | | `COOLIFY_API_URL` | No | `https://app.coolify.io/api/v1` | API base URL (for self-hosted) | ### Self-Hosted Coolify For self-hosted instances, set the API URL: ```bash export COOLIFY_API_URL="https://coolify.example.com/api/v1" export COOLIFY_TOKEN="your-token-here" ``` --- ## Additional Resources - **Coolify Documentation:** https://coolify.io/docs/ - **API Reference:** See `{baseDir}/references/API.md` - **GitHub:** https://github.com/coollabsio/coolify - **Discord:** https://coollabs.io/discord --- ## Edge Cases and Best Practices ### UUID vs Name Most commands require UUIDs, not names. Always use `list` commands first to find UUIDs: ```bash # Bad: Using name (will fail) {baseDir}/scripts/coolify applications get --uuid "my-app" # Good: Using UUID {baseDir}/scripts/coolify applications list # Find UUID first {baseDir}/scripts/coolify applications get --uuid abc-123 ``` ### Force Deployments Use `--force` flag carefully as it rebuilds from scratch: ```bash # Normal deployment (uses cache) {baseDir}/scripts/coolify deploy --uuid abc-123 # Force rebuild (slower, but ensures clean build) {baseDir}/scripts/coolify deploy --uuid abc-123 --force ``` ### Environment Variable Updates After updating environment variables, restart the application: ```bash # Update env var {baseDir}/scripts/coolify applications envs update \ --uuid abc-123 \ --env-uuid env-456 \ --value "new-value" # Restart to apply changes {baseDir}/scripts/coolify applications restart --uuid abc-123 ``` ### Backup Frequency Use cron expressions for backup schedules: | Expression | Description | |------------|-------------| | `0 2 * * *` | Daily at 2 AM | | `0 */6 * * *` | Every 6 hours | | `0 0 * * 0` | Weekly on Sunday at midnight | | `0 0 1 * *` | Monthly on 1st at midnight | --- ## Summary This skill provides complete access to Coolify's API across: - **Applications** — Deployment, lifecycle, logs, environment variables - **Databases** — 8 database types, backups, lifecycle management - **Services** — Docker Compose orchestration - **Deployments** — Trigger, monitor, cancel - **Servers** — Infrastructure management and validation - **Projects** — Organization and environment management - **Teams** — Access control and collaboration - **Security** — SSH key management - **GitHub Apps** — Repository integration All operations return structured JSON for easy agent consumption.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (HIGH)