Coolify

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:

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

# 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

{baseDir}/scripts/coolify applications list

Output:

{
  "success": true,
  "data": [
    {
      "uuid": "abc-123",
      "name": "my-app",
      "status": "running",
      "fqdn": "https://app.example.com"
    }
  ],
  "count": 1
}

Get Application Details

{baseDir}/scripts/coolify applications get --uuid abc-123

Application Lifecycle

# 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

{baseDir}/scripts/coolify applications logs --uuid abc-123

Environment Variables

# 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

# 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

{baseDir}/scripts/coolify databases list

Get Database Details

{baseDir}/scripts/coolify databases get --uuid db-123

Database Lifecycle

# 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

# 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

# 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

{baseDir}/scripts/coolify services list

Get Service Details

{baseDir}/scripts/coolify services get --uuid service-123

Service Lifecycle

# 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

{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

# 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

# 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

# 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

{baseDir}/scripts/coolify deployments get --uuid deploy-456

Cancel Deployment

{baseDir}/scripts/coolify deployments cancel --uuid deploy-456

Servers

List Servers

{baseDir}/scripts/coolify servers list

Get Server Details

{baseDir}/scripts/coolify servers get --uuid server-123

Create Server

{baseDir}/scripts/coolify servers create \
  --name "Production Server" \
  --ip "192.168.1.100" \
  --port 22 \
  --user root \
  --private-key-uuid key-456

Update Server

{baseDir}/scripts/coolify servers update \
  --uuid server-123 \
  --name "Updated Name" \
  --description "Production environment"

Validate Server

{baseDir}/scripts/coolify servers validate --uuid server-123

Get Server Resources

# 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

{baseDir}/scripts/coolify servers delete --uuid server-123

Projects

List Projects

{baseDir}/scripts/coolify projects list

Get Project Details

{baseDir}/scripts/coolify projects get --uuid proj-123

Create Project

{baseDir}/scripts/coolify projects create \
  --name "My Project" \
  --description "Production project"

Update Project

{baseDir}/scripts/coolify projects update \
  --uuid proj-123 \
  --name "Updated Name"

Delete Project

{baseDir}/scripts/coolify projects delete --uuid proj-123

Environments

# 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

{baseDir}/scripts/coolify teams list

Get Current Team

{baseDir}/scripts/coolify teams current

Get Team Members

{baseDir}/scripts/coolify teams members

Get Team by ID

{baseDir}/scripts/coolify teams get --id 1

Security (Private Keys)

List Private Keys

{baseDir}/scripts/coolify security keys list

Get Private Key

{baseDir}/scripts/coolify security keys get --uuid key-123

Create Private Key

{baseDir}/scripts/coolify security keys create \
  --name "Production Key" \
  --description "SSH key for production servers" \
  --private-key "$(cat ~/.ssh/id_rsa)"

Update Private Key

{baseDir}/scripts/coolify security keys update \
  --uuid key-123 \
  --name "Updated Key Name"

Delete Private Key

{baseDir}/scripts/coolify security keys delete --uuid key-123

GitHub Apps

List GitHub Apps

{baseDir}/scripts/coolify github-apps list

Get GitHub App

{baseDir}/scripts/coolify github-apps get --uuid gh-123

Create GitHub App

{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

{baseDir}/scripts/coolify github-apps update \
  --uuid gh-123 \
  --name "Updated App Name"

Delete GitHub App

{baseDir}/scripts/coolify github-apps delete --uuid gh-123

List Repositories

{baseDir}/scripts/coolify github-apps repos --uuid gh-123

List Branches

{baseDir}/scripts/coolify github-apps branches \
  --uuid gh-123 \
  --owner myorg \
  --repo myrepo

Common Use Cases

Deploy a New Application

1. List available servers:

   {baseDir}/scripts/coolify servers list
   

2. Create application:

   {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:

   {baseDir}/scripts/coolify applications envs create \
     --uuid  \
     --key DATABASE_URL \
     --value "postgres://..." \
     --is-runtime true
   

4. Deploy:

   {baseDir}/scripts/coolify deploy --uuid 
   

Set Up Database with Backups

1. Create database:

   {baseDir}/scripts/coolify databases create-postgresql \
     --project-uuid proj-123 \
     --server-uuid server-456 \
     --name "production-db"
   

2. Configure daily backups:

   {baseDir}/scripts/coolify databases backups create \
     --uuid  \
     --frequency "0 2 * * *" \
     --enabled true
   

3. Trigger manual backup:

   {baseDir}/scripts/coolify databases backups trigger \
     --uuid  \
     --backup-uuid 
   

Monitor Application Health

1. Check application status:

   {baseDir}/scripts/coolify applications get --uuid abc-123
   

2. View recent logs:

   {baseDir}/scripts/coolify applications logs --uuid abc-123
   

3. List recent deployments:

   {baseDir}/scripts/coolify deployments list-for-app --uuid abc-123
   

Troubleshooting

"API token not configured"

Cause: COOLIFY_TOKEN environment variable not set.

Solution:

export COOLIFY_TOKEN="your-token-here"

Or configure in OpenClaw config at ~/.openclaw/openclaw.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:

# List all applications to find correct UUID
{baseDir}/scripts/coolify applications list

"connect ECONNREFUSED"

Cause: Cannot connect to Coolify API.

Solution for self-hosted:

# 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:

   {baseDir}/scripts/coolify deployments get --uuid deploy-456
   

2. Check application logs:

   {baseDir}/scripts/coolify applications logs --uuid abc-123
   

3. Verify environment variables are correct:

   {baseDir}/scripts/coolify applications envs list --uuid abc-123
   

Node.js Not Found

Cause: Node.js not installed or not in PATH.

Solution:

# macOS (via Homebrew)
brew install node
Verify installation
node --version

Output Format

All commands return structured JSON:

Success Response

{
  "success": true,
  "data": { ... },
  "count": 42
}

Error Response

{
  "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:

export COOLIFY_API_URL="https://coolify.example.com/api/v1"
export COOLIFY_TOKEN="your-token-here"

Additional Resources

Edge Cases and Best Practices

UUID vs Name

Most commands require UUIDs, not names. Always use list commands first to find UUIDs:

# 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:

# 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:

# 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:

All operations return structured JSON for easy agent consumption.

Basic Commands

# 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

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:

export COOLIFY_API_URL="https://coolify.example.com/api/v1"
export COOLIFY_TOKEN="your-token-here"

"API token not configured"

Cause: COOLIFY_TOKEN environment variable not set.

Solution:

export COOLIFY_TOKEN="your-token-here"

Or configure in OpenClaw config at ~/.openclaw/openclaw.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:

# List all applications to find correct UUID
{baseDir}/scripts/coolify applications list

"connect ECONNREFUSED"

Cause: Cannot connect to Coolify API.

Solution for self-hosted:

# 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:

   {baseDir}/scripts/coolify deployments get --uuid deploy-456
   

2. Check application logs:

   {baseDir}/scripts/coolify applications logs --uuid abc-123
   

3. Verify environment variables are correct:

   {baseDir}/scripts/coolify applications envs list --uuid abc-123
   

Node.js Not Found

Cause: Node.js not installed or not in PATH.

Solution:

# macOS (via Homebrew)
brew install node
Verify installation
node --version