HTTPS Localhost: mkcert, Self-Signed Certs, and Tunnels

HTTPS localhost matters when local development needs the same secure-context behavior as production. Cookies, OAuth redirects, service workers, WebAuthn, camera APIs, and payment flows can behave when your app runs on plain HTTP.

You have three common choices: use mkcert, create a self-signed certificate, or expose the local server through a tunnel that gives the reviewer an HTTPS URL.

HTTPS localhost options

The right setup depends on who needs access and how long the setup should last.

Google’s web.dev guide recommends mkcert for local HTTPS because it creates a local certificate authority your browser can trust. The mkcert README says the tool creates and installs a local CA, then generates locally trusted certificates for names such as localhost, 127.0.0.1, and custom development hostnames.

That solves the local browser trust problem. It does not by itself give an external reviewer access to your machine.

Method 1: mkcert for trusted localhost certificates

mkcert is the best default when you need HTTPS on your own machine day after day.

On macOS with Homebrew:

brew install mkcert
brew install nss # if you use Firefox
mkcert -install
mkcert localhost 127.0.0.1 ::1

The last command creates a certificate and key. Your dev server still needs to use them.

For a small Node server:

import fs from "node:fs";
import https from "node:https";

const options = {
  key: fs.readFileSync("localhost+2-key.pem"),
  cert: fs.readFileSync("localhost+2.pem"),
};

https.createServer(options, app).listen(3000);

For many framework dev servers, you point the HTTPS config at the generated files. The exact flag changes by tool, so check the framework docs.

Keep one mkcert warning in mind: do not share rootCA-key.pem. The mkcert README and web.dev guide both warn that this private key can let someone create certificates your machine trusts. Team members should install mkcert on their own machines instead of sharing one root CA key.

Method 2: self-signed certificates

Self-signed certificates prove encryption, but browsers do not trust them by default. You can generate one with OpenSSL:

openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout localhost-key.pem \
  -out localhost-cert.pem \
  -days 30 \
  -subj "/CN=localhost"

This can help for quick server tests. It creates friction for browser flows because the browser warns the user. Some APIs, strict cookie flows, or mobile browsers may still fail unless you install trust in the right store.

Use self-signed certificates for throwaway experiments. Use mkcert when you care about local browser trust.

Method 3: tunnel HTTPS for temporary review

A tunnel gives you a public HTTPS URL that forwards to your local HTTP server. You avoid local certificate setup for the reviewer because the public link uses HTTPS.

npm run dev
npx wiremaven-cli 3000 --expires 30m --name https-review

wiremaven creates temporary encrypted public links for local dev servers. Your local machine opens an outbound-only WebSocket connection to the relay. The reviewer receives a browser link. You see viewer joins, request outcomes, failure events, and the session TTL.

This does not replace mkcert for every development need. If your local app itself must run as https://localhost for browser behavior on your machine, use mkcert. If you need to send an HTTPS link to a client or test a provider callback against a local build, a tunnel may be the faster path.

During beta, wiremaven requires no account and supports 15, 30, and 60 minute review windows.

Choosing the right path

Use mkcert when:

• You develop against HTTPS every day.
• Your local browser must trust https://localhost.
• You use custom local hostnames such as app.test.
• Your team can document setup per machine.

Use a tunnel when:

• A reviewer needs an HTTPS browser link.
• You need the link for 15, 30, or 60 minutes.
• You want request and failure signals during the session.
• You do not want the reviewer to install certificates or join a network.

Use self-signed certificates only when browser trust does not matter or when you want to understand the mechanics.

For wiremaven setup, read the docs. For how the relay avoids inbound firewall rules, see how wiremaven works.

Common local HTTPS failures

Check these when HTTPS localhost does not work:

• The certificate does not include the hostname you opened.
• The dev server reads the wrong key or certificate file.
• Firefox needs NSS support or a browser restart.
• Node tools need NODE_EXTRA_CA_CERTS for outbound trust.
• Mobile devices need their own trust setup.
• A teammate copied a certificate without installing their own local CA.

mkcert reduces certificate command pain, but it cannot configure every dev server for you.

FAQ

Do I need HTTPS on localhost?

Sometimes. Many browser APIs treat localhost as a trusted local context, but OAuth, cookies, service workers, custom hostnames, and mobile testing may need explicit HTTPS.

Is mkcert better than a self-signed certificate?

For local browser development, yes. mkcert creates a local CA and certificates your browser trusts after setup. A self-signed certificate often triggers warnings.

Can a tunnel give me HTTPS without mkcert?

Yes, for the public URL. A tunnel can give reviewers an HTTPS link while your local server keeps running on HTTP.

Should I share my mkcert root CA key with teammates?

No. Each developer should run mkcert on their own machine. Do not share rootCA-key.pem.

Start with the shortest setup that fits

For ongoing local HTTPS, use mkcert. For a temporary HTTPS review link, use a tunnel.

npx wiremaven-cli 3000 --expires 30m

Related: mkcert Tutorial: Trusted Local HTTPS Setup | What Is a Localhost Tunnel? | How to Share Localhost with a Client