Give a tunnel an address on a domain you own, such as example.com or app.example.com. You add the domain in DNS Manager, point its DNS to Localtonet, then choose the domain when you create the tunnel.
Before you start #
- A domain you own, and access to the place where its nameservers or DNS records are managed (your registrar or DNS provider).
- Balance on your account. Adding a domain in DNS Manager and creating a tunnel with the URL type Custom domain or Custom subdomain both require Balance. See Plans and Balance.
- The Localtonet app connected on the device that runs your service. See Quick start.
Choose how to connect the domain #
Localtonet has to answer the DNS queries for the name your tunnel uses. DNS Manager offers two ways to arrange that.
| Way | What changes | Use it when |
|---|---|---|
| Use Localtonet nameservers | You set ns1.localtonet.com and ns2.localtonet.com as the nameservers of the whole domain at your registrar. All DNS records of the domain are then managed in DNS Manager. | You want to use the root domain (example.com), or you are happy to manage the whole domain's DNS in Localtonet. |
| Keep your current DNS provider | You delegate one subdomain, for example app.example.com, to the Localtonet nameservers with two NS records. Your root domain and other subdomains stay with your current DNS provider. | The domain already serves a website or email and you only need one subdomain for the tunnel. Your DNS provider must support NS delegation of a subdomain. |
A CNAME record is not enough. A CNAME pointing to an autogenerated tunnel hostname or to a Localtonet server name does not replace this setup. Use one of the two ways above.
Steps #
-
Add the domain in DNS Manager #
Open DNS Manager. Under Add domain, enter the name in Domain name, for example
example.comorapp.example.com, and select Add domain. Leave outhttps://, the port and any path. For subdomain delegation, add the exact subdomain you will use with your tunnel.DNS Manager confirms with "Domain added. Connect your DNS, then choose this domain when creating a tunnel in My Tunnels." and opens the Connect your domain guide.
-
Point the DNS to Localtonet #
Do one of the following at your registrar or DNS provider.
Whole domain. Replace the nameservers of the domain with:
Nameserversns1.localtonet.com ns2.localtonet.comCopy any existing website and email records into DNS Manager before you switch nameservers, because after the switch only the records in DNS Manager are answered.
One subdomain. In your current provider's DNS settings, remove the existing CNAME record for the subdomain, then add two NS records. For
app.example.com:Type Name Nameserver NS appns1.localtonet.comNS appns2.localtonet.comSome providers require the full name
app.example.cominstead ofappin the Name field. -
Create the tunnel on the domain #
Open the page of the tunnel type, for example My Tunnels › HTTP, and choose the URL type:
- Custom domain uses the domain exactly as you added it. Select it in Domain.
- Custom subdomain puts a name of your choice in front of a domain. Enter the name in Subdomain and select the domain in Domain.
Fill in the rest of the form as for any tunnel and select Create tunnel. The tunnel types are described in HTTP / HTTPS and the other pages of the Tunnels group.
-
Start the tunnel and open the address #
Allow the DNS changes to propagate, select Start, then visit the address, for example
https://app.example.com. The first request starts certificate and routing setup; allow a short time, then try again.
URL types and domains per tunnel type #
| Tunnel type | URL types | Where your domain is chosen |
|---|---|---|
| HTTP | Random subdomain, Custom subdomain, Custom domain | The Domain list. |
| MCP Gateway | Random subdomain, Custom subdomain, Custom domain | The Domain list. |
| File Server | Random subdomain, Custom subdomain, Custom domain | The Domain list for a custom subdomain. For a custom domain you type the domain you added in DNS Manager. |
| TLS | Random subdomain, Custom subdomain | The Domain list. |
| TCP - UDP | Random subdomain, Custom subdomain | The Domain list. |
| Proxy Server, Rotating Proxy | Random subdomain, Custom subdomain | The Domain list. |
- With Random subdomain and Custom subdomain, the Domain list holds the Localtonet domain and the domains you added in DNS Manager. With Custom domain it holds only your own domains.
- Random subdomain does not need Balance. Custom subdomain needs Balance on every domain in the list, the Localtonet domain included.
- A subdomain name can contain letters, digits and hyphens. Some names are reserved and are refused with "NAME is not allowed."
- One address belongs to one tunnel. To publish several services under one domain, give each service its own subdomain with Custom subdomain.
SSL certificates #
TLS certificates for your domain are issued automatically. You do not upload a certificate and there is nothing to renew.
- The first request to the address starts certificate and routing setup, so the very first visit may not work yet. Allow a short time, then try again.
- CAA records limit which certificate authorities may issue certificates for a domain. Restrictive values can prevent tunnel HTTPS certificates from being issued, so remove or relax a CAA record if the certificate does not arrive.
- To serve a certificate of your own, create a TLS tunnel and set its SSL Mode to My service handles HTTPS. Encrypted traffic then passes straight through to your service, which must present its own certificate for the domain.
DNS records and propagation #
- When a tunnel on your domain starts, Localtonet adds the address records for the tunnel's name to the domain in DNS Manager. You can see them under Records. Do not delete them: deleting an A or AAAA record that belongs to a tunnel also deletes the tunnel, and DNS Manager warns you with "Any tunnels linked to this name will also be deleted."
- DNS changes need time to reach everyone. A saved record does not confirm nameserver setup or propagation, and adding a domain does not verify its nameservers. Nameserver changes usually take 1 to 2 hours and can take up to 48.
- When you move a tunnel to another server, DNS updates may take up to 3 hours.
- Records for other purposes (website, email, verification records) are managed in DNS Manager.
Remove a domain #
Deleting a domain in DNS Manager asks "Delete domain?" and warns that all its subdomains and linked tunnels will also be deleted. Every tunnel whose address is on that domain is stopped and deleted with it. Change the nameservers or remove the NS records at your provider as well, so the domain does not keep pointing to Localtonet.
Troubleshooting #
"Add balance to your account to use this feature." or "You need to purchase balance to use this feature."
DNS Manager and the URL types Custom domain and Custom subdomain need Balance. Add Balance, then try again.
"You must create a Domain from DNS Manager!" and "WARNING! You do not have any Domain!"
You chose Custom domain but have not added a domain yet. Add it in DNS Manager first.
"This domain already exists."
Another account has already added this domain in DNS Manager. If you own the domain, contact support.
"Enter a valid domain name."
Enter only the name, such as example.com or app.example.com, without a protocol, port or path. IP addresses and Localtonet's own domains are not accepted.
"NAME is already used by another tunnel." or "NAME already exists."
Another tunnel already has that address. Delete or change the other tunnel, or choose a different subdomain.
"NAME was not found."
The domain you chose or typed for Custom domain is not in your DNS Manager. Add it there with exactly the same spelling.
The address does not open after I started the tunnel
Check the setup in this order: the domain is in DNS Manager with the exact name the tunnel uses; the nameservers or the two NS records point to ns1.localtonet.com and ns2.localtonet.com; no CNAME record is left for the delegated subdomain at your provider; enough time has passed for propagation. If it still fails, contact support while the tunnel is running, before you select Stop, so its live configuration can be checked.
