tnl.dev :: docs

releases.

Install and verify tnl release artifacts.

install the client

Install tnl in your project or as a standalone CLI. Each release includes matching macOS/Linux arm64 and amd64 binaries, npm packages, and a server image. See GitHub releases for available versions.

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.

Or install the standalone client with curl:

curl -fsSL https://tnl.dev/install | sh

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.

Keep the TypeScript SDK and its platform-native npm package from the same release. Keep the Python binding and the native binary distributed in its platform wheel together too. Do not substitute an older native binary: the bindings reject invalid connector snapshots instead of using a compatibility fallback.

The shared native telemetry client-state baseline also requires a fresh TNL_STATE_DIR and a new sign-in when upgrading from the older baseline. Do not copy the old client database or publisher credentials into the new directory. The hosted receiver must support the per-record {client, event} format before releasing those clients; the old batch-level metadata format is not translated.

Control and standalone require the exact PostgreSQL schema version and baseline identity from their release. The updated public URL target constraints require a fresh baseline with a new identity; this is not an in-place upgrade or an import path for older databases. Back up PostgreSQL and TNLD_STORAGE_KEY, stop all old server roles, and run the matching tnld migrate against a fresh database using TNLD_DATABASE_DIRECT_URL. Start matching roles, supplying pooled TNLD_DATABASE_URL only to control or standalone. Do not import older client state or publisher credentials. See operations for the coordinated stop/start and traffic checks.

prerelease sdk and platform support

The workload, application-credential, and independent-runtime examples combine released code and pending implementation branches. They are not all available on native main or in published rc.40. Use each feature's matching SDK and server builds to try it; upgrading the package alone does not supply a pending API. The fleet descriptor API also needs its matching fleet-enabled SDK.

Local tests cover parts of these paths. They are not yet a promise that a published package works on every deployment platform:

PathChecked locallyStill needs checking
Native workload visitingTypeScript/Python clients, signed provider tokens, relay traffic, independent instances, rotating-file refresh, retained HTTP streamsInstalled packages and live provider runtimes, including idle/freeze/thaw behavior
Fetch-only application credentialsWeb Crypto/Python proofs against control, exact grants, revocation, streaming, cancellation, cleanupDeployed HTTP runtimes such as Cloudflare Workers
Application publicationBuilt TypeScript and source Python, Node/ASGI listeners, native publisher traffic, visitor TLS, listener replacement, drainReal-control publication, service traffic, installed packages, federated recovery and live deployment
Workload publicationLocal SDK/IPC startup, grants, finite leases, canceled acquisition, cleanup orderingFederated SDK publication traffic and live deployments

The publication traffic checks use signed control responses and endpoint-discovery fixtures. They do not exercise a deployed control service. Provider checks use signed local tokens; real Fly/Google acquisition, Kubernetes projection and key reachability, and GitLab job lifetimes still need live tests.

For a deployed function, check cold starts, reused and concurrent invocations, process/filesystem lifetime, token rotation, expiry, revocation, streaming, and cancellation. Database checks need a real pool across connector replacement. An HTTP response alone does not verify those behaviors.

The Fetch-only SDK supports HTTP visiting. Database connections and publication use the native runtime. SDK namespace allocation and non-HTTP publication remain separate implementation work.