tnl.dev :: docs
config reference.
Look up project configuration fields, defaults, and precedence.
file discovery and formats
Starting in the current directory, tnl searches upward to the Git worktree root, or stops in the current directory outside Git. It looks for tnl.yml, tnl.yaml, tnl.json, and tnl.config.ts. The nearest directory with a file wins; multiple files there are an error. Root --config PATH selects explicitly ahead of TNL_CONFIG; --no-config skips discovery and conflicts with --config.
Static YAML and JSON require version: 1 and put client settings under tnl. Optional $schema: https://tnl.dev/schema/v1.json supplies the editor schema. A static document may also have tnld process settings; see the tnld reference.
TypeScript exports settings directly through defineConfig from @tnldotdev/tnl/config, without the wrapper. The file must be named tnl.config.ts and requires Node.js 22.18 or newer. A factory receives cwd, env, worktree, and project. Configuration executes on the CLI when loaded; keep it trusted. tnl check validates configuration and prints its selected path. See equivalent examples.
The factory's worktree.label has project, optional checkout, id, and fullLabel: the DNS-safe components actually used after shortening. The primary checkout has no checkout property. project.relativeDirectory is "." at the root or a slash-separated directory such as "apps/api". These values are computed locally without a server call.
Git is optional for configured local publishing. Outside Git, discovery stops in
the current directory and the directory supplies local project identity. tnl apply
requires a Git checkout and supported origin to identify the saved project.
tnl.config.ts can import local TypeScript and installed packages. Local imports use the nearest tsconfig.json, including paths from extended configs. Run tnl check after changing imports or path mappings.
project defaults
| Field | Meaning |
|---|---|
server | Project control URL. |
team | Team name or ID. |
name | Saved name for an unnamed HTTP service; named services use their own key or name. |
publisherGroups / publisher_groups | Named publisher groups with optional description, ready team domain, public, and template. |
services | Map of up to 32 named services. |
workloads | Named provider identities with explicit application grants; see workloads. |
publicURL / public_url | Defaults for explicit service public URL blocks only. |
inspection | Local inspection mode and retention. |
feedback | Enable the development feedback toolbar. |
oauth | Opt into a stable project OAuth callback URL while local tunnels run. |
webhooks | Declared exact webhook endpoints for local public HTTP services. |
aliases | Saved project public URLs assigned to a selected worktree. |
Server and team belong at the project root. There are no dev, publish, directory, or tunnel configuration blocks.
services
Service keys are lowercase DNS labels beginning with a letter, up to 32 characters. Saved service names must be distinct within the configuration.
| Field | Meaning |
|---|---|
name | Optional common saved-name override for public or private services. Defaults to the service key. |
publisherGroup / publisher_group | Declared publisher group; omitted means built-in local. |
protocol | http (default), tcp, mysql, or postgres. |
target | App listener, address, Compose service, or Docker container. |
targetBinding / target_binding | "group" requires an exact per-installation target binding instead of a fixed template target. |
publicURL / public_url | Local HTTP public URL; named-group services reject this block. |
access | { team: true } declares team access on either path. |
target.tls | Optional publisher-to-target TLS, independent of mandatory managed visitor TLS. |
http | Local readiness/open/path settings, or named-group HTTP access and request limits. |
inspection | Overrides project inspection settings. |
publisherGroups.local cannot be declared: local is reserved. Named groups
accept description, domain, public, and template; the last two default to
false. Static YAML/JSON use publisher_groups. Provision each replica with
tnl publisher provision; keep replica counts and infrastructure in your own
deployment configuration. The retired aws block is rejected. See
AWS publishers.
publisherGroups.NAME.template: true registers a reusable definition without
creating a base group or endpoints. tnl publisher create NAME --from TEMPLATE
creates an independent concrete group; later tnl apply updates all derived
groups. Static files use publisher_groups.NAME.template. See
customer installations.
Use targetBinding: "group" on a template service when installations need
different destinations, target TLS trust, or discovery settings. It replaces
target; a binding cannot override a fixed target. The template still owns the
protocol and visitor settings. Required bindings and protocol approvals must be
supplied for every affected group in the same revision-checked configuration
apply. Replacement sets use the human-authorized API, not tnl apply; see
bound-service rollouts.
public: true changes managed endpoint DNS to ingress and keeps its allocated port, including HTTP; it does not remove authentication. Remote groups use reachable address targets or supported AWS discovery. Local services support app, address, Compose, and Docker targets. Named-group HTTP uses its managed endpoint, not a publicURL block. Its optional http block sets restricted access/IP filters through access and request limits through limits. Anonymous access, traffic limits, and incompatible inherited HTTP defaults are rejected. Without that service block, root public URL defaults do not apply. See publisher groups.
ssh and redis are not protocol values. Use tcp for an existing sshd or another opaque TCP service. Non-HTTP protocols cannot have a public URL. Root public URL defaults never opt another service into public HTTPS.
target selection
services: {
web: { publicURL: {} },
api: { target: { type: "address", address: "api.internal:8080" } },
database: {
protocol: "postgres",
target: { type: "address", address: "127.0.0.1:15432" },
},
cache: {
protocol: "tcp",
target: { type: "address", address: "127.0.0.1:16379" },
},
}| Target type | Fields and behavior |
|---|---|
app | Default for HTTP; no additional fields. An SDK reports the bound listener. |
address | Required address: port or address suitable for the protocol. HTTP accepts HTTP/HTTPS origins; private services can use host:port. The publisher must reach it. |
compose | Required service and container port; optional project and project-relative file. Requires matching worktree/Compose labels and a published host TCP port. |
docker | Required exact container and container port. Requires the matching tnl.worktree label and a published host TCP port. |
Compose and Docker select running containers; tnl does not start them. App discovery is HTTP-only. For app targets, start your app normally with its integration. For other local targets, use tnl publish SERVICE. Container ports are 1–65535. Discovery fields from different target types cannot be combined.
For the address targets above, publish the container ports to loopback in your application's Compose file, start it, then publish the configured service:
services:
db:
ports: ["127.0.0.1:15432:5432"]
cache:
ports: ["127.0.0.1:16379:6379"]docker compose up -d db cache
tnl publish databaseAdd those port mappings to your existing services with their images, credentials, and volumes. This recipe uses ordinary address dialing and needs no Docker label or socket access from tnl. Each concurrent worktree needs distinct host ports.
If you select compose or docker discovery instead, the running container must
have tnl.worktree equal to the exact worktree.label.fullLabel for the same
project and client state. Do not guess it from a directory or branch name. Compose
also checks the selected project, service, canonical working directory, exact
single config file, and non-one-off placement; exactly one container must match.
Both target types require a local Unix-socket Docker daemon and one unambiguous
published host TCP binding for the selected container port. An internal container
IP or Compose expose alone is insufficient. Prefer the loopback address recipe
when you do not already manage those labels and placement checks.
publish from docker
Use the prerelease enrolled Compose publisher
for one saved HTTP public URL. Its inputs are immutable TNL_IMAGE, explicit
TNL_SERVER, reachable TNL_TARGET, and one-use TNL_ENROLL_KEY. Persist the
publisher's private identity/certificate state; restart uses that identity, not a
human session. The application listens on its Compose network address. No app SDK
or Docker socket is required. For several applied services, use independently
enrolled publisher group members, not a copied human
client-state directory.
Host-side Compose/Docker target discovery remains separate: publish a loopback port or select an exact running container with the checks described above.
publisher-to-target tls
The optional target.tls block applies to private and public services. It configures
verified TLS from the publisher to the target. Managed visitor TLS is always a
separate handshake ending at the publisher.
| Field | Meaning |
|---|---|
target.tls: {} | Enable verified target TLS using publisher system roots. |
caFile / ca_file | Add a project-relative CA-only PEM bundle to system roots. |
serverName / server_name | Override the target certificate hostname; required when the intended hostname cannot be inferred before apply. |
HTTP address targets use an https:// origin with this block. TCP establishes
direct TLS; PostgreSQL and MySQL negotiate their native SSLRequest handshake
before forwarding login. Applying captures CA bytes and their digest, so group
replicas and installed jobs do not reopen the applying machine's file. Changing
trust requires a new approved revision. Service-level tls, target.tls.mode,
remote CA-bundle URLs, and verification bypasses are not supported. Omitting the
block permits plaintext backend traffic but never disables managed visitor TLS.
See target TLS.
workload policies
Root workloads is a map of provider identities and explicit application grants.
See workloads for provider fields, token sources, grant scopes,
and session duration. Callbacks
belong in runtime code, not configuration functions.
These prerelease declarations need matching SDK/server builds; the pinned rc.40 package and checked-in schema mirror do not supply every pending API. Validate against the selected feature's native source before applying a policy.
public url settings
TypeScript uses publicURL; static files use public_url. Put an explicit block on each local public HTTP service, even when inheriting defaults:
export default defineConfig({
publicURL: { domain: "dev.example.com" },
services: {
web: { publicURL: {} },
api: {}, // private http
},
});| Field | Meaning |
|---|---|
domain | Ready team domain for generated hostnames; otherwise use the team default. |
hostname | Exact hostname or HTTPS origin without port, path, or query. Mutually exclusive with service name. |
access | "restricted" (default), "anonymous", or { mode, ip }. An IP filter adds a source restriction; it does not supply a visitor credential. |
ephemeral | Remove the saved public URL after this tunnel stops. |
requirePostQuantum / require_post_quantum | Require hybrid post-quantum key agreement from public HTTPS visitors. Omission preserves the saved setting; explicit false removes it. See security. |
limits.http | total, concurrency, and rate: { count, per, burst } for HTTP work. |
limits.traffic | Connection and directional byte budgets; see the schema for all fields. |
For public URLs, limits.traffic.connections bounds authorized visitor connections
for one publish run across both relays and every ingress process. The default is 32. Two runs with a limit of 10 each have separate budgets of 10; they do not share
one budget of 10. HTTP/2 requests on one visitor connection use one connection
slot; limits.http.concurrency still limits simultaneous HTTP work separately.
Pending TLS and credential setup has a separate budget: 16 connections per relay,
32 per run, and eight per verified source network across both relays. A source
network is one IPv4 address or IPv6 /64; visitors sharing that network share its
setup allowance. Authorization releases the pending allowance and uses an
authorized connection slot. Closing a connection releases its slot only after
its active work finishes cleanup. Pending setup does not evict authorized
connections.
These hostname/domain, anonymous, ephemeral, and traffic settings describe local
public URLs. Named-group HTTP uses the group's managed endpoint and the narrower
service settings above. name belongs on the service, not inside
publicURL. Leave it unset for separate local worktree hostnames. A fixed local
name or exact hostname may be shared across checkouts. Anonymous local access
removes tnl's visitor-credential requirement; the app still owns its own authentication.
local http settings
http.readiness.path selects a local HTTP readiness path. http.open: true opens a ready public URL. Named remote groups do not support http settings.
mount another service at a path
services: {
web: {
publicURL: {},
http: { paths: { "/api": { service: "api", stripPrefix: true } } },
},
api: {},
}Both services must use the local publisher. The entry service must be public HTTP. The entry hostname's visitor policy applies to the mount. A string value such as "api" preserves the prefix; stripPrefix: true (strip_prefix in static files) removes it. The mounted service does not need its own public URL. Matching uses complete path segments, with the longest matching prefix; /__tnl/ is reserved.
inspection and integrations
inspection.mode is summary (default) or none; retention is a duration from 1m to 720h; maxBytes / max_bytes is a binary size from 1MiB to 1GiB. These are local inspection settings, separate from team audit history.
oauth callback url
Set root oauth: true to publish one project callback origin while participating local public tunnels run. tnl.oauth.url gives the origin; add your auth library's callback path and register that exact redirect URI with the provider. Keep the app base URL on the worktree-specific service URL and use the same redirect URI during code exchange. See OAuth callbacks.
webhook endpoints
Each webhooks.NAME declares a local public HTTP service, exact path, and provider; methods defaults to POST, and sourceIPs / source_ips replaces the server's provider source list. Verify sender signatures in the app. delivery is fanout or selected; Discord, Slack, Twilio, Telegram, and Amazon SNS default to selected, with other event providers defaulting to fanout.
Use tnl webhook use NAME to select a ready receiver or release NAME to release it. With no selected ready receiver, the provider gets 503. Fanout requires every ready receiver to succeed and provider retries may reach all of them again. Applying root OAuth and webhook declarations records desired configuration; local runtime owns their integration URLs, not remote group assignments. See provider setup guides.
aliases
Declare up to 32 aliases at the project root. Each aliases.NAME selects an HTTP entry service, with optional relative name, ready domain, access, or exact publicURL / public_url. An exact public URL is mutually exclusive with name and domain. Alias access defaults to restricted, independently of the entry service; an IP match does not replace a credential.
tnl alias use NAME selects this worktree; release NAME returns it to the primary checkout. Definitions in running worktrees must agree. Selection persists when services stop, without automatically choosing another worktree. Nested names depend on the server/domain policy and need exact DNS and certificates. See switching worktrees.
precedence and validation
An explicit --server / TNL_SERVER wins over the project setting, then the selected server or hosted default applies. --team / TNL_TEAM wins over root team, then the saved selection or personal team applies. Selecting another server skips the configured project team. An explicit access token with a project-selected server requires an explicit server selection.
Public URL defaults merge into explicit service blocks, then command options apply where supported. Static and TypeScript files reject unknown fields and validate the same contract. Run tnl check, then tnl apply to reconcile desired state with control. Starting a local app never applies remote changes.