What Paperboat sends
Paperboat answers the public name over HTTPS and tells your server so. The request reaches it from the same machine (loopback), which
most frameworks already trust, so redirects, absolute links, Secure cookies and CSRF origin checks work without changes.
| Header | Value |
|---|---|
X-Forwarded-Proto | Always https: the visitor reached the edge over HTTPS. |
X-Forwarded-Host | The public name the visitor typed. |
X-Forwarded-Port | Always 443. |
X-Forwarded-For, X-Real-IP | The visitor's address, one value. Anything the visitor sent under these names is dropped first. |
Forwarded | The same facts in the standard form: for, proto and host. |
Host | The public name, unchanged. Override it with --host-header when the app has a host allow-list. |
Paperboat-Visitor-Assertion | Only on private and team routes: a signed token naming the signed-in visitor. Public routes never carry it. |
Choose the origin
Your server does not need a public certificate: Paperboat holds the certificate for the public name. Behind a tunnel your server cannot get one by HTTP-01 or TLS-ALPN-01 either, because Paperboat answers for the name. Pick the row that matches your server.
| Your server | Route |
|---|---|
| Plain HTTP, the simplest | --to http://localhost:80 |
| HTTP/2 without TLS (gRPC servers) | --to h2c://localhost:50051 |
| Caddy tls internal, or an origin with its own private CA | --to https://localhost:443 --tls-ca <root.crt> |
| A long-lived self-signed certificate (NAS, Proxmox, router) | --to https://localhost:8006 --tls-verification pinned |
| Any certificate on the same machine, when you just want it to work | --to https://localhost:443 --tls-verification insecure |
| A real certificate from a DNS-01 challenge | --to https://localhost:443 (the default verification) |
$ pb tunnel create api --from http://localhost:80 --wait $ pb tunnel route add api --name web --to https://localhost:443 --tls-ca caddy-root.crt --wait $ pb preview http://localhost:3000 --host-header localhost - 1
A tunnel to the proxy's port 80. A preview takes the same target: pb preview http://localhost:80.
- 2
Add a second route, or use another origin, with the flags in the table.
- 3
The app sees Host: localhost; the visitor keeps the public name.
Reverse proxies
A proxy in front of your app decides what the app sees. Without the trusted-proxy line it replaces the visitor's address with its own, so every visitor looks like one address. If the proxy's port 80 redirects to HTTPS, point the route at its HTTPS port instead.
nginx
Use $http_x_forwarded_proto, not $scheme, which says http. Without client_max_body_size nginx refuses bodies over 1 MB.
# inside the server block that answers the tunnel
set_real_ip_from 127.0.0.1;
real_ip_header X-Forwarded-For;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;
proxy_buffering off;
client_max_body_size 100m;
} Caddy
Serve the site as http://name, or use auto_https disable_redirects on the port the tunnel uses.
{
servers {
trusted_proxies static 127.0.0.1/32 ::1/128
}
}
# Plain http, so Caddy does not redirect the tunnel to HTTPS.
http://app.example.test {
reverse_proxy 127.0.0.1:3000
} Traefik
Add the Docker bridge to trustedIPs if Traefik runs in a container. Put the HTTP-to-HTTPS redirect only on entry points the tunnel does not use.
# traefik.yml (static configuration)
entryPoints:
web:
address: ":80"
forwardedHeaders:
trustedIPs:
- "127.0.0.1/32"
- "::1/128" Apache
Needs mod_remoteip and mod_setenvif. Guard any RewriteCond %{HTTPS} off redirect with the HTTPS=on variable set here.
RemoteIPHeader X-Forwarded-For
RemoteIPInternalProxy 127.0.0.1
SetEnvIf X-Forwarded-Proto https HTTPS=on
# Only for an app that does not answer Expect: 100-continue (HTTP/1.0 servers).
Proxy100Continue Off Coolify
Coolify runs Traefik (or Caddy) as its proxy and picks the app by host name. Paperboat keeps the public name as the host, so set the app's domain in Coolify to the name you open: your tunnel's address or a custom domain.
Coolify redirects http to https on a domain with an https address, so point the route at the proxy's HTTPS port with the certificate
options from the table above: --to https://localhost:443 with --tls-verification insecure (the proxy is on the
same machine). Paperboat sends the public name as the TLS server name, so the proxy picks the right site.
For a preview, or when the app's domain in Coolify is not the public name, send the name Coolify knows:
pb preview http://localhost:80 --host-header app.example.test.
For your own machines only, use the front desk: no public address is needed.
Frameworks
Most frameworks trust loopback, so the forwarded headers just work. These are the ones that check the host name or need one setting for
the visitor's address. Use --host-header instead of changing a dev server's allow-list.
| Framework | Setting for | Configure |
|---|---|---|
| Vite | Host allow-list | server.allowedHosts: [".example.test"] (and preview.allowedHosts), or run the preview with --host-header localhost. |
| Next.js | Dev origins | allowedDevOrigins: ["app.example.test"] in next.config, so the dev server accepts the public name. |
| Django | Host, scheme, CSRF | ALLOWED_HOSTS, CSRF_TRUSTED_ORIGINS = ["https://app.example.test"], SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https"). |
| Rails | Host, scheme | config.hosts << "app.example.test" and config.assume_ssl = true. |
| Express | Trusted proxy | app.set("trust proxy", "loopback"), then req.protocol, req.hostname and req.ip are the visitor's. |
| Flask | Trusted proxy | app.wsgi_app = ProxyFix(app.wsgi_app, x_for=1, x_proto=1, x_host=1). |
| Laravel | Trusted proxy | $middleware->trustProxies(at: '127.0.0.1') in bootstrap/app.php. |
| Spring Boot | Trusted proxy | server.forward-headers-strategy=native. |
| ASP.NET Core | Trusted proxy | app.UseForwardedHeaders with XForwardedFor and XForwardedProto; loopback is trusted by default. |
gRPC, WebSocket and streams
WebSocket upgrades, server-sent events and streamed responses pass through, so AI token streams arrive as they are produced. Turn off
response buffering in any proxy in between (proxy_buffering off in nginx).
gRPC passes through with its trailers. Clients connect to the public name on port 443 over TLS. Point the route at a plain HTTP/2
server with --to h2c://localhost:50051; an https origin works as well.
gRPC-Web is not tested; if your proxy translates it to gRPC, route to the proxy as to any HTTP origin.
Uploads and timeouts
These are the defaults of Paperboat's edge; an edge you host yourself can change them.
| Limit | Value | If you hit it |
|---|---|---|
| Request body | 100 MB per request; larger is refused with 413. | Upload in chunks, or use a TCP route for bulk transfer. |
| Request headers | 32 KB in total; larger is refused with 431. | Trim cookies. |
| First byte from your app | 100 seconds; slower is answered with 504 and the code origin_timeout. | Answer early and stream, or return a job id. |
| Stalled upload | A body that stops arriving for 60 seconds is answered with 408. | Retry the upload. |
Private access
On your own machines a proxy needs no public address. https://app.homelab.ppr.boats goes to the port named
app; a name no port has goes to the machine's front desk, the proxy that knows it. The proxy sees the name the
browser typed as its Host.
$ pb port front-desk homelab 443 https $ pb port name set grafana 3000 --machine homelab - 1
Names that match no port go to the proxy on port 443 over HTTPS. The default is port 80 over http.
- 2
A name that matches a port goes straight there: https://grafana.homelab.ppr.boats.
Start with the machine in front of you
Install Paperboat here, then on a second machine. Free for personal use, no card needed.
$ curl -fsSL https://get.pprbt.dev/install | bash > irm https://get.pprbt.dev/install.ps1 | iex