Custom Domains
Serve any tunnel on a domain you own. One CNAME record points it at Localport, and the certificate is issued and renewed for you.
Summary
What is a custom domain?#
A custom domain serves a tunnel on a name you own, such as app.acme.com, in place of its Localport address. Localport obtains the certificate for that name and renews it.
Any tunnel can carry one. An HTTP tunnel answers over HTTPS at your domain. A TCP or TLS tunnel answers at your domain on its own port.
There are two kinds.
- A single domain, such as
app.acme.com, serves one tunnel at exactly that name. - A wildcard domain, such as
*.warehouse.acme.com, serves every name beneath it.
Add your domain#
1. Open dashboard.localport.io and go to Custom Domains.
2. Click Add domain.
3. Type the domain and click Add. Start it with *. for a wildcard.
You get one CNAME record to create at your DNS provider. Localport verifies that record and issues the certificate.
Any member of your team can add a domain. Deleting one is an Admin action.
DNS record#
One CNAME, from your domain to the target shown in the panel.
| Field | Value |
|---|---|
| Type | CNAME |
| Name | your domain, or *.warehouse.acme.com for a wildcard |
| Value | the target from the panel, such as k7m2xq4vb8ta.cd.localport.dev |
There is no A record and no IP address to keep current. The record stays as it is when the tunnel moves to another region.
A change at a DNS provider can take a few minutes to propagate. Verification continues after you close the panel.
Verification and certificate status#
Attach a domain once its DNS is verified and its certificate is issued.
| Status | What it means |
|---|---|
| Verifying DNS | Localport is looking for your CNAME record and has not found it yet. |
| Issuing Certificates | The record resolved. A certificate is being issued. |
| Ready to Attach | Verified, certificate installed. Attach it to a tunnel. |
| Attached | Serving a tunnel. |
| Failed | Issuance did not complete. Check the record, then delete the domain and add it again. |
Certificates come from Let's Encrypt, usually within a minute of verification, and are renewed for you.
Attach a domain to a tunnel#
Attach a domain from the tunnel that will use it, not from the Custom Domains page. Open the tunnel, go to its Settings, pick the domain under Custom Domain, and save. Attaching is an Admin action.
With a single domain, the tunnel answers at that exact name. With a wildcard, you set the name as you attach it. Enter api and the tunnel answers at api.warehouse.acme.com. Leave it blank to keep the tunnel's own Localport label.
A name is one DNS label: lowercase letters, numbers and hyphens, up to 63 characters, no dots.
Your tunnel answers on the new name as soon as you save, and on its Localport address as before. Every rule already on the tunnel covers the new name from the first request.
One domain serves one tunnel at a time. A domain you cannot select is attached to another tunnel, still verifying, or is a single domain on a fleet.
Wildcard domains#
A wildcard domain covers every name one level beneath it. *.warehouse.acme.com answers for api.warehouse.acme.com, staging.warehouse.acme.com and any other label, under one DNS record and one certificate.
On a single tunnel, you set the name when you attach the domain, and you can change it later. Any name under the domain resolves with no change at your DNS provider.
A fleet requires a wildcard. Each device is served at its own name under the domain. A device named camera answers at camera.warehouse.acme.com. A device that connects later is covered by the same record.
A fleet also answers as a whole at the name you set. Every device is reachable there on its own port, so a monitoring system can hold one hostname and address each device by port.
Move or remove a domain#
Set Custom Domain back to None in the tunnel currently holding it and save, then pick it in the other tunnel's settings. The domain stays verified and keeps its certificate.
Detach a domain before deleting it. A domain still serving a tunnel cannot be deleted.
There is no rename. Delete the domain you no longer want and add the new name, which gets its own CNAME target. Add a deleted domain back within a week and it keeps its certificate and its original target, so the record you already created still applies.
Frequently asked questions#
What DNS record do I need for a custom domain?
One CNAME, from your domain to the target shown when you add it, such as k7m2xq4vb8ta.cd.localport.dev. There is no A record and no IP address to keep current. For a wildcard, the record's name is *.warehouse.acme.com.
Do I need to provide my own SSL certificate?
No. A certificate is requested from Let's Encrypt once your DNS is verified, installed for you, and renewed while the domain is yours. There is nothing to upload and nothing to rotate.
Why does my domain still say "Verifying DNS"?
The CNAME record has not resolved yet. Confirm the record's name and value match the panel exactly, then allow a few minutes for your provider to propagate the change. Localport keeps re-checking on its own.
Can one domain serve several tunnels?
A domain serves one tunnel at a time. A wildcard domain covers every subdomain beneath it, so one wildcard attached to a fleet serves an entire fleet of devices, each on its own name.
Can I use a root domain like acme.com?
Yes, if your DNS provider supports CNAME-style records at the apex, often called CNAME flattening, ALIAS or ANAME. A provider without it cannot point a root domain at a hostname, so use a subdomain such as app.acme.com.
Does my Localport address stop working once I attach a domain?
No. The tunnel keeps answering on its Localport address as well, so you can move traffic across at your own pace and keep the original address as a fallback.
Can I use a custom domain with a TCP tunnel?
Yes. A TCP or TLS tunnel answers at your domain on the port the tunnel already uses, so a database reachable at example.eu.localport.dev:47266 is also reachable at db.acme.com:47266. Reserve the port in the tunnel's settings and the address stays the same across restarts.
Do I need a wildcard domain for a fleet?
Yes. Each device on a fleet is served at its own name under the domain, and only a wildcard record and a wildcard certificate cover a name before the device using it connects.
How do I move a domain to a different tunnel?
Set Custom Domain back to None in the tunnel currently using it and save, then pick it in the other tunnel's settings. The domain stays verified and keeps its certificate, so there is no second wait.
Can I rename a domain?
No. Delete the one you no longer want and add the new name, which gets its own CNAME target. Detach it from its tunnel first. Adding a domain back within a week restores its certificate and its original target, so the DNS record you already created still applies.
What to read next#
- Fleets. Give every device on a fleet a readable name under one wildcard domain.
- HTTP Tunnels. The tunnel a custom domain most often fronts.
- TCP Tunnels. Custom hosts for databases, game servers and SSH.
- Fanout Tunnels. One team webhook endpoint, on a name that outlives any tunnel.
- Remote Access. Require a client certificate before any request is served.
- CLI. Every command and flag.