HTTPS and domains

Every Covo site is served over HTTPS with a certificate your browsers trust, on a local name that only ever points to your own Mac.

Domain suffixes

Covo only serves reserved, local-only suffixes:

Suffix	Example	Setup	How the name resolves
.localhost	demo.localhost	None (default)	macOS sends every *.localhost name to your Mac
.test	demo.covo.test	covo domains enable test	A resolver file sends .test lookups to Covo’s small DNS server on 127.0.0.1
.local	pde.local	covo domains enable local	Covo’s lines in /etc/hosts, as MAMP PRO does it

The part before the suffix is up to you, for example covo site add demo --domain demo.covo.test. Other suffixes (.dev, .covo) and public domains are refused. In the app, .test and .local are in Settings → Domains.

.test

Enabling .test writes one file, /etc/resolver/test, with one administrator authorization through the standard macOS dialog (Covo never runs sudo or sees your password). The DNS server runs as your user on 127.0.0.1 and answers only for .test names.

covo domains enable test
covo domains disable test      # refused while sites use .test

.local (MAMP compatibility mode)

.local names only work through /etc/hosts. Enabling them installs a small helper, with one administrator authorization, that can only edit Covo’s own marked block in that file. Everything outside it, such as MAMP’s lines, stays exactly as it was. Use this mode to keep the names of sites you bring over from MAMP.

covo domains enable local
covo domains disable local     # refused while .local sites exist

Removing the helper needs no password.

The local certificate authority

Covo creates its own certificate authority (CA) and uses it to sign each site’s certificate. You trust it once with covo trust (one macOS dialog, login keychain, your user only).

A trusted CA can normally vouch for any website, so Covo’s is limited by Name Constraints: it can only sign names under .localhost, .test and .local, and no IP addresses. Safari, Chrome and Firefox enforce these limits and reject anything else it might sign, such as example.com or 127.0.0.1. The CA’s private root key is discarded right after it is created, so nobody, Covo included, can make another signing certificate under it.

PHP does not read the macOS keychain, so Covo gives PHP its own certificate bundle (Mozilla’s roots plus Covo’s CA). Your sites can call themselves over HTTPS, as WordPress does for loopback requests, cron and the REST API, with verification on.

Ports

Sites use port 8443 by default: https://shop.localhost:8443. You can choose another port, or the standard port 443 so addresses have no port. An optional HTTP port redirects http:// addresses to HTTPS.

covo ports                          # show
covo ports --https 443              # no port in addresses
covo ports --http 80                # http:// redirects to https:// (0: off)
covo ports --https 9443 --http 0    # back to a custom port

In the app: Settings → General → Ports.

Ports from 1024 to 65535 need nothing. Covo never runs as root, so for 443 and 80 it installs its helper (the same one as for .local) with one administrator password. The helper forwards the standard port to Covo, only on your Mac’s loopback address, so nothing becomes reachable from the network. It uses Covo’s own firewall anchor and leaves /etc/pf.conf unchanged. The forwards exist only while Covo is running.

Covo never takes a port another program is using. If MAMP or anything else already listens on 80 or 443, Covo refuses and leaves it alone.

WordPress stores its address in the database. After changing the HTTPS port, update existing WordPress sites:

covo wp shop search-replace https://shop.localhost:8443 https://shop.localhost

Open on phone

You can open one site at a time on a phone or tablet on the same network. In the app: the Open on Phone tile in the site detail. The toolbar and menu bar show an indicator while a site is shared.

covo phone shop                 # share for 30 minutes
covo phone shop --minutes 120   # at most 1440 (24 hours)
covo phone                      # what is shared, and where
covo phone --off

Sharing turns itself off after the chosen time. The site is served only on your Mac’s private network addresses, and its files and database are not changed.

The first QR code opens the site over plain HTTP at your Mac’s address, with nothing to install on the phone. Features that need a secure page (camera, location, service workers, payments), or a site that forces HTTPS, need the HTTPS address: choose Use HTTPS Instead in the app. It uses a .local name and Covo’s CA, which you install on the phone from a page Covo serves, with a QR code of its own. On iOS, enable it afterwards in Settings → General → About → Certificate Trust Settings. Nothing about the CA changes for this: it already allows .local names.

Android often does not resolve .local names, so the plain HTTP address is the one to use there. If the macOS firewall is on, macOS may ask whether caddy may accept incoming connections. With “Block all incoming connections” nothing gets through. Covo tells you the firewall state but never changes it.

Removing trust

covo untrust

This removes Covo’s CA from your login keychain. Sites keep running, but browsers show a certificate warning until you trust it again. covo uninstall also removes the CA, together with everything else Covo installed.