Coolify

@shrug/coolifyv2026.09.04.1· 10d agoMODELS

01README

Manage a Coolify instance over its REST API v1: list/get services (incl. docker_compose_raw) and applications, patch a service's compose, start/stop/restart applications, add persistent (named-volume) application storage, and trigger deploys/restarts. Also creates git-backed docker-compose applications, sets their compose location/domains, manages application env vars (secret-safe, length-only snapshots), toggles the predefined docker network, and introspects the deployment queue + build logs. Reads the instance version as a capability probe, configures an application's HTTP healthcheck, and delivers a file-mount's content via the storages API. Mutations are audited, confirm-gated, and preceded by a live reachability pre-flight check.

02Models1

@shrug/coolifyv2026.09.04.1coolify.ts

fn listServices()

List all services on the Coolify instance.

fn getService(uuid: string)

Fetch one service by uuid and snapshot it, including its docker_compose_raw.

Argument	Type	Required	Description
uuid	string	yes	Service uuid

fn listServers()

List all deploy-target servers on the Coolify instance (host/IP, user, port, reachability).

fn getServer(uuid: string)

Fetch one server by uuid and snapshot it (host/IP, user, port, reachability flags).

Argument	Type	Required	Description
uuid	string	yes	Server uuid

fn listProjects()

List all projects on the Coolify instance (GET /projects). A project's uuid + one of its environments (see getProjectEnvironments) are required to create an application.

fn getProjectEnvironments(uuid: string)

List a project's environments (GET /projects/{uuid}/environments) and snapshot each one's name + uuid — createGitComposeApplication needs BOTH the environment name and uuid.

Argument	Type	Required	Description
uuid	string	yes	Project uuid

fn listPrivateKeys()

List deploy/private keys on the instance (GET /security/keys) — metadata ONLY (uuid/name/description/fingerprint). The private key material the API returns is deliberately never persisted. Use a key's uuid as privateKeyUuid when creating an app from a private git repo over SSH.

fn listGithubApps()

List configured GitHub-app git sources on the instance (GET /github-apps). An empty result means the instance has no GitHub App configured and deploys only from public/deploy-key git repos. (Coolify v1 has no generic git-source list — only GitHub apps.)

fn updateServer(uuid: string, port?: string, user?: string, name?: string, description?: string)

Repoint/update a server's connection settings (ip, port, user, name, description) via PATCH /servers/{uuid}. Sends instant_validate so Coolify re-tests SSH immediately, then re-fetches the server so the snapshot reflects post-change reachability. At least one mutable field is required. Gated behind confirm:true; records an audit attempt on both paths.

Argument	Type	Required	Description
uuid	string	yes	Server uuid to update
port?	string	no	New SSH port
user?	string	no	New SSH user
name?	string	no	New display name
description?	string	no	New description

fn updateServiceCompose(uuid: string)

Replace a service's docker_compose_raw (base64-encoded on the wire) via PATCH. Gated behind confirm:true. Records an audit attempt on both paths.

Argument	Type	Required	Description
uuid	string	yes	Service uuid

fn deploy(uuid: string)

Trigger a (re)deploy of a service by uuid. Gated behind confirm:true. Records an audit attempt.

Argument	Type	Required	Description
uuid	string	yes	Service uuid to deploy

fn restartService(uuid: string)

Restart a service (optionally pulling latest images). Records an audit attempt.

Argument	Type	Required	Description
uuid	string	yes	Service uuid

fn listApplications()

List all applications on the Coolify instance.

fn getApplication(uuid: string)

Fetch one application by uuid and snapshot it.

Argument	Type	Required	Description
uuid	string	yes	Application uuid

fn controlApplication(uuid: string)

Start, stop, or restart an application by uuid. Gated behind confirm:true for all three actions (one predictable rule, even though `start` is arguably safe). Records an audit attempt on both paths. NOTE: to pick up a freshly built image, use `deploy` — there is no `?latest=` pull-latest param on the application restart endpoint (that exists only for services); `restart` recreates the app from its current image/build without pulling.

Argument	Type	Required	Description
uuid	string	yes	Application uuid

fn createApplicationStorage(uuid: string, name: string)

Add a persistent (named-volume) storage to an application so its data survives redeploys. POST /applications/{uuid}/storages. Gated behind confirm:true; records an audit attempt on both paths. Takes effect on the next deploy.

Argument	Type	Required	Description
uuid	string	yes	Application uuid
name	string	yes	Storage name (label in Coolify)

Resources

services(infinite)— Snapshot of all services on the instance

service(infinite)— Snapshot of one service, including its docker_compose_raw

servers(infinite)— Snapshot of all deploy-target servers on the instance

server(infinite)— Snapshot of one server (host/IP, user, port, reachability flags)

applications(30d)— Snapshot of all applications on the instance

application(infinite)— Snapshot of one application

deployment(infinite)— Record of a triggered deploy

projects(infinite)— Snapshot of all projects on the instance

environments(infinite)— Snapshot of one project's environments (name + uuid)

privateKeys(infinite)— Snapshot of deploy/private keys — metadata only (uuid/name/fingerprint), never key material

githubApps(infinite)— Snapshot of configured GitHub-app git sources (empty = instance deploys only from public/deploy-key git repos)

attempt(infinite)— Audit record of a mutation attempt (request + result/error + timestamp). Written on both success and failure.

03Previous Versions9

2026.08.28.2Aug 28, 2026

2026.08.28.2

Adds a no-op upgrades entry so existing instances repin their typeVersion to the current version. The 2026.08.28.1 release added methods and resource specs but shipped without an upgrades entry, leaving older instances (e.g. still on 2026.07.12.3) unable to auto-migrate their typeVersion. No behavior or schema change — the globalArguments schema (baseUrl + apiToken) is unchanged.

2026.08.28.1Aug 28, 2026

2026.08.28.1

Adds application provisioning, environment-variable management, predefined-network control, and deployment introspection to the @shrug/coolify type. Purely additive — every method and resource spec from 2026.07.12.3 is unchanged.

Added

Applications
- createComposeApplication — create a git-backed docker-compose application (build_pack=dockercompose) from a private GitHub App source.
- setComposeLocation — repoint an app at a different compose file / base directory.
- setComposeDomains — assign public per-compose-service domains (docker_compose_domains).
Environment variables
- listApplicationEnvs — snapshot an app's env inventory. Secret-safe: keys + flags + value length only; plaintext values are never persisted.
- upsertApplicationEnv / upsertApplicationEnvs — idempotent single/bulk create-or-update via the bulk endpoint, confirm-gated, audited with a redacted request/response. New applicationEnvs resource spec.
Networking
- setPredefinedNetwork — toggle an app's connect_to_docker_network so it joins Coolify's shared coolify bridge for cross-app DNS.
Deployments (read-only)
- listDeployments, listApplicationDeployments, getDeployment — the in-progress queue, an app's deploy history, and one deployment's status + build-log tail (including PR preview builds). New deployments and deploymentStatus resource specs.

Security

application.raw is now a sanitized, allowlisted projection of the Coolify application record (SAFE_APP_KEYS / sanitizeApplicationRecord) rather than the verbatim record. Unknown/future and secret-bearing fields (manual_webhook_secret_*, docker_compose_raw, …) are dropped by default — fail-closed. Applies to getApplication and every mutation's audit response.
The env surface never persists plaintext values, including on the failure path: a Coolify error whose response body echoes a submitted value is not folded into the thrown error or the persisted attempt audit.

Changed

ApplicationSchema gains optional connectToDockerNetwork, dockerComposeLocation, and dockerComposeDomains.
The reachable pre-flight check now also gates the six new mutating methods.

Notes for upgraders

If you previously read fields off application.raw beyond the vetted allowlist, they are no longer persisted there — read them from a live getApplication, or add the key to SAFE_APP_KEYS. All curated top-level application fields are unchanged.

2026.07.12.3Jul 13, 2026

Modified 1 models

2026.07.12.2Jul 12, 2026

v2026.07.12.2: getApplication captures the full Coolify application record verbatim (raw) plus curated fields incl. dockerImageTag/buildPack; listApplications summary gains dockerImageTag.

2026.07.12.1Jul 12, 2026

v2026.07.12.1: application surface — listApplications, getApplication, controlApplication (start/stop/restart, confirm-gated, audited). deploy remains the app pull-latest path. Additive; services unchanged.

Modified 1 models

2026.07.11.4Jul 11, 2026

2026.07.11.3Jul 11, 2026

2026.07.11.2Jul 11, 2026

2026.07.11.1Jul 11, 2026

04Stats

100 / 100

Downloads

Archive size

69.4 KB

Has README or module doc2/2earned
README has a code example1/1earned
README is substantive1/1earned
Most symbols documented1/1earned
No slow types (deprecated)1/1earned
Dependencies pass trust audit2/2earned
Has description1/1earned
Platform support declared (or universal)2/2earned
License declared1/1earned
Verified public repository2/2earned

Repository

https://github.com/shrugpw/swamp-coolify

05Platforms

linux · x86_64 linux · aarch64 macOS · x86_64 macOS · aarch64

06Labels

#coolify #deployment #docker-compose #paas