HTTPS on localhost with Caddy and memorable .localhost names

By

Updated

Serve a dev server at https://myapp.localhost through Caddy's local certificate authority, first with a two-line Caddyfile, then per project with Local Hoster.

In development you open http://localhost:4321, and most of the time that’s fine. Then you work on secure cookies, a service worker, WebAuthn or an OAuth callback, and the browser wants a secure origin.

Caddy can give you https://myapp.localhost with a certificate from its own local certificate authority, and forward every request to your dev server. We’ll do it by hand with a Caddyfile first, so you see what’s going on, then let Local Hoster do it for every project.

Why .localhost works without setup

Names ending in .localhost are reserved for your own machine. Browsers send myapp.localhost to 127.0.0.1 or ::1, so there’s nothing to add to /etc/hosts. Recent versions of curl do the same.

Caddy knows those names can’t get a public certificate. It issues one itself from a local authority it creates on first use, with a root called “Caddy Local Authority - 2026 ECC Root” (the year is when it was created). Your browser trusts those certificates once that root is in your system’s trust store.

Install Caddy with Homebrew:

brew install caddy

By hand: a Caddyfile

Start your dev server as usual, so it answers on http://localhost:4321. Then, in an empty folder, create a file called Caddyfile:

myapp.localhost {
	reverse_proxy localhost:4321
}

The first line is the address you’ll open. reverse_proxy forwards every request to the dev server. Run Caddy in that folder:

caddy run

Caddy logs “using adjacent Caddyfile”, creates the local authority, gets a certificate for myapp.localhost and listens on ports 80 and 443. The first time, it also tries to install its root certificate in the system trust store, which asks for your password.

Open https://myapp.localhost. Plain HTTP redirects to HTTPS:

curl -I http://myapp.localhost
HTTP/1.1 308 Permanent Redirect
Connection: close
Location: https://myapp.localhost/
Server: Caddy

Press Ctrl+C to stop Caddy. Only one program can listen on ports 80 and 443, so if you already run Caddy as a service, stop it first or skip this part. The Caddy course lesson proxy a local application goes deeper into reverse_proxy.

This setup has two problems. The port is fixed in the file, and when 4321 is busy Astro moves to 4322 and Caddy keeps sending requests to 4321. And every new project is another block to add and another reload.

Here’s how the two setups in this tutorial compare:

Caddyfile by handLocal Hoster
How Caddy runscaddy run in the project folderHomebrew service, always on
How routes get thereYou write a block per projectAdded through the admin API on localhost:2019
Dev server portFixed in the filePicked from the name, passed to the dev command
http://308 redirect to https://Serves the page too
When the dev server stopsRoute stays, requests failRoutes and TLS policy removed
While the dev server starts502Waits up to 10 seconds

Per project: Local Hoster

Local Hoster doesn’t write a Caddyfile. It talks to the Caddy admin API on localhost:2019, adds routes when your dev server starts and removes them when it stops. So Caddy needs to run all the time, with the admin API on.

The Homebrew service reads /opt/homebrew/etc/Caddyfile, and it can’t be empty. Put a global options block in it that turns on the admin API and nothing else:

printf '{\n\tadmin localhost:2019\n}\n' > "$(brew --prefix)/etc/Caddyfile"
brew services start caddy
caddy trust

An empty Caddyfile doesn’t work. caddy adapt on an empty file fails with EOF, and the service fails to start with adapting config: EOF. If you already have a Caddyfile with your own sites, keep it and skip the printf line.

caddy trust installs the root certificate in the system trust store and asks for your password. Check that the admin API answers:

curl http://localhost:2019/config/
{"admin":{"listen":"localhost:2019"}}

Install Local Hoster from the source zip on your Polar receipt: unzip it and run npm link in the folder. It needs Node.js 18 or newer and has no npm dependencies.

Wrap the dev command

In your project’s package.json, add a localhost field with the name and put localhoster in front of the dev command:

{
  "localhost": "myapp",
  "scripts": {
    "dev": "localhoster astro dev"
  }
}

Run npm run dev as usual. Local Hoster prints the two routes it added, then your dev server’s usual output:

Terminal in a ceramics-shop Astro project: cat package.json shows "localhost": "shop" and the dev script localhoster astro dev, then npm run dev prints http and https shop.localhost both pointing to localhost:15515, and Astro reports Local http://localhost:15515/

It picked port 15515 for shop.localhost and started astro dev --port 15515. That number comes from the name, so it’s the same every time. Give every project a stable .localhost URL covers how names become ports and how to run several projects.

Open https://shop.localhost. This is a fictional admin from the same demo, at https://admin.localhost, with the page reporting that it runs in a secure context:

An admin dashboard called Acme Admin open in Safari at admin.localhost, with a footer line reading https://admin.localhost, secure context: true

The page prints whether the browser treats it as a secure context, and it does, so the APIs that need HTTPS are available.

What it adds to Caddy

Each project gets three objects in the Caddy config, tagged with its name: an HTTP route on the :80 server, an HTTPS route on the :443 server, and a TLS policy that tells Caddy to use its internal authority for that name. You can read them from the admin API while the project runs:

curl http://localhost:2019/config/apps/tls/
{"automation":{"policies":[{"@id":"localhoster-shop-localhost-tls","issuers":[{"module":"internal"}],"subjects":["shop.localhost"]}]}}

The routes are localhoster-shop-localhost-http and localhoster-shop-localhost-https. Both forward to localhost:15515, and both keep retrying for up to 10 seconds while the dev server isn’t listening yet. A page you open while Astro starts waits for it, instead of showing an empty 502.

Unlike the Caddyfile above, there’s no redirect. http://shop.localhost and https://shop.localhost both serve the page. Use the HTTPS one when you test cookies or OAuth, and register that exact origin in the provider’s settings.

How a request reaches a dev server through Local Hoster and CaddyThe browser resolves shop.localhost to the local machine and connects to Caddy on port 443. Caddy uses a certificate from its internal authority, matches the host to the route Local Hoster added through the admin API, and forwards the request to the dev server on port 15515.admin API :2019Browser:https://shop.localhostCaddy on :443Certificate fromCaddy LocalAuthorityRoutelocalhoster-shop-localhost-httpsDev server onlocalhost:15515localhoster

Stop the dev server

Press Ctrl+C. Local Hoster removes both routes and the TLS policy, then exits. Reading the config again shows nothing left:

curl http://localhost:2019/config/apps/tls/
{"automation":{"policies":[]}}

Caddy keeps running for the next project. It removes the routes when the dev server exits on its own too, for example when it crashes on startup.

When it doesn’t work

If Caddy isn’t running, or the admin API is off, Local Hoster stops before starting your server:

Caddy is not running. Start it first:

  brew services start caddy

If it still does not start, check that its Caddyfile is not empty (see the README).

Check brew services list and the curl http://localhost:2019/config/ command above.

If the browser warns about the certificate, the root isn’t trusted yet. Run caddy trust while Caddy is running, then restart the browser. Without it, curl fails with SSL certificate problem: unable to get local issuer certificate.

Only your Mac trusts this authority. A phone on the same Wi-Fi resolves myapp.localhost to itself, not to your Mac, and wouldn’t trust the certificate anyway. The Caddy course lesson use local HTTPS covers trusting the root and testing clients that don’t trust it.

Get Local Hoster

Give your development projects memorable .localhost URLs with local HTTPS through Caddy. Includes the localhoster CLI and full MIT source.

See Local Hoster → · Read the docs · $20. See the app page for tax details, with full source code.

More tutorials for my apps →

Want me to talk about your product? You can sponsor this site.