PortPilot - Pretty URLs for Local Development

How It Works

PortPilot uses mkcert to generate locally-trusted SSL certificates. When you run portpilot init, it:

Downloads the mkcert binary for your platform
Installs a local Certificate Authority (CA) into your system trust store
Generates SSL certificates for the .test domain

bash

portpilot init

No More Browser Warnings

Because the CA is installed in your system trust store, browsers will show a green padlock for your .test domains - no more clicking through "Your connection is not private" warnings.

✓

Test Secure Features Locally

With local HTTPS, you can test features that require a secure context: HttpOnly cookies, Service Workers, Web Crypto API, and more.

Certificate Storage

SSL certificates are stored in your home directory:

text

~/.portpilot/certs/
├── rootCA.pem        # The local CA certificate
├── rootCA-key.pem    # The CA private key
├── test.pem          # Wildcard cert for *.test
└── test-key.pem      # Cert private key

SNI (Server Name Indication)

The proxy uses SNI to serve the correct certificate based on the requested domain. This allows each project to have proper HTTPS without any configuration.

Regenerating Certificates

If you encounter certificate issues, you can regenerate them by running init again:

bash

# Regenerate certificates
portpilot init
# Restart proxy to pick up new certs
portpilot proxy stop
portpilot proxy -d

Troubleshooting

Browser still shows warning

If you still see certificate warnings after running portpilot init:

Restart your browser completely (not just the tab)
Clear browser cache for the domain
On macOS, you may need to restart Keychain Access
Try regenerating certificates with portpilot init

Certificate expired

mkcert certificates are valid for a limited time. Regenerate them with portpilot init and restart the proxy.

Security Note

The CA private key is stored locally and should not be shared. These certificates are only for local development and should never be used in production.

SSL Certificates