Private betaRequest early access →

Sign in

Downloading releases

Self-hosted installs fetch each release as a signed offline bundle from Zynth's object storage, over a licence-gated, credential-authenticated route. This page covers the download itself; verifying and installing the bundle is Versioning & upgrades.

Your distribution credential

Your Zynth contact issues you a distribution credential — a secret string beginning zdc_, tied to your licence. It is shown to you once; store it in your secret manager (it authenticates every release download, so treat it like a password). One credential is typically issued per install; ask for another if you run more.

Downloading a version

Present the credential as a bearer token to the download endpoint. The response is a 302 redirect to a short-lived, pre-signed storage URL — follow it to get the bytes:

Shell
curl -L -H "Authorization: Bearer $ZYNTH_DISTRIBUTION_CREDENTIAL" \
  https://auth.zynthmedia.com/api/v1/distribution/releases/v1.4.0 \
  -o zynth-auth-v1.4.0-offline.tar.gz
  • The pre-signed URL is valid for a few minutes — long enough to start the transfer, and an in-flight download is not interrupted when it expires. Start the download promptly.
  • The URL is a bearer capability for its lifetime; your tooling should not log it.

What you can download

You can download every release published while your maintenance term was active — forever, even after the term lapses. What a lapsed term stops is access to releases published after it ended. This is deliberate: you are entitled to the software you paid for, permanently; a renewal buys the window of newer releases. Your credential's own expiry is a second, independent bound — if it lapses or is revoked, ask for a new one.

When a download is refused

Every refusal is a plain 404 Not Found, on purpose — the endpoint never distinguishes "unknown credential" from "lapsed contract", so a wrong or guessed credential learns nothing. A 404 means one of:

  • the credential is wrong, expired, or has been revoked;
  • your licence has been revoked;
  • your maintenance term does not cover that release's publication date;
  • that version does not exist or has been withdrawn (yanked).

If you believe you are entitled to a release and still get a 404, contact your Zynth representative with the version and your install ID — they can see, from their side, exactly which condition applied.

A 503 (rather than 404) means downloads are temporarily unavailable on Zynth's side — not a problem with your credential. Retry shortly.

Always verify before you install

The bundle carries a cosign signature and SBOM for every image, so you can verify it is authentic and untampered fully offline, before anything runs. You need one file from a machine you trust first: the Sigstore trust root (see Air-gapped verification below).

Shell
tar -xzf zynth-auth-v1.4.0-offline.tar.gz && cd zynth-auth-v1.4.0-offline
export ZYNTH_TRUSTED_ROOT=/path/to/trusted_root.json
./scripts/zynth-verify.sh --bundle . --verify-only

On a machine that can reach the registry, ./scripts/zynth-verify.sh v1.4.0 --verify-only checks the published images directly instead, and needs no trust-root file.

The download's own integrity is the per-image signatures verified here — not the transport. Only install a bundle that verifies.

From v0.43.0, every image also carries two signed attestations, and zynth-verify.sh requires both:

  • SLSA build provenance (SLSA v1, Build Level 2): which workflow built the image, from which source commit.
  • An SPDX SBOM: every package in the image.

The attestations are signed by the same release identity as the image and verify offline the same way. Each image was also scanned for known vulnerabilities before it was signed: a fixable Critical or High finding stops the image from being signed at all, unless Zynth has recorded a dated, reasoned exception for it (for example, a finding in code the product never runs), which expires and is re-reviewed. The SBOM files in the bundle's sbom/ directory are the signed SBOMs themselves, so what you read is what was attested. Releases before v0.43.0 carry signatures only; zynth-verify.sh says so and verifies the signatures.

Verifying offline needs cosign v3.1.2 or newer. Bundles from v0.43.0 on are written by cosign v3.1.2, and an older cosign cannot read them. It would wrongly report the images as unsigned, so zynth-verify.sh --bundle checks your cosign version first and stops with an upgrade message. Verifying against the registry works from cosign v3.0.6.

Air-gapped verification needs a Sigstore trust root that you bring. cosign otherwise downloads it live, which a machine with no network can't do. The bundle deliberately does not include one: a trust root supplied by the thing being verified proves nothing, because a tampered bundle could carry a forged one. Once, on any machine with internet access:

Shell
cosign initialize

Then copy ~/.sigstore/root/tuf-repo-cdn.sigstore.dev/targets/trusted_root.json to the air-gapped machine and export ZYNTH_TRUSTED_ROOT=/path/to/trusted_root.json (or place it at that same path in the home directory of the user who runs the verification). zynth-verify.sh --bundle, and zynth-upgrade --bundle, which uses it, refuse to run without it and say exactly this. Refresh the file occasionally, because Sigstore rotates keys. See Versioning & upgrades for the install and patch-upgrade flow.

Checking the archive before you unpack it

Each bundle ships with a .sha256 alongside it. Keep the two files together and run:

Shell
sha256sum -c zynth-auth-v1.4.0-offline.tar.gz.sha256   # macOS: shasum -a 256 -c …

This catches a truncated or corrupted download; it is not a substitute for the signature check above, which is what proves authenticity. A checksum tells you the bytes arrived intact — only the cosign verification tells you they came from Zynth.

Bundles published before v0.24.0 recorded a dist/ build path inside the .sha256, so this command reports No such file or directory … FAILED even for a perfectly good archive. The bundle is fine — compare the digests directly instead:

Shell
awk '{print $1}' zynth-auth-v1.4.0-offline.tar.gz.sha256
sha256sum zynth-auth-v1.4.0-offline.tar.gz

Upgrading from a bundle (air-gapped)

If your install has no outbound network to our registry, upgrade straight from the extracted bundle — no registry contact at all:

Shell
zynth-upgrade --bundle ./zynth-auth-v1.4.0-offline

It needs the same Sigstore trust root as offline verification (see Air-gapped verification above). It verifies the bundle's images offline against the release signature, loads them into your Docker host, checks your licence and configuration, snapshots the database, deploys, smoke-tests, and auto-rolls-back if the smoke test fails — the same safe sequence as a connected patch, sourced entirely from the bundle. As with the connected path, it applies patches within your current minor only; a minor or major upgrade goes through the gated runbook.