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 issue the HTTPS certificate — ngris http 3000 --url app.yourcompany.com. That maps your own domain to a server running on localhost, with automatic TLS, no reverse proxy to configure, no router port to open, and no certbot cron job. 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

Once the CNAME resolves, Ngris issues the TLS certificate for your domain and terminates HTTPS at the edge. There is no certbot to run, no ACME challenge to wire up, and no renewal cron to babysit — the edge provisions the certificate and renews it before it expires. That is how you get HTTPS for a custom domain on localhost without touching a certificate authority yourself. 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 is free on the Developer 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. Requires the Team plan, a one-time CNAME, 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 Team-plan 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.
• Static egress IPs — a stable outbound IP that partners can allowlist.
• 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 issues the HTTPS certificate and forwards requests to your local port, so your own domain serves whatever is running on localhost.

Is a custom domain free on Ngris?

No. A custom domain — bringing your own domain like app.yourcompany.com — is a paid feature on the Team plan ($10/mo) and up. The free Developer plan ($0) gives you a public HTTPS URL on a generated Ngris hostname and 5 endpoints with no credit card, but you cannot attach a domain you own until Team.

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?

Ngris issues and renews the TLS certificate for your domain automatically once the CNAME resolves and terminates HTTPS at the edge. There is no certbot to run and no renewal cron to maintain; your local service can keep speaking plain HTTP while the public hostname is HTTPS end to end.

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.