Custom Domain for Localhost: Point Your Own Domain (with HTTPS)

To use a custom domain for localhost, run the Ngris agent against your local port with a reserved hostname, point your domain at the Ngris edge with one CNAME record, and let the edge serve HTTPS — ngris http 3000 --url app.yourcompany.com. That maps your own domain to a server running on localhost, with TLS at the edge (issued and renewed for you when you connect your DNS provider), no reverse proxy to configure, and no router port to open. The rest of this guide is the exact four steps, plus how HTTPS works, what plan you need, and the difference between a generated URL and your own domain.

# Install the agent (macOS & Linux)
curl -fsSL https://ngris.com/install.sh | sh

# Point your own domain at localhost:3000 over HTTPS
ngris http 3000 --url app.yourcompany.com

How does this work without opening a port? The Ngris agent makes an outbound connection to the Ngris edge; the edge answers on your public hostname, terminates TLS, and forwards each request back down that same connection to localhost:3000. Nothing ever listens on your network, so there is no inbound firewall hole and no dynamic DNS to babysit. If you are brand new to this, start with exposing localhost to the internet for the basics of the agent and a generated URL, then come back here to put your own domain on top.

Step 1 — Reserve a stable hostname

Run ngris http 3000 with no flags and you get an ephemeral hostname: a public HTTPS URL that lives only while the agent is running. Restart the agent and the hostname changes. That is fine for a quick demo, but it is the wrong foundation for a custom domain, because a CNAME has to point at something stable.

A reserved hostname stays yours across restarts. You claim it with --url, and from then on every session for that endpoint comes up on the same address. This is the target your custom domain will ultimately alias to, so reserve it first.

# ephemeral — changes every run
ngris http 3000

# reserved — stable across restarts
ngris http 3000 --url app.ngris.com

Step 2 — Point a domain to localhost with one CNAME

Now bring your own domain. In the dashboard, add the custom domain — for example app.yourcompany.com — to your reserved endpoint under Domains. The dashboard shows you the CNAME target to create at your DNS provider. This is how you point a domain to localhost: you alias the domain to the Ngris edge, and the edge routes it to the agent's tunnel back to your machine.

# at your DNS provider — one record
app.yourcompany.com.   CNAME   cname.ngris.io.

That single record is the entire DNS change. Requests to app.yourcompany.com resolve to the Ngris edge, the edge matches the hostname to your endpoint, and traffic is forwarded down the agent's outbound connection to localhost:3000. There is nothing to configure on your side of the connection and nothing exposed on your network. Ngris can also manage the DNS records and wildcard for you in auto mode if you hand the dashboard your DNS provider credentials — the full walkthrough is in the custom domains docs.

Step 3 — Automatic HTTPS for your custom domain

How the certificate gets there depends on how you connected the domain. In auto mode — you gave Ngris API credentials for your DNS provider (Cloudflare, Route 53, DigitalOcean, Namecheap, cPanel, or Webmin) — Ngris issues a certificate for the domain and its wildcard over ACME DNS-01 and renews it before it expires: no certbot to run, no ACME challenge to wire up, no renewal cron to babysit. In manual mode — you added the CNAME yourself — Ngris validates the record and you upload your own certificate. Either way, HTTPS terminates at the edge. If you would rather not track expiry at all, Iris, the AI built into Ngris, watches for things like certificates nearing expiry and surfaces a nudge before it becomes a problem.

Because TLS terminates at the edge, your local service can keep speaking plain HTTP on port 3000. The public hostname is HTTPS end to end for anyone hitting app.yourcompany.com, while the agent's tunnel back to your machine handles the transport.

Step 4 — Run the agent on your domain

With the domain added and the CNAME in place, start the agent against your custom domain:

# serve localhost:3000 at your own domain over HTTPS
ngris http 3000 --url app.yourcompany.com

The agent connects out to the edge, the edge answers on https://app.yourcompany.com, and requests land on your local port. Ship code, restart the process, redeploy — the domain and its certificate stay put. This is the whole point of a custom domain for local development: a stable, memorable address you can hand to a teammate, register with a webhook provider, or set as an OAuth redirect URL, that keeps working across restarts.

Use my own domain for localhost vs a generated URL

There are two ways to get a public URL for a local server, and they answer two different needs:

• A generated Ngris URL — ngris http 3000 with no flags prints a public HTTPS URL on an Ngris hostname. It works on every plan, needs no DNS, and is perfect for a quick share or a webhook test. Use this when you just need a link for the next hour.
• Your own domain — ngris http 3000 --url app.yourcompany.com serves your local server on a domain you own. It works on every plan, needs a one-time DNS setup, and gives you a branded, stable address. Use this when the URL needs to look like yours and survive restarts.

So "use my own domain for localhost," "map a domain to a local server," and "point a domain to localhost" all describe the same flow: reserve a hostname, add one CNAME to cname.ngris.io, and run the agent on your domain.

Custom subdomain for localhost

You do not have to give up your apex domain to a local dev server. Most people map a subdomain — app.yourcompany.com, dev.yourcompany.com, staging.yourcompany.com — to localhost and leave the root domain pointing at their real site. Each custom domain on Ngris is served via a wildcard, so once *.yourcompany.com is set up you can spin new endpoint subdomains up without editing DNS again. A localhost custom subdomain is just a CNAME on that name and a matching --url on the agent.

More than a DNS alias — a full edge on your domain

Serving a custom domain through the Ngris edge is not just a DNS alias. The edge is a full gateway, so the same hostname gets more than a tunnel:

• HTTP/2 and HTTP/3 (QUIC) — the edge serves HTTP/1.1, HTTP/2, and HTTP/3 to clients regardless of what your local service speaks.
• A web application firewall — the Coraza-powered WAF attaches as a single traffic-policy rule, detect-by-default and then switch it to block.
• Rate limiting, mTLS, and JWT rules — part of the traffic-policy engine (23 rule types across ordered phases: WAF, JWT, mTLS, rate limits, transforms).
• Identity-aware access — put your domain behind SSO/OIDC (Google, GitHub, Okta) with unified RBAC, no VPN.
• Traffic Inspector and Replay — a live Traffic Inspector filtered by host, path, status, or method, plus request Replay to re-send a captured request to any environment.

All of that binds to the same custom domain you just configured — you attach the rules you want as traffic policies and leave the rest off. If you are coming from another tunnel and want the workflow you already know, the Ngris vs ngrok comparison maps it onto the policy-first edge.

Frequently asked questions

How do I use a custom domain for localhost?

Reserve a stable Ngris hostname with the --url flag, add your domain in the dashboard, create one CNAME record pointing your domain to cname.ngris.io, and run ngris http 3000 --url app.yourcompany.com. The Ngris edge serves HTTPS (issuing the certificate for you in auto mode) and forwards requests to your local port, so your own domain serves whatever is running on localhost.

Is a custom domain free on Ngris?

Yes. Bringing your own domain, like app.yourcompany.com, works on every current plan, including the free Developer plan ($0). What the free plan doesn't include is picking your own name on a shared Ngris domain (a custom subdomain), which is on the Team plan ($10/mo) and Enterprise ($25/mo).

How do I point a domain to localhost?

Create a single CNAME record at your DNS provider that points your domain (for example app.yourcompany.com) at cname.ngris.io, then run the agent with a matching --url. Requests to your domain resolve to the Ngris edge, which forwards them down the agent's outbound tunnel to your local port — nothing is opened on your network.

How do I get HTTPS for a custom domain on localhost?

Connect the domain in auto mode with your DNS provider's API credentials and Ngris issues and renews the TLS certificate over ACME DNS-01, then terminates HTTPS at the edge, so there is no certbot to run and no renewal cron to maintain. If you add the CNAME yourself (manual mode), you upload your own certificate instead. Either way your local service can keep speaking plain HTTP while the public hostname is HTTPS.

Can I map a subdomain to a local server?

Yes. Most setups map a subdomain such as app.yourcompany.com or dev.yourcompany.com to localhost and leave the apex domain on your real site. Each custom domain is served via a wildcard, so once the domain is configured you can create new endpoint subdomains without editing DNS again.

What is the difference between a reserved hostname and a custom domain?

A reserved hostname is a stable Ngris-owned address you claim with --url so your endpoint comes up on the same URL across restarts. A custom domain is your own domain (like app.yourcompany.com) aliased to that endpoint with a CNAME. You reserve the hostname first, then point your domain at it.

curl -fsSL https://ngris.com/install.sh | sh
ngris http 3000 --url app.yourcompany.com

That is the whole procedure: reserve a hostname, add a CNAME to cname.ngris.io, and let the edge handle the certificate. New to the CLI? The Getting Started guide walks through install and your first endpoint, and the custom domains docs cover auto vs manual provisioning. When your app grows past a demo, the same edge can expose and lock down a local API on that domain.