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

FieldMeaning
serverProject control URL.
teamTeam name or ID.
nameSaved name for an unnamed HTTP service; named services use their own key or name.
publisherGroups / publisher_groupsNamed publisher groups with optional description, ready team domain, public, and template.
servicesMap of up to 32 named services.
workloadsNamed provider identities with explicit application grants; see workloads.
publicURL / public_urlDefaults for explicit service public URL blocks only.
inspectionLocal inspection mode and retention.
feedbackEnable the development feedback toolbar.
oauthOpt into a stable project OAuth callback URL while local tunnels run.
webhooksDeclared exact webhook endpoints for local public HTTP services.
aliasesSaved 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.

FieldMeaning
nameOptional common saved-name override for public or private services. Defaults to the service key.
publisherGroup / publisher_groupDeclared publisher group; omitted means built-in local.
protocolhttp (default), tcp, mysql, or postgres.
targetApp 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_urlLocal HTTP public URL; named-group services reject this block.
access{ team: true } declares team access on either path.
target.tlsOptional publisher-to-target TLS, independent of mandatory managed visitor TLS.
httpLocal readiness/open/path settings, or named-group HTTP access and request limits.
inspectionOverrides 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 typeFields and behavior
appDefault for HTTP; no additional fields. An SDK reports the bound listener.
addressRequired address: port or address suitable for the protocol. HTTP accepts HTTP/HTTPS origins; private services can use host:port. The publisher must reach it.
composeRequired service and container port; optional project and project-relative file. Requires matching worktree/Compose labels and a published host TCP port.
dockerRequired 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:

compose.yaml (service fragments)
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 database

Add 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.

FieldMeaning
target.tls: {}Enable verified target TLS using publisher system roots.
caFile / ca_fileAdd a project-relative CA-only PEM bundle to system roots.
serverName / server_nameOverride 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
  },
});
FieldMeaning
domainReady team domain for generated hostnames; otherwise use the team default.
hostnameExact 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.
ephemeralRemove the saved public URL after this tunnel stops.
requirePostQuantum / require_post_quantumRequire hybrid post-quantum key agreement from public HTTPS visitors. Omission preserves the saved setting; explicit false removes it. See security.
limits.httptotal, concurrency, and rate: { count, per, burst } for HTTP work.
limits.trafficConnection 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.