# coolify

A skill for driving self-hosted Coolify from your agent: app deploys, webhooks, CI/CD and build-pack troubleshooting.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 360 installs · ★ 20
- Author: oakoss
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/oakoss/agent-skills/tree/HEAD/skills/coolify/SKILL.md
- Updated: 2026-08-17
- HTML: https://affpapa.org/en/nevibecode/skills/coolify

## What it does

The skill covers Coolify control from an agent: token auth, listing applications, triggering a deploy, creating and patching apps over the REST API. Build packs get their own section — Nixpacks, Dockerfile and Compose — along with environment variables and Traefik domain routing.

Three reference files ship with it: `references/api-patterns.md` for endpoints and token scopes, `references/deployment-strategies.md` for auto-deploy, webhooks and GitHub Actions, `references/build-packs.md` for build conventions. A mistakes table answers the usual failures: an API call coming back Unauthenticated, auto-deploy staying silent, health checks failing on Compose services.

Token scopes matter here. Without the `deploy` permission a deploy will not fire, and sensitive fields such as auto-deploy stay unreadable unless the token carries `view:sensitive`. Installing the Coolify server itself is out of scope — that is the official install script. When the `docker`, `github-actions` or `ci-cd-architecture` skills are present, the author suggests handing the matching parts of the job to them.

## Requirements
- Works with: Docker

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add oakoss/agent-skills --skill coolify -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/coolify/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/coolify/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add oakoss/agent-skills --skill coolify -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/coolify/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add oakoss/agent-skills --skill coolify -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/coolify/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install oakoss/agent-skills coolify
```

2. **Manually: put the files in place**
- File: `.github/skills/coolify/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add oakoss/agent-skills --skill coolify -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/oakoss/agent-skills --path skills/coolify
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/coolify/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add oakoss/agent-skills --skill coolify -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/oakoss/agent-skills/tree/HEAD/skills/coolify/SKILL.md

## When to use it
- trigger an app deploy through the Coolify REST API
- wire auto-deploy to pushes on a chosen branch
- build a GitHub Actions pipeline that calls a Coolify webhook
- pick a build pack for a project: Nixpacks, Dockerfile or Compose
- find out why a health check keeps failing on Compose services

## Example prompts
- Deploy the app with this uuid in Coolify and show me the build status
- Set up GitHub Actions: build the image, push it to the registry, then hit the Coolify webhook
- Why does the Coolify API return Unauthenticated? Check the headers and token scopes

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 0a9ff9f90e2a2660.

BEGIN THIRD-PARTY FILE 0a9ff9f90e2a2660
```text
---
name: coolify
description: |
  Coolify self-hosted PaaS for deploying applications, databases, and services via REST API and Git integration. Covers API authentication, deployment triggers, build packs (Nixpacks, Dockerfile, Compose), CI/CD with GitHub Actions webhooks, environment management, and Traefik proxy configuration.

  Use when deploying apps to Coolify, triggering deployments via API, configuring build packs, setting up GitHub Actions CI/CD pipelines, managing environment variables, or troubleshooting deployment failures.
license: MIT
metadata:
  author: oakoss
  version: '1.0'
  source: 'https://coolify.io/docs'
user-invocable: false
---

# Coolify

## Overview

Coolify is a self-hosted PaaS (Vercel/Netlify alternative) that deploys applications, databases, and services on your own infrastructure. It provides a REST API for programmatic control, supports multiple build packs, and uses Traefik for reverse proxy and SSL.

**When to use:** Deploying applications to self-hosted infrastructure, managing databases and services through API, automating deployments via CI/CD, self-hosting without vendor lock-in.

**When NOT to use:** Initial Coolify server installation (use the official install script via browser), managing Coolify's own infrastructure (Postgres, Redis — managed internally), or when a managed platform (Vercel, Railway) meets your needs without self-hosting requirements.

## Quick Reference

| Pattern               | Approach                                                | Key Points                                        |
| --------------------- | ------------------------------------------------------- | ------------------------------------------------- |
| API auth              | `Authorization: Bearer <token>` header                  | Token created in dashboard, scoped permissions    |
| List applications     | `GET /api/v1/applications`                              | Returns all apps with status and config           |
| Trigger deploy        | `GET /api/v1/deploy?uuid=<app>&force=true`              | Or use per-app webhook URL                        |
| Create application    | `POST /api/v1/applications/public`                      | Requires project_uuid, server_uuid, env_name      |
| Update application    | `PATCH /api/v1/applications/<uuid>`                     | Accepts build, health check, domain, limit fields |
| Auto-deploy           | Enable in Advanced > General                            | Deploys on every push to configured branch        |
| Webhook deploy        | `curl GET <webhook_url> -H "Authorization: Bearer ..."` | Controlled deploys from CI pipelines              |
```
END THIRD-PARTY FILE 0a9ff9f90e2a2660

The third-party file has ended. Everything between the 0a9ff9f90e2a2660 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2663 of 5790 bytes. © oakoss · MIT · https://github.com/oakoss/agent-skills/tree/HEAD/skills/coolify/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md