Installation

Download

Get the latest version from the download page:

System	File
macOS (Apple Silicon and Intel)	.dmg: drag Joppa into Applications
Linux x86_64	.AppImage (portable, make it executable: chmod +x Joppa_amd64.AppImage) or .deb (Debian, Ubuntu: sudo apt install ./Joppa_amd64.deb)

First launch on macOS

Joppa is not signed by Apple yet, so macOS blocks the first launch. That’s expected, and it only asks once.

1. Open Joppa from Applications. macOS shows ““Joppa” Not Opened”: click Done, not Move to Trash.
2. Open System Settings › Privacy & Security and scroll down to Security.
3. Next to ““Joppa” was blocked to protect your Mac”, click Open Anyway.
4. Confirm with Open Anyway, then your password or Touch ID.

The download page shows these steps with pictures.

On first launch, Joppa creates its config folder and its certificate authority, and starts the HTTPS proxy. It then lives in the menu bar: closing the window doesn’t stop it.

Trust the certificate

Joppa signs a certificate for each domain with a local certificate authority (CA). For the browser to show the padlock, your system must trust that authority. You do this only once, with an administrator password.

Open Settings › Certificate authority: Joppa shows the exact command for your machine, with a button to copy it.

macOS

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain \
  "$HOME/Library/Application Support/joppa/ca/rootCA.pem"

Joppa checks trust on its own: the status bar switches to CA ok as soon as it’s done.

Linux

sudo cp ~/.config/joppa/ca/rootCA.pem /usr/local/share/ca-certificates/joppa-rootCA.crt
sudo update-ca-certificates

Ports 80 and 443

The proxy listens on 127.0.0.1, port 443 (HTTPS) and 80 (redirect to HTTPS). It only accepts connections from your machine.

• macOS: nothing to do.
• Linux: ports below 1024 need a special permission. If Joppa can’t open them, it shows the command to run:

sudo setcap cap_net_bind_service=+ep /path/to/joppa

If only port 80 is unavailable, the proxy still runs; the HTTP → HTTPS redirect is simply disabled.

Resolving .test domains

The browser needs to know that myproject.test points to your machine (127.0.0.1). Joppa doesn’t change your DNS configuration: if a domain doesn’t respond while the proxy is running, make *.test resolve to 127.0.0.1.

On macOS, with dnsmasq (Homebrew):

brew install dnsmasq
echo 'address=/.test/127.0.0.1' >> "$(brew --prefix)/etc/dnsmasq.conf"
sudo brew services start dnsmasq
sudo mkdir -p /etc/resolver
echo 'nameserver 127.0.0.1' | sudo tee /etc/resolver/test

A container runtime (optional)

Domains and HTTPS need nothing else. For services (PostgreSQL, Redis, Mailpit…), install one of these runtimes: OrbStack, Docker Desktop, Colima or Podman. See Container runtimes.

Check

The status bar at the bottom of the window sums it all up:

joppa   proxy :443   CA joppa ok   2/2 domains online   1/1 service

You’re ready for getting started.