tnl.dev :: docs
use your domain.
Use your own domain for public URLs.
managed and custom domains
Use the selected team's ready default domain for public URLs and managed service certificates, or add a custom domain when the server allows it. DNS automation is required even for connector-only service hostnames, whose records resolve to loopback.
The managed domain is controlled by the tnl server. A self-hosted server uses readable names by default; the hosted server opts into generated membership labels on tnl.dev. A custom domain belongs exclusively to one team after DNS authority verification. Personal teams publish directly beneath their custom domain; organization members use their immutable member slug. Choose a member slug you will want in your URLs before creating or joining the organization team. Only a ready domain can be used for new publish runs or selected as default.
With TNLD_MANAGED_DOMAIN=routes.example.com, --name app gives these URLs:
| Selected team and domain | Public URL |
|---|---|
| Explicitly authorized server administrator, managed domain | https://app.routes.example.com |
| Chase's personal team, managed domain | https://app.chase.routes.example.com |
Chase in organization team studio, managed domain | https://app.chase.studio.routes.example.com |
Chase's personal team, custom dev.example.com | https://app.dev.example.com |
Chase in studio, custom studio.example.com | https://app.chase.studio.example.com |
Hosted generated mode, managed tnl.dev | https://app.ecstatic-penguin.tnl.dev |
A custom domain replaces the managed suffix; it does not add to it. The server administrator's direct managed-domain URL and a personal team's direct custom-domain URL belong to that personal team. For organization teams, a member's URL stays inside their namespace on either domain. No account becomes an administrator merely by signing in first.
For a member named chase, the hostname of https://web.chase.studio.example.com breaks down this way:
publicURL.domain (public_url.domain in static files) selects a ready team domain for explicit public service blocks. It does not make private services public. Without a fixed service name, local public services get separate worktree hostnames. See worktree names.
Namespace-authorized sibling URLs can share a narrow wildcard certificate at the smallest authorized parent, such as *.chase.studio.example.com. A nested name like api.preview.chase.studio.example.com needs a different approved plan. Exact saved-URL credentials receive exact-hostname plans. Member namespace apexes remain reserved, and ingress still requires an exact saved public URL mapping. Every plan uses DNS-01 automation; manually pointing names at ingress does not provide a TLS-ALPN fallback.
claim a development domain
Select the team first, then add a lowercase ASCII DNS name without a trailing dot using tnl domain claim. An admin or owner can add one; it may be pending while DNS authority is provisioned. Self-hosted servers disable new custom domains by default. The operator can opt in with TNLD_CUSTOM_DOMAINS_ENABLED=true and Route 53 DNS automation (TNLD_ROUTE53_MANAGED_ZONE_ID and at least one ingress IP address). A disabled server returns HTTP 403 (custom_domains_disabled). Hosted tnl.dev enables custom domains. See self-hosting for setup.
tnl team use studio
tnl domain claim studio.example.com --default
tnl domain status studio.example.comtnl domain claim waits up to about three minutes for the NS delegation records and prints them when available. It does not wait for DNS verification or for the domain to become ready. If records are not yet available, the claim is saved: run tnl domain status studio.example.com later to see the records. Do not add the same domain again to check progress. --default asks to make the domain the team's default once it is ready. A domain overlapping an existing managed or custom domain cannot be added.
delegate dns
Add the exact records reported by tnl domain claim or tnl domain status studio.example.com at your DNS provider. For a custom domain, these are NS delegation records: delegate that domain to the nameservers reported by the server. If the domain is a subdomain such as studio.example.com, add the NS records in the parent example.com zone. Do not substitute an A record pointing at ingress for NS delegation. Check again with tnl domain status studio.example.com after DNS propagates; publish only when the state is ready. The tnl server then manages public URL DNS and certificate challenges beneath that domain.
tnl domain status studio.example.comtnl domain status accepts a domain name or ID available to the selected team and shows its state, ID, default marker, required records, and next step. Use tnl domain list to see all available team domains.
choose a default domain
tnl domain default studio.example.com
tnl domain listdomain default accepts a ready domain name or ID available to the team. New public URLs use it unless explicitly overridden. Managed services also capture a ready domain at creation; named groups can select publisherGroups.NAME.domain (publisher_groups.NAME.domain in static files). Changing the default never renames existing endpoints. Use the explicit publisher namespace operation to change a managed namespace, then refresh native clients with tnl connect.
Only an owner can release a custom domain, and it cannot be the current default. Select another ready domain first; releasing revokes authority for its public URLs.
tnl domain default MANAGED_DOMAIN
tnl domain release studio.example.comuse a namespace or shared hostname
For Chase in organization team studio, tnl publish web --name preview uses https://preview.chase.studio.example.com. The exact --public-url https://preview.studio.example.com is team-shared and requires an admin or owner; --public-url https://studio.example.com can publish the custom domain itself. On a personal team using custom dev.example.com, --name preview uses https://preview.dev.example.com. The exact address must be an HTTPS origin without a port, path, or query. On the managed domain, only the built-in administrator's personal team can publish direct URLs; other members stay in their own namespace. See Teams for roles and Configuration for project defaults.