releases.

[ install the client ]

tnl and tnld come from one signed v<version> source tag. A release publishes matching Darwin/Linux arm64 and amd64 archives, a multi-platform ghcr.io/tnldotdev/tnl image, and @tnldotdev/tnl with four platform-specific native npm packages. See GitHub releases for the available versions and notes.

For a project using the CLI or the Next.js/Vite integrations, install the npm launcher at the next dist-tag while releases are prereleases:

pnpm add -D @tnldotdev/tnl@next
pnpm exec tnl version

Use npm install -D @tnldotdev/tnl@next or bun add -d @tnldotdev/tnl@next with those package managers. The npm latest dist-tag currently points to a 0.0.0 bootstrap placeholder; an unqualified @tnldotdev/tnl install does not select the prerelease client. Check npm view @tnldotdev/tnl dist-tags --json before installing: release automation sends prereleases to next and stable releases to latest. The npm package exposes tnl, @tnldotdev/tnl/config, /next, and /vite; it does not install tnld.

For a server, download the appropriate archive from the matching GitHub release (it contains both tnl and tnld) or use the published GHCR image by digest, as in self-hosting. Stable releases are also available through the Homebrew tap. Check tnl version and tnld version: released binaries report their version and source commit.

[ verify a release ]

The release includes checksums.txt, a Sigstore bundle checksums.txt.sigstore.json, archive SPDX SBOMs, and tnld-image-digest.txt. Download all files named in checksums.txt, then verify the signed manifest against the exact tag of the release you downloaded before checking archive digests. From a directory containing the release assets:

TNL_TAG='v0.1.0-rc.30' # replace with the tag of the downloaded release
cosign verify-blob checksums.txt --bundle checksums.txt.sigstore.json \
  --certificate-identity "https://github.com/tnldotdev/tnl/.github/workflows/release.yml@refs/tags/$TNL_TAG" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
shasum -a 256 -c checksums.txt

For Compose, take the ghcr.io/tnldotdev/tnl@sha256:... reference from that same release's tnld-image-digest.txt and replace the placeholder below. Run this in the same shell so TNL_TAG still identifies the release you verified above:

IMAGE='ghcr.io/tnldotdev/tnl@sha256:replace-with-release-digest'
cosign verify "$IMAGE" \
  --certificate-identity "https://github.com/tnldotdev/tnl/.github/workflows/release.yml@refs/tags/$TNL_TAG" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Assign the verified reference to TNL_IMAGE. The tag alone can move; the verified digest pins the image content. The release workflow builds and signs these artifacts; it does not deploy a server.

[ plan a compatible upgrade ]

Use a tnl client and tnld server from the same release when possible; read the release notes before changing either side. OpenAPI /v1 and the tunnel protocol describe contracts, not a promise that any arbitrary old client works with a new server. A control or standalone process requires the exact supported PostgreSQL schema version, so back up PostgreSQL and TNLD_STORAGE_KEY, run the new release's tnld migrate over the direct database URL, and start new serving processes over the pooled URL. Do not keep old control processes running against a newly migrated schema. See operations for the upgrade check sequence.