Some browser features simply refuse to work without HTTPS — geolocation, Service Workers, WebRTC, and most OAuth flows among them. Deploying to a remote server every time you need to test one of these is slow and unnecessary.

With mkcert and stunnel, you can have a fully trusted HTTPS environment running on localhost in under two minutes, no cloud hosting required.

What this guide covers:

• Generating a locally trusted certificate with mkcert

• Wrapping your dev server in a TLS tunnel with stunnel

• Fixing the most common setup errors

Why HTTPS on Localhost Matters

Running HTTP locally is fine for basic UI work, but it breaks down quickly once you start integrating with external services or using security-dependent browser APIs. A local HTTPS setup lets you:

• Test secure API integrations (Stripe, Google Maps, Auth0) without deploying

• Eliminate mixed-content warnings during frontend development

• Use browser features that only activate over a secure connection

• Replicate production conditions accurately from day one

Step 1: Install mkcert

mkcert is a zero-config tool that creates locally trusted development certificates. Unlike self-signed certificates, ones generated by mkcert are accepted by your browser without warnings because the tool installs its own local certificate authority.

On macOS with Homebrew:

brew install mkcert
mkcert -install

Once installed, generate a certificate for localhost:

mkcert -key-file ~/localhost-key.pem -cert-file ~/localhost-cert.pem localhost

This produces two files — a private key and a signed certificate — both scoped to localhost.

Step 2: Bundle the Certificate Files

Combine the key and certificate into a single file for easier use with stunnel:

cat ~/localhost-key.pem ~/localhost-cert.pem > ~/localhost-bundle.pem

Step 3: Set Up stunnel

stunnel is a lightweight proxy that wraps an existing TCP service in TLS encryption. It sits in front of your dev server and handles the HTTPS layer transparently.

Install it:

brew install stunnel

Then start it, pointing it at your dev server:

sudo stunnel3 -f -d 443 -r 8000 -p ~/localhost-bundle.pem

What each flag does:

• -d 443 — listens on the standard HTTPS port

• -r 8000 — forwards decrypted traffic to your local server on port 8000

• -p — specifies the certificate bundle to use

Tip: If port 443 is already in use, swap -d 443 for -d 8443 and access your site at https://localhost:8443 instead.

Step 4: Test the Setup

Start your local server on port 8000:

npm run dev --port 8000

Then open https://localhost in your browser. If everything is configured correctly, your site loads over HTTPS with no certificate warnings.

Troubleshooting

Certificate not trusted This usually means mkcert -install was skipped. Run it now — it registers the local CA with your system trust store and browsers pick it up automatically.

Port 443 already in use Switch to an alternate port:

sudo stunnel3 -f -d 8443 -r 8000 -p ~/localhost-bundle.pem

Then visit https://localhost:8443.

Command not found Confirm both tools are installed and on your $PATH:

which mkcert && which stunnel3

If either returns nothing, re-run the install step and open a new terminal session.

Key Takeaways

• mkcert generates locally trusted certificates that browsers accept without warnings.

• stunnel wraps any local server in a TLS tunnel without modifying the server itself.

• Bundling the key and certificate into one file keeps the stunnel command clean.

• Port 8443 is a reliable fallback when 443 is unavailable.

• This entire setup takes under two minutes and requires no external hosting.

Conclusion

Local HTTPS is one of those things that feels like extra work until you set it up once and realize how little effort it actually takes. mkcert handles certificate trust so your browser never complains, and stunnel handles encryption so your server does not have to.

Next time a browser API refuses to cooperate or an OAuth flow demands a secure origin, this setup has you covered — no deployment, no workarounds.

Have a question about the setup or want to see a version using nginx instead of stunnel? Leave a comment below.