Repository navigation
Releases
v0.5.0 — Coolify 4.7.5, safer writes, hardened redaction
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 a...
v0.4.1 — null env values on Coolify 4.7
Verified against Coolify 4.7.5 (two live instances, read-only).
Install from the attached tarball (no git needed, no script runs):
pnpm add -D https://github.com/Coriou/coolify-harness-api/releases/download/v0.4.1/coolify-harness-0.4.1.tgzbun add -d https://github.com/Coriou/coolify-harness-api/releases/download/v0.4.1/coolify-harness-0.4.1.tgzFrom the git tag: bun add -d coolify-harness@github:Coriou/coolify-harness-api#v0.4.1. pnpm refuses this
version from git (ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED: it still has a prepare script, removed in
0.5.0), so with pnpm use the tarball.
Fixed
env list/env diff/env apply/env deletefailed withCoolify response (listEnvs) failed contract validationon Coolify 4.7. Coolify 4.7.5 stores a compose-declared blank
variable (${VAR:-}) with no value and serialisesvalue: null(alsoreal_value: null,
order: null); the read schema only accepted a string or an absent key.valueis now
nullish: a null value reads as''and the row carriesvalue_null: true.- A null value is not a withheld one.
value_hiddenstill means only "the token lacks
read:sensitive" (key absent);env diff/env applyare refused (exit 5) for withheld
values only. - A null row compares equal to an empty desired value:
KEY=in--from-file/--set KEY=
against a null row isunchanged, never an update, and a null row next to an empty-string row
of the same key and scope is not duplicate-key drift. env listprintslen=0 (null)and--jsonrows gainvalue_null(boolean, additive);
value_lengthstaysnullfor withheld values only.
- A null value is not a withheld one.
Added
EnvVar.value_null(optional in the type, always set by the parser).test/fixtures/coolify/v4.7/envs-compose-blank.json: synthetic, 4.7.5-shaped env payload.
Full changelog: v0.4.0...v0.4.1