tnl.dev :: docs

tnld reference.

Commands and configuration for tnld processes.

commands and roles

tnld runs one server process. Configure it with environment variables, tnld serve flags, or a --config YAML/JSON file; serve is the default command. The self-hosting walkthrough includes both canonical Compose files.

CommandPurpose
tnld serveStart the configured role (also the default command).
tnld migrateApply embedded PostgreSQL migrations using only TNLD_DATABASE_DIRECT_URL.
tnld config check --config path/to/tnl.ymlValidate a YAML or JSON process file without starting services; success is silent.
tnld versionPrint version and commit.

TNLD_ROLE / --role accepts standalone (default), control, ingress, or relay. Standalone combines control, ingress, and two logical relay services; its two services do not form separate failure boundaries. Control owns PostgreSQL, certificate issuance, DNS automation, and administration. Ingress accepts visitor TCP connections and forwards each once to a connected relay. Relays accept publisher connections over QUIC or TLS/TCP and carry visitor streams. Split ingress and relay processes require a shared cluster secret; standalone must not be configured with one.

tnld serve --config path/to/tnl.yml loads the tnld section of a versioned .yml, .yaml, or .json configuration file. Explicit flags take precedence over environment variables, which take precedence over file values. tnld migrate does not load serving configuration. See tnld serve --help for serving flags (for example, TNLD_RELAY_ID / --relay-id); TNLD_DATABASE_DIRECT_URL is read only from the environment by migrate.

database and dns

SettingUse
TNLD_DATABASE_URLPooled PostgreSQL URL for control and standalone only; never pass it to ingress or relays.
TNLD_DATABASE_DIRECT_URLDirect PostgreSQL URL read by tnld migrate only.
TNLD_SERVER_DOMAINInfrastructure suffix for control., ingress., and relay hostnames.
TNLD_MANAGED_DOMAINPublic URL namespace domain, independent of the server domain.
TNLD_MANAGED_URL_MODEsimple (default) uses direct built-in administrator URLs and readable member namespaces; generated gives memberships generated labels on the managed domain. Set on control or standalone.
TNLD_ROUTE53_MANAGED_ZONE_IDManaged-domain hosted zone required for publisher DNS-01 issuance. Supply supported TNLD_INGRESS_IPV4_ADDRESSES and/or TNLD_INGRESS_IPV6_ADDRESSES.
TNLD_ROUTE53_SERVER_ZONE_IDServer-domain hosted zone for relay transport certificate DNS-01 issuance.
TNLD_CUSTOM_DOMAINS_ENABLEDAllow teams to add custom domains. Default false; enabling requires managed DNS automation. Existing custom domains remain usable when disabled.
TNLD_MANAGED_DOMAIN_MAX_MEMBER_CHILD_LABELSMaximum DNS labels beneath a member namespace on the managed domain. Default 0 imposes only DNS hostname bounds. Custom domains are not restricted by this setting.

Control and standalone require the exact schema version and baseline identity from the selected release. The updated public URL target constraints require a fresh PostgreSQL baseline with a new identity, not an in-place migration or an import of older state. Coordinate a stop/start of all server roles: stop the old roles, run the matching tnld migrate against a fresh direct connection, then start matching roles. Do not import older client state or publisher credentials. See operations.

The Route 53 zones serve distinct purposes; split Compose requires TNL_SERVER_ZONE_ID and passes it as TNLD_ROUTE53_SERVER_ZONE_ID to control. Custom-domain creation additionally requires TNLD_CUSTOM_DOMAINS_ENABLED=true; DNS automation alone does not enable it.

Publisher certificates require DNS automation. Saved public URL grants receive exact-host DNS-01 plans; namespace-authorized publishers may use narrow wildcards within that scope. Each publisher keeps its own private key. A custom-domain claim also requires TNLD_CUSTOM_DOMAINS_ENABLED=true.

listeners and certificates

The deployment proxy owns public control HTTPS. TNLD_CONTROL_LISTEN defaults to the private HTTP backend 127.0.0.1:8080; TNLD_CONTROL_URL is the normalized external HTTPS origin. TNLD_CONTROL_TRUSTED_PROXIES names trusted peer CIDRs and TNLD_CONTROL_CLIENT_IP_HEADER selects one overwritten X-Forwarded-For or Fly-Client-IP value. HTTPS metadata and the external Host are required. The internal control listener remains TLS on :9443 for split control. Raw ingress and relay TCP/UDP default to :443. Standalone uses separate control HTTP and raw ingress listeners with in-process internal control calls.

Split ingress and relays set TNLD_CONTROL_HOSTNAME (DNS name, no scheme or port) and can use TNLD_PRIVATE_CONTROL_ADDRESS (for example, control:9443) to dial the private control API. Each ingress needs a stable TNLD_INGRESS_ID. Each relay needs TNLD_RELAY_SERVICE_ID, TNLD_RELAY_ID, a public TNLD_RELAY_ADDRESS (hostname and port), and a TNLD_INTERNAL_RELAY_ADDRESS reachable from ingress; TNLD_INTERNAL_RELAY_LISTEN binds the internal forwarding port. Restrict private control 9443 and internal relay 9445 to the server network.

Connectors require two ready relay services, not two ingress addresses. Connectors and publishers verify each relay address using its relay transport certificate. Control binds each prepared pair to the exact relay processes and publisher connections; the publisher verifies current visitor permission before target access. Ingress remains responsible for public endpoint visitors. Control defaults to 30-second ingress and relay leases with 10-second renewals. TNLD_INGRESS_LEASE_DURATION, TNLD_RELAY_LEASE_DURATION, and TNLD_LEASE_RENEWAL_INTERVAL select those timings; renew before either deadline.

TNLD_SERVICE_PORT_RANGES declares managed TCP exposure, defaulting to 20000-20015 and bounded to 256 ports. Direct ingress binds every declared port. When a trusted edge combines ports onto one backend, set TNLD_REQUIRE_PROXY_HEADER=true and TNLD_INGRESS_TRUSTED_PROXIES; the original destination port selects the service before native protocol negotiation. The public mapping must expose exactly the declared inventory without changing service port numbers. Keep visitor PROXY metadata separate from the relay packet transport. Do not terminate visitor TLS at the edge.

Control and standalone require TNLD_ACME_EMAIL, TNLD_ACME_ACCEPT_TERMS=true, and an HTTPS TNLD_ACME_DIRECTORY_URL (default: Let's Encrypt production). TNLD_ACME_PROFILE defaults to tlsserver. Publisher and automatic relay certificates use DNS-01. Public control certificates belong to the deployment proxy. Split control loads a paired TNLD_PRIVATE_CONTROL_TLS_CERTIFICATE_FILE and TNLD_PRIVATE_CONTROL_TLS_PRIVATE_KEY_FILE for internal HTTPS. Relays and standalone use server-domain DNS certificate automation or a paired TNLD_RELAY_TLS_CERTIFICATE_FILE and TNLD_RELAY_TLS_PRIVATE_KEY_FILE override.

select relay quic settings

Set TNLD_RELAY_QUIC_PROFILE on relay or standalone processes:

ValueUse
standardDefault. Use the normal UDP socket behavior and QUIC packet settings.
flyUse Fly's IPv4 UDP path with replies routed through the bound socket.

The daemon selects these deployment settings independently of TNLD_RELAY_UDP_LISTEN. A listener address never selects the profile. For Fly, set both explicitly:

TNLD_RELAY_UDP_LISTEN=fly-global-services:443
TNLD_RELAY_QUIC_PROFILE=fly

The fly profile uses a basic packet wrapper, sets the initial QUIC packet size to 1200 bytes, and disables path MTU discovery. These settings apply to publisher-to-relay QUIC, not visitor TLS. Connectors use relays, not ingress listeners.

authority and secrets

SettingUse
TNLD_STORAGE_KEYRequired unpadded base64url encoding of a 32-byte key; control/standalone encrypt recoverable PostgreSQL secrets with it. TNLD_STORAGE_KEY_PREVIOUS supports re-encryption during rotation.
TNLD_CLUSTER_SECRETHigh-entropy shared secret on split control, ingress, and relays for private API authentication. TNLD_CLUSTER_SECRET_PREVIOUS is accepted only during rotation.
TNLD_WEB_SERVICE_SECRETShared secret for the accounts app's scoped website requests to control. Keep it server-only.
TNLD_EMAIL_URL, TNLD_WEBHOOK_SECRETOptional paired mailer HTTPS origin and separate webhook secret for control's invitation-email delivery queue.
TNLD_GUEST_DEMO_ENABLEDOptional guest tnl publish --demo support (default: false). Guests use a secret demo link, with one active demo, a 72-hour credential, and 20 cumulative minutes ready, including idle time, across runs.
TNLD_OIDC_ISSUER, TNLD_OIDC_CLIENT_ID, TNLD_OIDC_CLIENT_SECRETRequired issuer and server client, with its secret when confidential. Register the external control origin's /v1/auth/device/callback and /v1/browser/callback with authorization-code and PKCE support. TNLD_OIDC_SCOPES includes openid.
TNLD_INITIAL_ADMINISTRATORS, TNLD_INITIAL_TEAM_OWNERS, TNLD_OIDC_ADMISSION_FILEExplicit issuer-subject administrator seeds, team owner seeds, and direct issuer team-admission rules. No first-account administrator rule exists.

Hosted and self-hosted servers use control's built-in authority. Control owns device approval and polling; the configured OIDC server client proves identity through a browser authorization-code flow. Ingress receives a purpose-specific verifier for IP filters; TNLD_STORAGE_KEY stays on control or standalone.

Never supply control-only database, storage, login, website, or DNS-provider settings to an ingress or relay. Keep secrets and the metrics listener private. See operations for readiness, backups, and upgrades.

applied projects and private services

tnl apply uses the public control API to store normalized project revisions, publisher groups, service assignments, and grants in PostgreSQL. Named group replicas pull only their assignments using independent enrolled identities. Neither hosted nor self-hosted tnld provisions those replicas or operates AWS on their behalf; see publisher groups.

Managed services retain their allocated hostname and port across private/public exposure changes, including HTTP. Private access uses authenticated connectors; direct public access reaches the same port through ingress. Publisher-owned visitor TLS and target trust remain separate from relay transport TLS and the internal control API's TLS. See private services for client handling and audit history for its transactional and asynchronous boundaries.