Custom Domains

How a custom domain works#

Every tunnel already answers on a Localport address. A custom domain gives the same tunnel a second name, one that belongs to you, and Localport handles everything behind it.

Two kinds are supported, and you choose per domain.

• A single domain, like app.acme.com, serves one tunnel under exactly that name.
• A wildcard domain, like *.warehouse.acme.com, serves every name beneath it, so one domain can carry many at once.

It works for any tunnel, not only web apps. HTTP tunnels are served over HTTPS, TCP and TLS tunnels answer at your domain on their own port, and a mesh puts every device in a fleet under one name.

Localport issues and renews the SSL certificate for your domain. Once the domain is verified, a publicly trusted certificate is issued and installed for you, then renewed ahead of every expiry for as long as the domain is attached. There is nothing to buy, nothing to upload, and no renewal to remember.

The setup is one DNS record. When you add a domain, Localport mints a unique target for it and asks you to point your domain at that target with a CNAME. Once that record resolves, the domain is verified, a certificate is issued, and the domain can be attached to a tunnel.

To follow along you need a Localport account, a domain you control, and access to its DNS records.

Step 1: Add the domain#

Open dashboard.localport.io, go to Domains, and click New. Type the domain you want to use and press Add.

Localport generates a unique CNAME target for that domain and shows you the record to create. The domain then moves through three stages on its own: DNS verification, certificate issuance, and ready to attach.

Step 2: Create one CNAME record#

At your DNS provider, create a single record using the two values the panel gives you:

Field	Value
Type	CNAME
Name	your domain (app.acme.com, or *.warehouse.acme.com for a wildcard)
Value	the target shown in the panel, like k7m2xq4vb8ta.cd.localport.dev

That is the whole DNS side. There is no A record to maintain, no IP address to keep current, and nothing to change when your tunnel moves to another region.

Step 3: Your certificate is issued automatically#

Once the record is verified, Localport requests a TLS certificate for your domain and installs it, usually in under a minute. You never generate a key, upload a certificate, or set a renewal reminder. Renewals happen on their own for as long as the domain is yours.

The domain then reads Domain ready and is available to attach. Localport waits for the certificate before offering it, so a domain never goes live in a state where a visitor would meet a security warning.

Step 4: Attach it to a tunnel#

Attaching happens in the tunnel, not on the domains page. Open the tunnel you want the domain to serve, go to its Settings, and pick the domain in the Custom Domain dropdown. Click Save and the domain starts serving.

How it attaches depends on the kind of domain. A single domain goes in as-is, and the tunnel answers at exactly that name. A wildcard can serve any name beneath it, so the control grows a short input where you type the label you want.

The domain is live on that tunnel as soon as you save, and it serves one tunnel at a time, so moving it later means picking it in a different tunnel's settings.

Your Localport address keeps working alongside it. A custom domain is an addition rather than a switch, which means you can move traffic across at your own pace, and every access rule already on the tunnel (IP allowlists, basic auth, mutual TLS) applies to the new name from the first request.

Wildcard domains

An ordinary domain resolves one name. A wildcard resolves every name below it, so the record you create for *.warehouse.acme.com answers for api.warehouse.acme.com, staging.warehouse.acme.com, and any other label, including ones you have not thought of yet. Add a wildcard by putting *. in front of the domain when you create it, and the certificate Localport issues covers the same range.

That combination is what makes a whole class of setups possible.

A single tunnel attached to a wildcard lets you decide the name at attach time rather than at DNS time. Pick the domain in the tunnel's settings and a short input appears beside it, where you type the label you want. Type api and the tunnel is reachable at api.warehouse.acme.com. Change it to staging later and the new name serves straight away, because the DNS record and the certificate already covered both.

A mesh tunnel needs a wildcard for the same reason, taken further. Devices name themselves as they connect, so a camera that joins the fleet this afternoon becomes camera.warehouse.acme.com the moment it does. No record was created for it, and none is needed, because the wildcard was already resolving every name in that range. This is why a mesh accepts wildcard domains only; a single-name domain could serve one device and nothing else.

On a mesh the label input has a second job. It sets the shared host that every device also answers on over its own port, which is convenient for a monitoring system that would rather hold one hostname and tell devices apart by port number. Each device keeps its individual name alongside it.

---

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 (something like k7m2xq4vb8ta.cd.localport.dev). No A record, no IP address, and nothing to update later. 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 automatically once DNS is verified, and renewal is handled for you. There is nothing to upload and nothing to rotate.

Why is my domain still "Not ready"?

Either the CNAME has not resolved yet or the certificate has not been issued. The dashboard shows which of the two is outstanding. DNS is the usual cause, so confirm the record's name and value match the panel exactly, then give your provider a few minutes.

Can one domain serve several tunnels?

A domain attaches to one tunnel at a time. A wildcard domain, though, covers every subdomain, so one wildcard attached to a mesh 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). Providers without it cannot point a root domain at a hostname, so use a subdomain such as app.acme.com instead.

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 rename a domain?

Domains are add-only, so there is no rename. Delete the one you no longer want and add the new name, which gets its own CNAME target. If you re-add a domain you deleted recently, its existing certificate is reused rather than issued again.

How do I move a domain to a different tunnel?

Detach it in the tunnel currently using it (set Custom Domain back to None and save), then pick it in the other tunnel's settings. The domain stays verified and keeps its certificate throughout.

What to read next#

• Mesh Tunnels. Give a whole fleet readable names under one wildcard domain.
• HTTP & HTTPS Tunnels. The tunnel a custom domain most often fronts.
• TCP Tunnels. Custom hosts for databases, game servers, and SSH.
• Locked Tunnels. Require a client certificate before any request is served.
• CLI. Every flag, option, and exit code.