---
title: Coolify
description: Monitoring of Coolify applications in Pipedash, with live application state, deployment history, deploys, cancellation and in-app deployment logs.
---

The Coolify plugin (`coolify`) treats each Coolify application as a pipeline. It lists deployments as runs, starts deployments, cancels them and shows deployment logs in the app. Services and databases do not appear as separate pipelines.

## Requirements

API access must be enabled in the Coolify instance settings. The API token is created under Keys & Tokens > API Tokens. Pipedash sends it in the `Authorization: Bearer <token>` header.

The token needs these permissions:

| Permission | Used for |
|---|---|
| `read` | Listing applications and deployments |
| `deploy` | Starting and cancelling deployments |
| `read:sensitive` | Reading deployment logs |

The `deploy` and `read:sensitive` permissions require the token owner to be a team admin or owner.

Credential validation calls `GET /api/v1/version`. Validation does not check each permission. Missing access can still fail discovery, deployment actions or log loading.

## Configuration

<Screenshot src="provider-coolify" variant="dialog" alt="Add provider dialog with Coolify selected, showing Coolify URL, API Token and Skip TLS Verification" caption="Coolify asks for the dashboard URL and an API token." />

| Key | Type | Required | Default | Description |
|---|---|---|---|---|
| `server_url` | Text | Yes | None | URL of your Coolify dashboard (e.g., https://coolify.example.com). API access must be enabled in the instance settings. |
| `token` | Password | Yes | None | Coolify API token, created under Keys & Tokens > API Tokens. Needs read to list applications and deployments and deploy to start or cancel them. Add read:sensitive to see deployment logs; deploy and read:sensitive require the token owner to be a team admin or owner. |
| `insecure` | Boolean | No | `false` | Skip TLS certificate verification (useful for self-signed certificates). |

The dialog labels these fields "Coolify URL", "API Token" and "Skip TLS Verification". The URL field reports "Must be a valid HTTP or HTTPS URL" for an invalid value.

One more key goes in the config table of the TOML file:

- `selected_items`: Comma-separated application UUIDs or application names to monitor.

Pipedash trims each selection and ignores empty entries. Matching uses exact UUIDs or names. Without `selected_items`, all applications stay. An empty `selected_items` string shows no applications.

## Base URL

`server_url` is required. The value is the Coolify dashboard URL without `/api/v1`. Pipedash trims surrounding spaces and trailing slashes, then appends `/api/v1` to API requests. A path prefix stays in place.

The URL must use `http://` or `https://` and include a host. Query strings and fragments are rejected.

Only `insecure = "true"` skips TLS certificate verification in the TOML config. Omission and other values leave verification on.

The plugin uses these endpoints:

| Method | Endpoint | Used for |
|---|---|---|
| `GET` | `/api/v1/version` | Credential validation |
| `GET` | `/api/v1/applications` | Application discovery and pipeline refresh |
| `GET` | `/api/v1/projects` | Project groups |
| `GET` | `/api/v1/projects/{project_uuid}` | Project environments |
| `GET` | `/api/v1/deployments/applications/{application_uuid}?skip={offset}&take={count}` | Latest deployment, history and run lookup |
| `GET` | `/api/v1/deployments/{deployment_uuid}` | Deployment details and logs |
| `POST` | `/api/v1/deploy?uuid={application_uuid}` | Starting a deployment |
| `POST` | `/api/v1/deployments/{deployment_uuid}/cancel` | Cancelling a deployment |

## Pipeline discovery

Pipedash lists applications from `/api/v1/applications`. It loads projects and their environments to group the applications by project name.

<Screenshot src="provider-coolify-picker" variant="dialog" alt="Coolify application picker grouped by project, with state, environment and source descriptions" caption="The picker groups applications by project and shows state, environment and source." />

The picker description starts with the raw application state. It adds the environment when a project placement exists and the source when available. For example:

`State: running:healthy | Environment: production | Source: acme/web@main`

- The project filter matches the project name exactly.
- Applications without a matching project environment have no project group.
- Search matches the application name and description, ignoring case.
- A picker page holds 100 applications by default. Page sizes from 1 to 200 are accepted.
- Pipedash loads and filters the application list before it paginates the picker.

For a `dockerimage` application, the repository value is the image name with the tag when available, and the branch is empty. Other applications show their Git repository, or the server name when no repository exists. A branch appears only with a Git repository.

The pipeline table adds these columns:

| Column | Shows | Visible by default |
|---|---|---|
| State | Live application state, such as Up, Unhealthy, Restarting or Dead | Yes |
| Server | Name of the destination server | Yes |
| Build Pack | Build pack, such as `nixpacks`, `dockerfile` or `dockercompose` | No |
| Domains | The `fqdn` value of the application | No |

Each selected application gets a separate latest-deployment request with `skip=0&take=1`. Its last run is the `created_at` of that deployment. An application without deployments has no last run.

A deployment request that fails for one selected application fails the pipeline refresh. Pipedash does not return a partial list.

## Run history

Each run is one application deployment. Pipedash reads deployment history with `skip` and `take`, in pages of at most 20 deployments. It stops at the requested limit or at a short page. A request with a limit of zero reads no deployments.

The run number is the numeric deployment `id` of Coolify. The internal run ID combines the application UUID and the deployment UUID as `{application_uuid}__{deployment_uuid}`.

The run table uses these columns:

| Column | Shows | Visible by default |
|---|---|---|
| Run | Numeric deployment ID | Yes |
| Status | Deployment status mapped to a Pipedash status | Yes |
| Source | Pull request, Webhook, Rollback, API or Manual | Yes |
| Started | Deployment `created_at` | Yes |
| Duration | Elapsed seconds for a concluded deployment | Yes |
| Commit | Commit hash, except an empty value or `HEAD` | No |

The plugin supplies no branch, actor or inputs for deployment runs. The conditional Branch and Actor columns therefore have no values.

Source uses this order: a positive `pull_request_id`, then `is_webhook`, then `rollback`, then `is_api`. A deployment without those flags reads "Manual".

Run details look up the numeric deployment ID in the application history, in pages of 20. The lookup stops at a short page or at a page that contains older IDs.

A concluded deployment uses `finished_at`, or `updated_at` when `finished_at` is absent. Only `finished`, `failed` and `cancelled-by-user` conclude a run. The duration cannot be negative.

The run link opens `server_url` followed by the `deployment_url` of Coolify. Without a deployment URL, it opens the dashboard URL.

Coolify supplies a live resource label without an explanation message. The run-history header therefore shows no resource-state block. The application state appears on the dashboard, while each history row keeps its deployment status.

## Trigger parameters

Triggering a pipeline deploys the application with `POST /api/v1/deploy?uuid={application_uuid}`.

The plugin has no trigger parameters. It does not send `force`, `instant`, a branch, a tag or other input values.

The response must contain a non-empty deployment UUID in its first deployment entry. Pipedash reads the queued deployment to obtain its numeric run number. If that read fails, the trigger still succeeds without a run number.

## Cancel

Cancel is supported. Pipedash resolves the run number to a deployment UUID and posts to `/api/v1/deployments/{deployment_uuid}/cancel`.

Cancel is offered for pending and running deployments. Force cancel is not supported. Coolify can reject a cancellation that is no longer allowed.

## Run logs

The Logs tab shows deployment logs from `/api/v1/deployments/{deployment_uuid}`. These are deployment logs, not application runtime logs. See [Run logs](/docs/features/run-logs).

<Screenshot src="run-logs-coolify" alt="Coolify deployment logs with one Deployment job, command lines and deployment output" caption="Coolify exposes one Deployment job. New output appears while the deployment runs." />

- The log tree contains one job named "Deployment", with the node ID `deployment`.
- A `queued` deployment has pending logs. An `in_progress` deployment has partial logs. Other statuses mark the log ready.
- Pipedash parses the `logs` field as a JSON array and sorts the entries by `order`.
- A command prints once for each distinct command and batch pair.
- Hidden output is debug output. Other `stderr` output is error output. Remaining output is plain text.
- The dialect uses `. ` for plain output, `$ ` for commands, `! ` for errors and `~ ` for debug output.
- The dialect supplies no timestamps or groups. It does not infer errors from text.
- Each read fetches the deployment detail again and renders the complete log. This is snapshot polling, not an upstream log stream.
- The resume cursor records the rendered length and a hash of the rendered prefix. An unchanged prefix appends only the new bytes. A changed prefix or an invalid cursor reloads the log.
- Pipedash writes the rendered output in chunks of up to 64 KiB.

A missing `logs` field means the token cannot read sensitive data. The error message is `Coolify hides deployment logs from this API token. Give the token the read:sensitive permission to see them`.

A `null` log value is empty output, not a permission error. Invalid log JSON fails with `Failed to parse Coolify deployment logs: <parse error>`.

## Status page

The plugin has no `status_page_url` field and supplies no status page source. It also supplies no instance component-health checks.

The common connection checks still apply. Two consecutive network failures or timeouts report `Can't reach <provider>`. Two consecutive server errors report `<provider> is returning server errors`. A rate limit reports `Rate limited by <provider>`. See [Provider health](/docs/features/provider-health).

## Capabilities and permissions

The plugin declares trigger, cancel, run logs and HTTP proxy support. It does not declare force cancel, single sign-on, asynchronous trigger handling or retained run history.

The plugin publishes no permission-check matrix and no feature-specific permission checks. Credential validation confirms that the version endpoint responds. It does not prove that the token can deploy or read sensitive logs.

## Errors

These are the message texts of the plugin. The displayed error can also include an error category.

| Condition | Message |
|---|---|
| Missing or blank dashboard URL | `Missing server_url in config` |
| Missing or blank token | `Missing token in config` |
| Malformed URL | `Invalid Coolify URL: <parse error>` |
| URL without an HTTP or HTTPS scheme and host | `Coolify URL must be an HTTP or HTTPS URL with a host` |
| URL with a query or fragment | `Invalid Coolify URL: remove the query or fragment` |
| Empty application ID | `Invalid pipeline ID format: ` |
| Deployment ID not found | `Deployment <id> not found for application <application_uuid>` |
| Deploy response without a queued deployment UUID | `Coolify did not queue a deployment of application <application_uuid>: <reason>` |
| Deploy response without a reason | `Coolify did not queue a deployment of application <application_uuid>: no reason given` |
| Logs hidden from the token | `Coolify hides deployment logs from this API token. Give the token the read:sensitive permission to see them` |
| Invalid log JSON | `Failed to parse Coolify deployment logs: <parse error>` |
| Invalid log node | `Invalid log node ID: <node_id>` |

HTTP failures include the status code, request URL and a preview of the response body. Authentication failures, permission failures, missing resources, rate limits and server errors use the common provider error handling.

## TOML example

```toml
[providers.coolify-prod]
name = "Coolify Prod"
type = "coolify"
token = "${COOLIFY_API_TOKEN}"
refresh_interval = 30

[providers.coolify-prod.config]
server_url = "https://coolify.example.com"
insecure = "false"
selected_items = "web,api"
```

`web` and `api` are example application names. Application UUIDs also work.

## Status mapping

<Screenshot src="provider-coolify-state" alt="Coolify applications with Up, Unhealthy, Restarting and Dead states, plus a failed deployment on a healthy application" caption="Application health supplies the status after a finished deployment. Other deployment statuses take priority." />

Pipedash splits the application status at the first colon into state and health. The live mapping applies when no deployment exists or the latest deployment is `finished`.

| Pipedash status | Coolify application state | State label |
|---|---|---|
| `degraded` | `running:unhealthy` | Unhealthy |
| `success` | `running` with any other health value, or no health value | Up |
| `degraded` | `degraded`, with any health value | Degraded |
| `degraded` | `restarting`, with any health value | Restarting |
| `failed` | `dead`, with any health value | Dead |
| `running` | `starting`, with any health value | Starting |
| `cancelled` | `exited`, with any health value | Exited |
| `cancelled` | `paused`, with any health value | Paused |
| `pending` | Any other state, including an empty value | Unknown |

A dead application is Failed, not Degraded.

When the latest deployment is not `finished`, its deployment status overrides the live health. This includes failed and cancelled deployments. Pipedash omits the resource-state label in that case, but the separate State column still shows the live application state.

Deployment runs use this mapping:

| Pipedash status | Coolify deployment status |
|---|---|
| `pending` | `queued`, any other status |
| `running` | `in_progress` |
| `success` | `finished` |
| `failed` | `failed` |
| `cancelled` | `cancelled-by-user` |

Deployment runs are never `skipped`. The newest deployment follows the live application state when it is `finished`: it shows `degraded` while the application maps to `degraded` or `failed` in the table above. Older deployments keep their deployment status.
