HTTPS proxy
Joppa's built-in reverse proxy: ports, protocols, forwarded headers, error pages and automatic start.
The proxy receives every request to your .test domains, decrypts it with the domain’s certificate, then forwards it to the dev server.
Ports and addresses
| Port | Role |
|---|---|
| 443 | HTTPS |
| 80 | Redirects to HTTPS |
The proxy listens on 127.0.0.1 (and ::1 when IPv6 is available). It only accepts connections from your machine.
What gets through
- HTTP/2 and HTTP/1.1.
- WebSockets: hot reloading (HMR) in Vite, Next.js or Astro works.
- Server-Sent Events: streams stay open.
- Headers: original
Hostkept;X-Forwarded-Proto: https,X-Forwarded-Host,X-Forwarded-Port: 443andX-Forwarded-Foradded.
Error pages
| Case | Response |
|---|---|
.test domain unknown to Joppa |
A “Domain not configured” page (not a certificate error) |
| The dev server doesn’t respond | A 502 page “The dev server is not responding” |
Start and stop
- Settings › Proxy: status, Start / Stop, and Start the proxy when Joppa opens (on by default).
- The ⌘ K palette: “Restart the HTTPS proxy”, “Stop the proxy”.
- The menu bar: Start proxy / Stop proxy.
- The terminal:
joppa proxy start/joppa proxy stop.
When the proxy is stopped, a banner at the top of the window reminds you, and the Dock icon turns red.
Joppa in the background
Closing the window doesn’t quit Joppa: the proxy keeps serving your domains, and Joppa stays in the menu bar. Its menu lists your projects and their domains (a click opens them), the proxy status, Open Joppa… and Quit Joppa. Only one instance runs at a time: launching the app again brings back the existing window.