tnl.dev :: docs
frameworks.
Register your app's development listener with tnl.
choose an integration
Start your app normally. Its integration prepares project metadata and registers the actual HTTP listener with a local tnl process. tnl init wires up recognized projects or prints the action needed for custom files. Each public service needs an explicit publicURL block; omission keeps it private.
| App | Listener registration |
|---|---|
| Vite | Add the tnl() plugin. |
| Next.js | Wrap the config in withTnl(). |
| Node or Bun HTTP server | Prepare the service, then register the bound server. |
| Other app | Start it yourself, then use tnl publish. |
api servers
Prepare the selected service before startup, then register the server after binding. Port zero lets the OS select an available port. For example, with Node:
import { createServer } from "node:http";
import { tnl } from "@tnldotdev/tnl";
const prepared = await tnl.prepare({ service: "api" });
const server = createServer((_request, response) => response.end("hello"));
server.listen(0, "127.0.0.1");
const publication = await prepared.register(server);With Bun:
import { tnl } from "@tnldotdev/tnl";
const prepared = await tnl.prepare({ service: "api" });
const server = Bun.serve({
hostname: "127.0.0.1",
port: 0,
fetch: () => new Response("hello"),
});
const publication = await prepared.register(server);Keep your existing server framework: pass its bound server to prepared.register. For Fastify, await app.listen({ port: 0 }), then register app.server. For Bun with Hono, pass app.fetch to Bun.serve. Registration acknowledges a local HTTP listener without waiting for public readiness. Use await publication.wait() for a fresh native readiness check. publication.close() releases registration without stopping the app listener. Named remote groups use address targets instead of app registration. See the development workflow.
publish a temporary app with tnl.publish
Use tnl.publish to give an application-owned Node or Bun HTTP server a temporary public URL. Prepare an authorized HTTP namespace once:
tnl auth login
tnl publisher setup --namespace
tnl publisher current --checkThen publish the server your app owns:
import { createServer } from "node:http";
import { tnl } from "@tnldotdev/tnl";
const server = createServer((_request, response) => response.end("pong"));
server.listen(0, "127.0.0.1");
const tunnel = await tnl.publish(server);
console.log(tunnel.url);tnl.publish resolves when this publish run is routable. It reuses the selected scoped publisher identity; app startup does not create a control login or signing identity. The public URL defaults to restricted visitor access. A request from a permitted visitor checks the app response separately from publication readiness.
Keep the returned handle for the app's lifetime. tunnel.finished() resolves after shutdown and rejects on terminal publication failure. During shutdown, await tunnel.close() to drain the publish run and remove its temporary URL, then close your app's server. Closing the tunnel leaves a supplied listener running; the app owns that listener. The handle also supports asynchronous disposal.
For a different publisher host, provision a namespace credential with tnl publisher provision --namespace --output-file /private/publisher.json from an authorized session. Transfer that private credential file to the host and pass publisherCredentialFile: "/private/publisher.json" and an explicit server to tnl.publish, or select the file with TNL_PUBLISHER_CREDENTIAL_FILE. Its grant permits scoped publication, not team administration.
observe a publication
Configured registrations and standalone publications return the same handle:
const status = await publication.status(); // reads without probing
await publication.wait(); // requests a fresh application readiness check
await publication.wait({ until: "routable" }); // routing only
for await (const event of publication.watch({ after: status.cursor, signal })) {
// save event.cursor to resume exclusively after this event
}Use an AbortSignal to cancel a wait or watch without stopping the publication.
Readiness results are fenced by registration, listener target, run, and readiness
path. Watch uses the native local journal; unrelated changes advance its cursor
without exposing another service's payload. An expired cursor reports
sdk.event_cursor_expired; read status before resuming.
Registering a replacement listener supersedes the old handle. Closing that old handle cannot stop the replacement. SDK-instance cleanup joins its publications before releasing its database clients and native connection owners.
publish a python asgi app
Use tnl.publish as an async context manager. The SDK starts an ASGI listener on
a free port and waits for its public URL to become routable:
import asyncio
import tnl
from myapp import app
async def main():
async with tnl.publish(app) as publication:
print(publication.url)
await publication.wait() # fresh application readiness
await publication.finished() # until shutdown or terminal failure
asyncio.run(main())Prepare a namespace publisher with tnl publisher setup --namespace first, or
pass publisher_credential_file for a provisioned publisher. The runtime does not
enroll an identity or manage grants.
For a configured Uvicorn app, keep its normal development lifecycle:
tnl.run("myapp:app", service="api", port=0, reload=True)The serving worker registers after bind; the reload supervisor does not publish.
If you manage the listener yourself, prepared = await tnl.prepare(service="api")
followed by publication = await prepared.register(target) returns the same
observation handle without waiting for readiness. Close the prepared service at
application shutdown.
Python handles expose status(), wait(until="ready"),
wait(until="routable"), watch(after=cursor), finished(), and close().
Cancelling a wait or watch does not stop the publication. An expired event cursor
reports sdk.event_cursor_expired. A replaced listener's old handle cannot close
the replacement. Leaving tnl.publish drains the native run before stopping its
SDK-owned ASGI listener; failed cleanup can be retried.
own a python runtime instance
Use tnl.create_tnl to pin one directory, server, client state directory, and
optional workload callback without changing process-wide configuration:
async with tnl.create_tnl(
directory="/srv/checkout",
credential=tnl.Workload("job", token=acquire_current_assertion),
) as app:
connection = await app.connect("database")
# pass these settings to your ordinary database driverConstruction does not start native work or reuse an ambient connection handle.
app.client(service, create=..., close=...) shares the existing ordinary client
factory. Each getter selects current access and reuses an exact connection
binding; expiration renewal alone does not replace a client. A callback reads
the current request, not a background refresh context. Use an absolute
token_file instead when native should acquire the assertion from a file.
credential=tnl.Workload("job") uses the generated manifest's native acquisition
source. The former top-level workload option is not accepted.
The global configure_workload API is removed; put callbacks and token files on
the instance's credential instead.
Instances also own await app.prepare(service="api") and
async with app.publish(asgi_app) publications. A selected workload cannot fall
back to a personal publisher. Closing the instance with aclose(), or leaving
its async context, fences new work, joins pending setup, drains publications,
closes clients, then joins its native owners. Failed cleanup can be retried;
sibling instances stay running. Keep each instance on one event loop and create
a new one after a fork. Application-document HTTP access
uses exact resource IDs without native authentication. The same document can
prepare a native application listener.
For SDK-owned listeners, publish an ASGI app
with the same document, or use a
workload credential for native
federation. Python application-document connectors and non-native database
transport remain separate work.
use a service url in your app
When your project configuration explicitly enables public URLs for web and api, tnl generates browser-safe metadata. Read the API URL from the frontend or server:
import { tnl } from "@tnldotdev/tnl";
const apiURL = tnl.services?.api?.url;
const sameOriginAPIURL = tnl.services?.web?.paths?.["/api"]?.url;apiURL uses the API's own public URL. With web.http.paths["/api"] configured, sameOriginAPIURL uses web's public URL and includes the mount path. The browser sends requests to the same hostname as the web app; the API receives the prefix unless the mount sets stripPrefix: true. The hostname's visitor policy applies to the mounted path.
Use the generated .url rather than constructing an origin from .hostname.
Managed HTTP metadata retains its allocated port, for example
https://api.production.shop.example.com:20001; it must not become port 443.
Publisher egress observations belong to manager status, not this browser-safe
metadata. A generated URL still does not prove readiness or authorize a visitor.
App preparation updates runtime metadata. Run tnl generate offline for portable declarations and include .tnl/generated/project.d.ts in TypeScript for typed service names. Track .tnl/generated/; only .tnl/local/project.json holds worktree- and installation-dependent values, so ignore only /.tnl/local/ at the selected project root.
In a monorepo, these paths start at the selected tnl project root, not each service's app directory. For example, an app at apps/web using the repository's project configuration includes ../../.tnl/generated/project.d.ts in its tsconfig.json. Init prints the include action and preserves your TypeScript configuration.
Private services have no public URL to expose in browser metadata. A public URL can be recorded before the service is running; metadata is not readiness and contains no access token. Starting a framework app never applies remote configuration. See project metadata and security.
With project-level oauth: true, tnl.oauth?.hostname and tnl.oauth?.url identify the project's one callback origin across worktrees, including services with another app domain. Without it, tnl.oauth is absent. tnl.webhooks?.payments?.hostname and .url identify a declared endpoint; its URL includes the configured path. These values are browser-safe metadata and can exist before their integration URL publishers become ready. Check tnl status for current readiness. See OAuth callbacks and webhooks.
tnl.aliases?.review?.url identifies a declared alias, and .service names its entry service. The value can exist before the alias is ready; check tnl status for selection and publication. Vite and Next development integrations accept alias hostnames that reach their own entry service or a configured path mount, without adding unrelated aliases to their host allowlists.
tnl.worktree?.label exposes browser-safe project, optional checkout, id, and fullLabel components. Runtime metadata can be absent and needs narrowing. Portable declarations keep these runtime-dependent values broad; the primary checkout has no checkout property. No filesystem root is included. Config factories receive the same label object plus project.relativeDirectory; see factory context.