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 versionUse 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 | shverify 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.txtFor 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.comAssign 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:
| Path | Checked locally | Still needs checking |
|---|---|---|
| Native workload visiting | TypeScript/Python clients, signed provider tokens, relay traffic, independent instances, rotating-file refresh, retained HTTP streams | Installed packages and live provider runtimes, including idle/freeze/thaw behavior |
| Fetch-only application credentials | Web Crypto/Python proofs against control, exact grants, revocation, streaming, cancellation, cleanup | Deployed HTTP runtimes such as Cloudflare Workers |
| Application publication | Built TypeScript and source Python, Node/ASGI listeners, native publisher traffic, visitor TLS, listener replacement, drain | Real-control publication, service traffic, installed packages, federated recovery and live deployment |
| Workload publication | Local SDK/IPC startup, grants, finite leases, canceled acquisition, cleanup ordering | Federated 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.