mkcert: Trusted HTTPS on Localhost Without the Browser Warning

A local certificate authority that actually gets trusted

Contents

Every developer who has ever built anything that touches cookies, service workers, WebAuthn or a strict CORS policy has hit the same wall: the thing only behaves correctly over HTTPS, and http://localhost is not HTTPS. So you generate a self-signed certificate, point your dev server at it, and get a full-page red warning that trains you to click through security prompts without reading them. That habit is the actual danger, rather than the self-signed cert itself. mkcert exists to stop you learning it.

The tool, maintained by cryptographer Filippo Valsorda under the FiloSottile GitHub organisation, solves a narrow problem extremely well. It creates a local certificate authority, installs that CA’s root certificate into your operating system’s and browsers’ trust stores, and then issues leaf certificates signed by that CA for whatever hostnames you ask for. Because the root is genuinely trusted by your machine, every certificate it signs is genuinely trusted too. No warning, no exception page, no “proceed anyway” muscle memory.

Why self-signed certificates train bad habits

A self-signed certificate has no chain of trust behind it. The browser cannot verify it against anything it already trusts, so it shows a warning and asks you to add a manual exception. Do that often enough across enough projects and you stop reading the warning at all — you just click through. That is precisely the behaviour a real phishing or man-in-the-middle certificate warning is trying to interrupt, and repeated exposure to fake danger dulls your reaction to real danger. It is the same mechanism as alert fatigue in a monitoring system: cry wolf enough times and the wolf stops meaning anything.

There is also a growing set of browser and platform features that flatly refuse to run outside a “secure context”, and a self-signed exception does not always count as one. Service workers, the Web Crypto API, WebAuthn and passkey registration, geolocation on some browsers, and clipboard access all check for a genuinely trusted origin before they will function. localhost itself gets a special-cased pass in most browsers, but the moment you move to a named host — api.mylab.local, a LAN IP, a hostname shared between two containers — that pass disappears and you need a certificate the browser actually believes. This is why so many “it works on my machine but not when I test it from my phone” bugs turn out to be secure-context failures rather than anything to do with your application code.

mkcert sidesteps the whole problem by making the certificates actually trustworthy from the browser’s point of view, because they chain up to a CA your machine was told to trust. The trick is that the CA’s private key never leaves your laptop, so nobody else can mint certificates that your machine will trust — a local-only trust anchor that only exists on boxes where you deliberately installed it.

An open iron padlock with its shackle lifted away and its internal spring mechanism exposed.
A padlock with its mechanism exposed. The browser padlock that mkcert-issued certificates earn on localhost rests on a chain of trust rather than a mechanism, but the promise is the same. Photo: Padlock and key by André Omereler, CC0, via Wikimedia Commons.

Installing it

mkcert ships prebuilt binaries and packages for the usual platforms.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Debian/Ubuntu
sudo apt install libnss3-tools
curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
chmod +x mkcert-v*-linux-amd64
sudo mv mkcert-v*-linux-amd64 /usr/local/bin/mkcert

# macOS
brew install mkcert nss

# Then, everywhere:
mkcert -install

libnss3-tools matters if you use Firefox or Chrome on Linux, because those browsers keep their own certificate store (NSS) separate from the system one that curl and most other tools use. Without it, mkcert can still create the CA, but Firefox will not trust it until you import it manually.

mkcert -install does the actual work: it generates a CA keypair if one does not exist yet, then installs the CA certificate into every trust store it can find — the system store, Java’s cacerts if a JVM is present, and each browser’s NSS database. Run it once per machine. Each teammate on a project needs to run their own mkcert -install; the CA is per-machine on purpose, not shared, which is exactly why it is safe to trust.

Run mkcert -CAROOT afterwards to see exactly where the CA files landed. On Linux that is typically a path under ~/.local/share/mkcert; on macOS, ~/Library/Application Support/mkcert. Two files live there: rootCA.pem, the public certificate, and rootCA-key.pem, the private key that signs everything mkcert issues. Only the second one is sensitive.

Issuing a certificate

Once the CA is installed, issuing leaf certificates for actual hostnames is a single command:

1
mkcert dev.mylab.local "*.dev.mylab.local" localhost 127.0.0.1 ::1

That produces two files in the current directory: dev.mylab.local+4.pem (the certificate, covering all five names you listed) and dev.mylab.local+4-key.pem (the private key). Point your dev server or reverse proxy at those two files and every one of those hostnames now serves valid HTTPS.

A wildcard entry like *.dev.mylab.local is worth including even if you only need one hostname today, because adding a second service later (an API on api.dev.mylab.local, an admin panel on admin.dev.mylab.local) means you can reuse the same certificate instead of minting a new one and restarting whatever loaded it. The +4 suffix in the filename just counts how many names the certificate covers; if you reissue with a sixth name, mkcert writes dev.mylab.local+5.pem instead of overwriting the old files, so you can tell at a glance which certificate is current without opening it.

Wiring it into a dev server

Most frameworks and reverse proxies accept a cert and key path directly. With Caddy, for a local reverse-proxy setup:

1
2
3
4
dev.mylab.local {
    tls dev.mylab.local+4.pem dev.mylab.local+4-key.pem
    reverse_proxy localhost:3000
}

With Node’s built-in HTTPS server:

1
2
3
4
5
6
7
const https = require('node:https');
const fs = require('node:fs');

https.createServer({
  cert: fs.readFileSync('dev.mylab.local+4.pem'),
  key: fs.readFileSync('dev.mylab.local+4-key.pem'),
}, app).listen(443);

You will also need the hostname to actually resolve. For a single machine, an /etc/hosts entry pointing dev.mylab.local at 127.0.0.1 is enough. For a homelab where several devices need to reach the same dev box, point a real DNS record at it instead — I run a local DNS resolver for exactly this, described in what a TLS handshake is actually saying, which covers the handshake mechanics mkcert is quietly sidestepping for you.

Docker and container workflows

The common failure mode in containerised dev environments is that mkcert’s CA lives on the host, but the browser making the request runs on the host too while the server runs in a container — the certificate and key just need to be mounted in, which is simple:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
services:
  web:
    build: .
    volumes:
      - ./certs:/certs:ro
    environment:
      - TLS_CERT=/certs/dev.mylab.local+4.pem
      - TLS_KEY=/certs/dev.mylab.local+4-key.pem
    ports:
      - "443:443"

The trickier case is testing from a second machine — a phone or tablet on the same network — because that device has never run mkcert -install and has no reason to trust your CA. The fix is exporting the root certificate and installing it as a trusted profile on the device: on iOS that means airdropping or emailing rootCA.pem, opening it, installing the profile under Settings, and then separately flipping it on under Certificate Trust Settings, which Apple deliberately splits into two steps. Android’s flow is similar but lives under Settings → Security → Encryption & credentials → Install a certificate. Neither is instant, but you only do it once per test device, and it beats permanently disabling certificate warnings in the browser, which some engineers do out of impatience and then forget to re-enable.

Where mkcert stops being the right tool

mkcert is deliberately scoped to development and local trust — it is not a certificate authority you should run for production services, and it has no revocation mechanism, no short-lived certificate rotation and no audit trail. For anything that needs to be trusted by devices you do not personally administer, or that needs the operational guarantees a real PKI gives you, reach for something built for that job. I run step-ca as an internal certificate authority for homelab services that other household devices need to trust, and Caddy’s automatic HTTPS for anything actually exposed. mkcert’s job ends the moment code leaves your own development machine.

The distinction is worth being precise about, because the two tools solve genuinely different problems that look superficially similar. mkcert answers “how do I get a trusted padlock on my own laptop for code I am writing right now.” step-ca and similar internal CAs answer “how do I issue certificates that a fleet of other machines, some of which I do not directly control, should trust, with rotation and revocation built in.” Reaching for mkcert to solve the second problem means every device needs the same CA key manually installed and kept in sync, which is a maintenance burden a real internal CA is designed to avoid. Reaching for step-ca to solve the first problem is just needless operational weight for a certificate that only your own browser will ever check.

There is one adjacent trap worth naming: the CA root key mkcert generates lives, unencrypted, in a config directory as described above. Anyone with access to that file and your machine’s trust store could mint certificates your browser would silently accept. That is a fine trade-off for a personal laptop. It is not a trade-off you want on a shared build server, where a compromised CA key could be used to intercept traffic for anyone whose browser trusts it. Keep mkcert’s CA to single-user machines and you get all of the convenience with none of the actual attack surface.

CI pipelines and headless testing

If a pipeline runs browser tests against a service that expects HTTPS — a webhook receiver, a WebAuthn flow, anything gated behind a secure-context check — you can install the CA non-interactively as part of the job:

1
2
mkcert -install
mkcert -cert-file ci.pem -key-file ci-key.pem localhost 127.0.0.1

Headless Chrome and Firefox read the same NSS and system trust stores as their interactive counterparts, so once -install has run inside the CI container, browser automation tools like Playwright and Cypress stop flagging the certificate as invalid. The one wrinkle is that CI containers are usually ephemeral, so this has to run every job rather than once — cheap in practice, since certificate issuance is local and takes a fraction of a second, but worth knowing before you assume the CA persists between runs the way it does on your own machine.

Sharing trust across a team

The natural next question is whether a team can share one CA so nobody has to remember which teammate’s laptop issued which certificate. mkcert supports this, technically: copy rootCA.pem and rootCA-key.pem into everyone’s $(mkcert -CAROOT) directory and every machine trusts certificates issued by the same authority. In practice I would not do it. Distributing the CA’s private key to every laptop on a team means any one of those machines being compromised lets an attacker mint certificates the whole team’s browsers will silently trust, which is exactly the blast radius a per-machine CA was designed to avoid. The convenience gain — one shared certificate file instead of everyone issuing their own — is small; the certificates themselves are cheap and instant to generate, so there is rarely a good reason to pay that cost. Let each teammate run their own mkcert -install and issue their own leaf certificates for the same hostnames; the certificates differ, the trust behaviour does not.

Where a shared root genuinely earns its keep is a small, deliberately-scoped case: a handful of physical test devices — a couple of phones, a tablet — that the whole team uses for manual QA and that never leave a locked drawer. Installing one CA’s root as a trust profile on those specific devices is a bounded, auditable decision in a way that pushing a private key onto every developer’s laptop is not.

Removing it cleanly

If you ever want to undo the trust relationship — decommissioning a laptop, or just tidying up — mkcert -uninstall removes the CA from every trust store it added it to, and deleting the config directory removes the key material. Nothing about mkcert modifies system files outside those trust stores, so there is no lingering cruft to hunt down afterwards.

Troubleshooting

Firefox still shows a warning after mkcert -install. Confirm libnss3-tools (or nss on macOS) was installed before you ran -install — mkcert only touches the NSS database if it can find the tooling. Reinstall the tool, then rerun mkcert -install.

curl trusts it, the browser doesn’t. Different trust stores. curl usually reads the system store; browsers on Linux frequently use their own NSS store. This is the same libnss3-tools issue from above.

Docker containers reject the certificate. The CA was only installed on the host, not inside the container’s filesystem. Copy $(mkcert -CAROOT)/rootCA.pem into the container’s trust store, or mount it and update-ca-certificates inside the image.

A phone on the same network still shows a warning. The device has never had the CA root installed as a trust profile — see the Docker and container workflows section above. Browser certificate trust is per-device, not per-network, so pinging a service from a laptop that trusts the CA proves nothing about a phone that does not.

The certificate expired. mkcert leaf certificates are valid for a fixed and fairly long window, but if you hit it, just rerun the mkcert issuance command with the same hostnames — it is idempotent and free, since you own the CA.

For a five-minute setup, mkcert eliminates a genuinely bad habit — clicking through security warnings — while costing nothing except a .gitignore entry so you never accidentally commit the private key alongside your dev config.

Smarc
Written by Smarc

Founder and editor of Aside House. A lifelong tinkerer who self-hosts far more than is sensible, hardens Linux boxes for fun, and prods the latest AI tools to see what they can really do. The how-to guides here are the notes Smarc wishes had existed the first time round.

Smarc is the editor of Aside House. The homelab, the hardware and the opinions are real; the guides are drafted with AI assistance. Infrastructure details are genericised on purpose.