Skip to content

v0.5.0 — Coolify 4.7.5, safer writes, hardened redaction

Latest

Choose a tag to compare

@Coriou Coriou released this 16 Nov 19:19

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.tgz
bun 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.tgz

Needs 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 delete on Coolify ≥ 4.7 needs a token with the delete ability (a Coolify change).
  • config doctor now 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). --offline does 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 url must not redirect (http → https, another host): the request fails and
    says so. Put the final URL in the config.
  • deploy --wait can 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 without read).
  • A plain deploy of an application makes one more request (GET /deployments/{uuid}, at
    most 10 s, needs read; without it the check is skipped) and exits 1 with DEPLOY_NOT_QUEUED
    when Coolify answered "queued" for a deployment it does not have.
  • env delete --key refuses a value holding = or a blank (it is not a name), and a key that
    was not found is echoed (text and notFound in the JSON) only when it reads like a variable
    name: otherwise it is <N-character key>. An unreadable --from-file / --token-file path
    is described the same way when it does not read like a path.
  • A deploy interrupted (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 --redeploy without --apply no longer deploys, and flag set without --set /
    --from-file is a usage error (it was a bare deploy with --redeploy --apply).
  • --preview on a service or a database is exit 2 (it wrote the production row); --take 0 and
    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-file is exit 2.
  • --from-file strips the quotes around a value. The first env diff --from-file after
    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 set need read:sensitive (they printed an empty document without it),
    and so does env delete on a service or a docker-compose application (it reads the compose to
    check the key is not referenced; --force skips the check).
  • database set --public true on a database that has no port stored is exit 2: add --public-port.
  • compose set, proxy set, database set, env apply --json: confirmed may be null (the
    re-read failed). compose set --from-file / proxy set --from-file refuse a file without a
    top-level services:; proxy set refuses --image together with --from-file (the image was
    silently dropped).
  • env diff --json / env apply --json: every value is 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 --redeploy the deploy
    acknowledgement is its deploy field, 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 a ZodError; DEFAULT_LATEST_TAKE is 1.
    Network failures are CoolifyNetworkError (not the runtime's TypeError). applyEnvWrite
    returns { confirmed: false, confirmError } when the re-read fails (it threw). upsertEnvs
    refuses is_preview items on a service or database, and a key with edge whitespace.
    waitForDeployment defaults 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 negative timeoutMs / intervalMs /
    pollGraceMs / maxConsecutiveErrors throw a RangeError; getLatestDeployment prefers a
    production row.

Security

  • env diff --json and env apply --json printed 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
    of environment:, anchors, values spanning lines (block scalars with indicators, a value on the
    next line, multi-line quoted scalars), PEM blocks, every value under environment: whatever the
    key case, command: / entrypoint: / test: and Dockerfile RUN / ENV / ARG (flags such as
    --requirepass x, -a x, -pSECRET, -u user:pass, header values, export token=…),
    requirepass / http_Passwd style directives in *_conf documents, Traefik / Caddy auth
    labels, URL passwords after an empty user or containing @, ?password= query parameters,
    token-only URLs, Bearer tokens 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 --set argument 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 FILE refuses 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 tokenEnv that 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 / Basic tokens,
    $(…) 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=value and leading shell assignments whatever the case,
    build args: and x-…environment blocks, 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 new privileged: true or a docker.sock mount from a
    compose set diff. 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 one echo '…' >> key per row, the long base64 rows are still hidden). An env item
    holding a lone quote no longer hides what follows; flow-style volumes:
    are shown; a service named test or env, set -e, sed -e, - shared_buffers=256MB
    arguments and the lines that continue an inline command: stay readable.
  • compose set and proxy set say how many added or changed lines their diff shows as
    [REDACTED] (hiddenAddedLines with --json, a NOTE: 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
    \r instead 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=value given to env delete, a value after --token-file, --timeout or
    --public, and an unknown flag that does not read like one are no longer echoed.
  • --out FILE is 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 --redeploy without --apply triggered 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 after compose set /
    proxy set / database set. The write is now reported as done, "not confirmed" when the
    re-read failed, and --restart still runs. A 2xx that is not JSON at all (a login page) stays
    an error.
  • deploy --wait returned 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 --wait gave 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 a Retry-After longer than 30 s is reported instead of slept through.
  • status downloaded 20 build logs (megabytes) to show one deployment: it now asks for one
    row, in parallel with the resource. logs --build reuses that row.
  • status hid any error on the latest deployment behind "(none found)"; it now says why
    (latestDeploymentError in the JSON).
  • env apply --json printed the plan followed by prose; flag set --json --redeploy printed two
    documents; env delete --apply --json printed its document before deleting.
  • --preview on a service or database wrote the production row (Coolify drops is_preview
    there). It is refused before any request.
  • A locked ("shown once") variable made env diff / env apply fail with a misleading
    "token lacks read:sensitive". Locked rows are listed as len=locked and rewritten with a warning.
  • env diff never 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-file now removes
    matching quotes (also after KEY = ), expands \n / \r in double quotes and reads multi-line
    quoted values. Unquoted values are unchanged; an unterminated quote is an error.
  • compose get / compose set / the env delete lock check treated a compose Coolify withheld
    (no read:sensitive) as an empty one; they now fail with exit 5.
  • database set --public true flipped the column without opening the port: Coolify needs
    is_public and public_port in one request. A port change on an already-public database now
    comes with a note (Coolify does not move the proxy).
  • env delete with 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 its prepare script: the script is gone, dist/ is committed and checked in CI.
  • The coolify-harness bin 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 …/start and …/restart with a deployment uuid it never created. The deployment is now
    read back once (with --wait the 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 (outcomeUnknown in the JSON error), a 5xx says it
    settles nothing, and a compose set / proxy set that 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 --json killed 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 --redeploy with 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
    auditError in the document.
  • constructor, toString and __proto__ given as a command, target, instance or variable name
    were accepted or silently dropped.
  • GET /version was read as JSON: 4.10 became 4.1.
  • env apply --apply with nothing to write said "Applied and confirmed"; it says so.

Added

  • Coolify 4.7.5 contract: env delete asks for the new delete token ability; fixtures in
    test/fixtures/coolify/v4.7/; proxy_error_page, is_buildtime / is_runtime / comment on
    env writes (library).
  • Compatibility check: TESTED_COOLIFY, coolifyCompatibility(), compatibilityWarning().
    instance info and config doctor warn (never fail) when the live Coolify is outside the
    tested range; coolify-harness --version prints the harness version and the range.
  • config doctor checks 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; help and
    catalog gen / catalog check honour --json too.
  • --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() from coolify-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-logs on status, deployments, deployment, deploy --wait (logs_length instead 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.schema accepts any of them.
  • Config: coolify-harness.config.{mts,mjs,js} are found automatically; clearer validation errors.
  • waitForDeployment: signal (abort), maxIntervalMs; Ctrl-C during deploy --wait prints 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, the EnvVar / 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: help and usage
    errors no longer load it at all. The config is validated without zod.
  • config doctor contacts Coolify and its exit code reflects what it found (see Upgrading).
  • catalog check on stale artifacts and catalog gen on a schema that is not an object are
    typed errors (exit 3 and exit 2; the second was exit 1).
  • DEFAULT_LATEST_TAKE is 1 (was 20) and getLatestDeployment() returns the newest production
    deployment by creation time.
  • HTTP defaults: first retry after 250 ms (was 50 ms); deploy --wait polls every 2 s growing to
    5 s (a fixed intervalMs is honoured as before); 5 consecutive poll failures tolerated (was 3).
  • Requests send Accept: application/json and User-Agent: coolify-harness/<version>; redirects
    are not followed.
  • An env update carries is_literal / is_multiline / is_shown_once when the existing row has
    them set (visible in the plan JSON).
  • --take 0 is 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. No prepare script and no registry publishing: releases are git tags plus a
    tarball on the GitHub release.
  • docs/coolify-4.5-api-coverage.md is now docs/coolify-api-coverage.md (pinned to 4.7.5).

Full changelog: v0.4.1...v0.5.0