Repository navigation
Verified against Coolify 4.7.5 (latest stable; two live instances, read-only). Tested range:
4.5.0 – 4.7.5. What changed in Coolify and what the API still cannot do:
docs/coolify-api-coverage.md.
Install (pnpm, or Bun) from the tag, or from the attached tarball when the machine has no git:
pnpm add -D coolify-harness@github:Coriou/coolify-harness-api#v0.5.0
pnpm add -D https://github.com/Coriou/coolify-harness-api/releases/download/v0.5.0/coolify-harness-0.5.0.tgzbun add -d coolify-harness@github:Coriou/coolify-harness-api#v0.5.0
bun add -d https://github.com/Coriou/coolify-harness-api/releases/download/v0.5.0/coolify-harness-0.5.0.tgzNeeds Node.js >= 24 (or Bun). No install script runs.
Upgrading from 0.4.x
No command or flag was removed. The config file is unchanged, with one condition: the instance
url must be the final address (redirects are no longer followed). Check these:
env deleteon Coolify ≥ 4.7 needs a token with thedeleteability (a Coolify change).config doctornow calls Coolify (GET /version) and exits non-zero when a token is set
but rejected (5), the instance cannot be reached or is not a Coolify (1), or no token is set at
all (5).--offlinedoes the local check only; it too exits 5 when the instance or target
named on the command line has no token, and a config whose target points at an unknown
instance is exit 2 (both were exit 0).- The instance
urlmust not redirect (http → https, another host): the request fails and
says so. Put the final URL in the config. deploy --waitcan now end with exit 7 or 8 where it ended with 0: when Coolify skips the
request because that commit is already queued or building, the wait reports on that deployment
instead of returning at once (exit 1 when it cannot tell which one, 5 withoutread).- A plain
deployof an application makes one more request (GET /deployments/{uuid}, at
most 10 s, needsread; without it the check is skipped) and exits 1 withDEPLOY_NOT_QUEUED
when Coolify answered "queued" for a deployment it does not have. env delete --keyrefuses a value holding=or a blank (it is not a name), and a key that
was not found is echoed (text andnotFoundin the JSON) only when it reads like a variable
name: otherwise it is<N-character key>. An unreadable--from-file/--token-filepath
is described the same way when it does not read like a path.- A
deployinterrupted (Ctrl-C, SIGTERM) while it checks or waits exits 130 with its document;
a deploy Coolify did not queue leaves two audit records (the request, then its failure). flag set --redeploywithout--applyno longer deploys, andflag setwithout--set/
--from-fileis a usage error (it was a bare deploy with--redeploy --apply).--previewon a service or a database is exit 2 (it wrote the production row);--take 0and
numbers that are not plain digits are exit 2.- A request now times out after 30 s (it could hang for ever); an unterminated quote in a
--from-fileis exit 2. --from-filestrips the quotes around a value. The firstenv diff --from-fileafter
upgrading lists the keys 0.4 wrote with their quotes as updates; applying fixes them.- Variable names are validated (letters, digits,
_,.): a bad name is exit 2 before any
request, instead of a half-applied write. compose get/compose setneedread:sensitive(they printed an empty document without it),
and so doesenv deleteon a service or a docker-compose application (it reads the compose to
check the key is not referenced;--forceskips the check).database set --public trueon a database that has no port stored is exit 2: add--public-port.compose set,proxy set,database set,env apply--json:confirmedmay benull(the
re-read failed).compose set --from-file/proxy set --from-filerefuse a file without a
top-levelservices:;proxy setrefuses--imagetogether with--from-file(the image was
silently dropped).env diff --json/env apply --json: everyvalueis redacted (they were printed in clear).- If you parse
env apply --json/flag set --json: it is now ONE document (plan +dryRun,
applied,confirmed); it used to be JSON followed by prose. With--redeploythe deploy
acknowledgement is itsdeployfield, not a second document. status/logs --build: the latest deployment is the latest production one (a
pull-request preview on top of the list is skipped).- Library: invalid input raises
InvalidInputError, not aZodError;DEFAULT_LATEST_TAKEis 1.
Network failures areCoolifyNetworkError(not the runtime'sTypeError).applyEnvWrite
returns{ confirmed: false, confirmError }when the re-read fails (it threw).upsertEnvs
refusesis_previewitems on a service or database, and a key with edge whitespace.
waitForDeploymentdefaults changed: the interval grows from 2 s to 5 s, 5 failed polls are
tolerated (was 3), a 4xx is fatal at once, and NaN or negativetimeoutMs/intervalMs/
pollGraceMs/maxConsecutiveErrorsthrow aRangeError;getLatestDeploymentprefers a
production row.
Security
env diff --jsonandenv apply --jsonprinted env values in clear: the desired values
(creates[].value,updates[].value) and, on a key with duplicate rows, the LIVE values
(duplicateKeyDrift[].values). Every value in a plan is now[REDACTED] (N chars). Human
output was never affected.- Redaction bypasses closed. A compose with Windows line endings (CRLF) was not redacted at
all. Also now covered: quoted keys and JSON-style compose, flow mappings, a list at the indent
ofenvironment:, anchors, values spanning lines (block scalars with indicators, a value on the
next line, multi-line quoted scalars), PEM blocks, every value underenvironment:whatever the
key case,command:/entrypoint:/test:and DockerfileRUN/ENV/ARG(flags such as
--requirepass x,-a x,-pSECRET,-u user:pass, header values,export token=…),
requirepass/http_Passwdstyle directives in*_confdocuments, Traefik / Caddy auth
labels, URL passwords after an empty user or containing@,?password=query parameters,
token-only URLs,Bearertokens in Coolify's own format, and everything nested under a
sensitive key. The compose diff redacts each document as a whole. - The API token can no longer reach an error message: a token with a line break is refused
without being quoted, and the runtime's own message is scrubbed. - Redirects are not followed, so a token or a request body never travels to another address.
- A
--setargument without=, a stray argument, an invalid variable name and a malformed
dotenv line are described in errors, never quoted (they are often a secret out of place). - Server error messages are sanitised before they reach stderr or the audit log: anything that
repeats a value or a line of a document sent in the request, URL credentials and tokens. --out FILErefuses to write through a symlink and sets mode 0600 before writing; the audit
log is 0600 (also when an older version created it).- The config refuses an instance URL with credentials and a
tokenEnvthat is not a variable name. - Found by six rounds of adversarial review and covered by
test/redaction-*.test.ts: the
value of a flag on the next list item or continuation line, command lists read one argument
at a time (block and flow style), quoted-pSECRET, header flags,Bearer/Basictokens,
$(…)and backtick substitutions, quoted parts glued by the shell, values nested under a
sensitive key, scalars folded or quoted over several lines, lone CR line breaks, comments,
Dockerfile continuations,-e name=valueand leading shell assignments whatever the case,
buildargs:andx-…environmentblocks, password hashes, webhook URLs, Go DSNs, PEM blocks
with armor headers, pasted between quotes, written out by a command over several lines, as a
JSON array of lines, or of any length. Every scan is linear in the input (several patterns took
seconds to minutes on a hostile 100 kB line). - Redaction also had to stop hiding what a reviewer must see. A PEM marker used to hide
everything up to the next END marker, or the rest of the document: put in a label, a list item,
a flow collection or a comment, it hid a newprivileged: trueor a docker.sock mount from a
compose setdiff. A marker now hides only what a key block is made of — base64 lines and the
armor headers (Proc-Type,DEK-Info,Version,Comment…) — up to its END marker; any
other line is shown, minus the rows of the key it may hold (after a header of an unknown name,
or written oneecho '…' >> keyper row, the long base64 rows are still hidden). An env item
holding a lone quote no longer hides what follows; flow-stylevolumes:
are shown; a service namedtestorenv,set -e,sed -e,- shared_buffers=256MB
arguments and the lines that continue an inlinecommand:stay readable. compose setandproxy setsay how many added or changed lines their diff shows as
[REDACTED](hiddenAddedLineswith--json, aNOTE:line otherwise) and where to read
them: a hidden line is a change nobody reviewed. A lone CR inside a diff line is printed as
\rinstead of overprinting the line.- What the redactor does not claim: it is a heuristic over text, not a parser. A password given
as a bare positional argument (rabbitmqctl add_user u PASS), in free prose, or under a
lower-case key that says nothing (pw,k) is not recognised. Keep secrets in env variables
and reference them ($VAR): references are always shown, values never. - A
--key NAME=valuegiven toenv delete, a value after--token-file,--timeoutor
--public, and an unknown flag that does not read like one are no longer echoed. --out FILEis written to a new 0600 file that then replaces the target (an existing
world-readable file is never written into; another hard link to it is left alone).
Fixed
flag set --redeploywithout--applytriggered a real deploy after its dry-run.- Mutations were retried after a lost answer. A network error or 5xx on
POST …/start,
…/restart, a cancel, a delete or a proxy save was replayed up to 3 times, which could queue a
second deployment. Only reads, the env bulk upsert, the service compose save and 429 answers are
retried now. - A mutation that landed could be reported as failed: an acknowledgement in an unexpected
JSON shape (creating a key on a service or database answers a row without its flags), an
acknowledgement whose body was lost, or a failing confirmation read aftercompose set/
proxy set/database set. The write is now reported as done, "not confirmed" when the
re-read failed, and--restartstill runs. A 2xx that is not JSON at all (a login page) stays
an error. deploy --waitreturned at once (exit 0) when Coolify skipped the request because the same
commit was already queued or building. It now follows that production deployment (preview
deployments are ignored), and fails if it cannot look.deploy --waitgave up after ~6 s of Coolify being unreachable (and again after 20 s once
the circuit breaker opened). It rides out 5 failed polls, does not count polls refused by the
open breaker, treats a 404 as fatal only before the deployment was first seen, stops at once on
other 4xx answers, and never runs past its timeout.- No request timeout: a hung connection hung the command forever. Every attempt has a 30 s
timeout, and aRetry-Afterlonger than 30 s is reported instead of slept through. statusdownloaded 20 build logs (megabytes) to show one deployment: it now asks for one
row, in parallel with the resource.logs --buildreuses that row.statushid any error on the latest deployment behind "(none found)"; it now says why
(latestDeploymentErrorin the JSON).env apply --jsonprinted the plan followed by prose;flag set --json --redeployprinted two
documents;env delete --apply --jsonprinted its document before deleting.--previewon a service or database wrote the production row (Coolify dropsis_preview
there). It is refused before any request.- A locked ("shown once") variable made
env diff/env applyfail with a misleading
"token lacks read:sensitive". Locked rows are listed aslen=lockedand rewritten with a warning. env diffnever came back clean for a key with duplicate rows that all held the desired value,
nor for a single-line value with leading or trailing whitespace (Coolify trims it on save).- An env update on Coolify 4.5 reset
is_literal/is_multiline/ the lock; the flags a row has
set are now sent back with the update. - One invalid variable name in a bulk write left the keys before it written and the command
reported as failed. Names are validated before anything is sent. - A dotenv value in quotes was written to Coolify with its quotes.
--from-filenow removes
matching quotes (also afterKEY =), expands\n/\rin double quotes and reads multi-line
quoted values. Unquoted values are unchanged; an unterminated quote is an error. compose get/compose set/ theenv deletelock check treated a compose Coolify withheld
(noread:sensitive) as an empty one; they now fail with exit 5.database set --public trueflipped the column without opening the port: Coolify needs
is_publicandpublic_portin one request. A port change on an already-public database now
comes with a note (Coolify does not move the proxy).env deletewith several keys said nothing about the rows deleted before a failure.- A failing audit log (read-only checkout, full disk) turned a successful mutation into an error;
a closed pipe (… | head) killed a command mid-mutation with exit 0. - A missing config file, an unreadable
--from-file, and--app --json(a flag swallowed as a
value) are usage/config errors (exit 2) with a clear message, not raw runtime errors. - 403 errors show Coolify's own reason (
Missing required permissions: delete, a token limited to
some projects); network failures say which host and why; contract errors name the failing
fields and types. - pnpm refused to install the package from git (
ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED) and Bun
skipped itspreparescript: the script is gone,dist/is committed and checked in CI. - The
coolify-harnessbin had no shebang: under Bun it was run by the shell. - A full deployment queue was reported as "queued" (exit 0, audit "success"): Coolify answers
POST …/startand…/restartwith a deployment uuid it never created. The deployment is now
read back once (with--waitthe first poll is that read); Coolify's own 404 is
DEPLOY_NOT_QUEUED(exit 1), and a second audit record says the request was not queued. The
bare 404 of a proxy in front of a restarting Coolify is not taken for it. - A failed write read as "nothing happened". A timeout or a dropped connection on a write
says the request may have reached Coolify (outcomeUnknownin the JSON error), a 5xx says it
settles nothing, and acompose set/proxy setthat fails that way reads the document back
and reports what is stored (stored). - A read against a Coolify that accepts the connection and never answers took 122 s (four
attempts); a timed-out read is now tried once more, about a minute at worst. deploy --wait --jsonkilled by SIGTERM (a caller's own timeout) printed nothing; it now ends
like Ctrl-C, with the deployment uuid, exit 130. An interrupt also ends a poll in flight, and
the poll issued at the deadline gets to answer (a deployment that finished in the last seconds
was reported as timed out).- Under Bun, piped output above 64 kB was cut short (a forced exit before the flush).
- A request that is given up on (a wait that ended, Ctrl-C) is aborted instead of left running:
under Bun it kept the process alive for up to a minute after the output. flag set --apply --redeploywith a deploy switch that does not fit the target wrote the
variable and then failed as a usage error; the switches are checked first.- With
--json, an audit record that could not be written put prose on stderr at exit 0; it is
auditErrorin the document. constructor,toStringand__proto__given as a command, target, instance or variable name
were accepted or silently dropped.GET /versionwas read as JSON:4.10became4.1.env apply --applywith nothing to write said "Applied and confirmed"; it says so.
Added
- Coolify 4.7.5 contract:
env deleteasks for the newdeletetoken ability; fixtures in
test/fixtures/coolify/v4.7/;proxy_error_page,is_buildtime/is_runtime/commenton
env writes (library). - Compatibility check:
TESTED_COOLIFY,coolifyCompatibility(),compatibilityWarning().
instance infoandconfig doctorwarn (never fail) when the live Coolify is outside the
tested range;coolify-harness --versionprints the harness version and the range. config doctorchecks every instance that has a token (GET /version): reachability, token,
version.--offline,--json,--instance.- With
--json, a failure is one JSON document on stderr:
{ "error": { "code", "message", "exitCode", … } }, for every non-zero exit;helpand
catalog gen/catalog checkhonour--jsontoo. --token-file FILE: read the API token(s) from a dotenv file (a variable set in the
environment wins; a missing file is not an error), so
"coolify": "coolify-harness --token-file .env"is the whole wrapper script.run()fromcoolify-harness/cli: the whole bin as a function, for a wrapper script of your
own (main()returns an exit code and leaves the process alone).- Release tarballs: every GitHub release carries
coolify-harness-X.Y.Z.tgz, installable by URL
with pnpm or Bun on a machine without git. deploy --dry-run;env diff --fail-on-changes(exit 4 when anything would be written);
--no-logsonstatus,deployments,deployment,deploy --wait(logs_lengthinstead of
the build log).env apply --json:dryRun,applied,confirmed,confirmError.env delete --json:
deleted,confirmed.- Catalog: zod 4 and zod mini schemas (a zod 4 schema used to throw "not a ZodObject"), next
to zod 3, whose output is unchanged.SchemaInput.schemaaccepts any of them. - Config:
coolify-harness.config.{mts,mjs,js}are found automatically; clearer validation errors. waitForDeployment:signal(abort),maxIntervalMs; Ctrl-C duringdeploy --waitprints how
to follow or cancel the deployment (exit 130).- Unknown commands suggest the nearest one.
- Library:
CoolifyNetworkError,CoolifyDeployNotQueuedError,UsageError,
InvalidInputError,EnvChangesPendingError,isLockedRow,findConfigFile,
redactCommandLine,redactUrlCredentials, theEnvVar/EnvWriteItem/EnvWriteResult
types,CoolifyClientDeps.timeoutMs/maxRetryDelayMs,WaitOptions.pollGraceMs,
getDeployment(uuid, { signal }),DeployAck.unrecognised,CoolifyNotFoundError.serverMessage,
CoolifyNetworkError.outcomeUnknown. coolify-harness --version/-v(alone on the line).- Onboarding: README rewritten (install from GitHub with pnpm or Bun, 5-minute quick start, "For
AI agents", troubleshooting, compatibility table),CONTRIBUTING.md,SECURITY.md, issue
template, GitHub releases.
Changed
- zod 4 internally (was zod 3), loaded only while a request is in flight:
helpand usage
errors no longer load it at all. The config is validated without zod. config doctorcontacts Coolify and its exit code reflects what it found (see Upgrading).catalog checkon stale artifacts andcatalog genon a schema that is not an object are
typed errors (exit 3 and exit 2; the second was exit 1).DEFAULT_LATEST_TAKEis 1 (was 20) andgetLatestDeployment()returns the newest production
deployment by creation time.- HTTP defaults: first retry after 250 ms (was 50 ms);
deploy --waitpolls every 2 s growing to
5 s (a fixedintervalMsis honoured as before); 5 consecutive poll failures tolerated (was 3). - Requests send
Accept: application/jsonandUser-Agent: coolify-harness/<version>; redirects
are not followed. - An env update carries
is_literal/is_multiline/is_shown_oncewhen the existing row has
them set (visible in the plan JSON). --take 0is a usage error (Coolify requires at least 1).- Toolchain: pnpm 12, TypeScript 6, vitest 5, ESLint 10 + typescript-eslint, zod 4. CI runs on
Node 24 and 26. Nopreparescript and no registry publishing: releases are git tags plus a
tarball on the GitHub release. docs/coolify-4.5-api-coverage.mdis nowdocs/coolify-api-coverage.md(pinned to 4.7.5).
Full changelog: v0.4.1...v0.5.0