Put any server behind Paperboat

A preview or tunnel sends each request to a port on your machine. Most servers work as they are. These are the settings for the ones that do not: a reverse proxy, a framework that checks the host name, a streaming or gRPC service.

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.

HeaderValue
X-Forwarded-ProtoAlways https: the visitor reached the edge over HTTPS.
X-Forwarded-HostThe public name the visitor typed.
X-Forwarded-PortAlways 443.
X-Forwarded-For, X-Real-IPThe visitor's address, one value. Anything the visitor sent under these names is dropped first.
ForwardedThe same facts in the standard form: for, proto and host.
HostThe public name, unchanged. Override it with --host-header when the app has a host allow-list.
Paperboat-Visitor-AssertionOnly 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 serverRoute
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. 1

    A tunnel to the proxy's port 80. A preview takes the same target: pb preview http://localhost:80.

  2. 2

    Add a second route, or use another origin, with the flags in the table.

  3. 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.

nginx.conf
# 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.

Caddyfile
{
    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
# 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.

apache.conf
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.

FrameworkSetting forConfigure
ViteHost allow-listserver.allowedHosts: [".example.test"] (and preview.allowedHosts), or run the preview with --host-header localhost.
Next.jsDev originsallowedDevOrigins: ["app.example.test"] in next.config, so the dev server accepts the public name.
DjangoHost, scheme, CSRFALLOWED_HOSTS, CSRF_TRUSTED_ORIGINS = ["https://app.example.test"], SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https").
RailsHost, schemeconfig.hosts << "app.example.test" and config.assume_ssl = true.
ExpressTrusted proxyapp.set("trust proxy", "loopback"), then req.protocol, req.hostname and req.ip are the visitor's.
FlaskTrusted proxyapp.wsgi_app = ProxyFix(app.wsgi_app, x_for=1, x_proto=1, x_host=1).
LaravelTrusted proxy$middleware->trustProxies(at: '127.0.0.1') in bootstrap/app.php.
Spring BootTrusted proxyserver.forward-headers-strategy=native.
ASP.NET CoreTrusted proxyapp.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.

LimitValueIf you hit it
Request body100 MB per request; larger is refused with 413.Upload in chunks, or use a TCP route for bulk transfer.
Request headers32 KB in total; larger is refused with 431.Trim cookies.
First byte from your app100 seconds; slower is answered with 504 and the code origin_timeout.Answer early and stream, or return a job id.
Stalled uploadA 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. 1

    Names that match no port go to the proxy on port 443 over HTTPS. The default is port 80 over http.

  2. 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