A permanent public address for a service
A tunnel is a preview that stays. It keeps one address, comes back after a reboot or an update, and can serve several apps under your own domain.
$ pb tunnel create api --port 8080 --wait
Created tunnel api (tunnel_4kq81zc2)
https://calm-summer-beach-3476.pprbt.app -> http://127.0.0.1:8080
Status: ready- 1
The address is generated once and stays for the life of the tunnel.
apiis only a label you can rename.
Preview or tunnel
Same engine, different lifetime. Start with a preview; press t in it when you want to keep it.
| Question | Preview | Tunnel |
|---|---|---|
| Lives | While the command runs, or up to 24 hours in the background | Until you delete it |
| After a reboot | Gone | Comes back by itself |
| Routes | One target | Many: by host, by path, plus raw TCP |
| Pause without deleting | No | Yes |
| Custom domain | Yes | Yes |
Custom domains
Add a domain or a subdomain to your workspace once. After that, giving a tunnel a name under it is one command and takes effect without touching DNS again.
Your DNS stays where it is. Paperboat never edits it, and removing a domain here leaves your records alone.
$ pb domain add dev.example.com$ pb domain verify dev.example.com$ pb tunnel route list api
$ pb tunnel domain add api api.dev.example.com --route <route>- 1
Prints two DNS records: a CNAME that proves the domain is yours, and a wildcard that sends its names to Paperboat.
- 2
Once the records exist. One certificate is issued for the domain and every name one level under it.
- 3
A hostname is served by one of the tunnel's routes;
route listshows the onecreatemade. No DNS step for this name.
Routes
Routes decide where a request goes: by host name, by path, or as plain TCP. Up to 100 previews and tunnels run at once on Free, 1,000 on Pro.
$ pb tunnel route add api --name web --to http://127.0.0.1:3000 --path / --wait$ pb tunnel route add api --name db --to 127.0.0.1:5432 --protocol tcp --wait$ pb tunnel route add api --name db --to 127.0.0.1:5432 --protocol tcp_private --wait- 1
A second app behind the same tunnel. The longest matching path wins.
- 2
Raw TCP on a public port of its own. Your service does its own authentication.
- 3
TCP that is never public: only your signed-in machines can open it.
Errors
pb tunnel status, pb tunnel logs and pb tunnel doctor report one of these, and the same code is
in --json for your monitoring.
| Code | Meaning | What to do |
|---|---|---|
connector_offline | The machine is off or Paperboat is stopped on it | Turn it on and run pb doctor there. The tunnel reconnects by itself. |
origin_refused | Your app is not listening on the route's port | Start it, or fix the port with pb tunnel route update. |
origin_timeout | Your app is up but did not answer in time | Check that it is healthy and not behind a firewall. |
origin_tls | Your app's TLS certificate was not accepted | Trust it in the route's settings, or use an http origin. |
dns_pending | The custom domain is not verified yet | Add the records from pb domain show, then pb domain verify. |
certificate_pending | The certificate is still being issued | Wait. Issuance starts once DNS is verified. |
bandwidth_exhausted | The workspace used its bandwidth for the month | Add bandwidth or change plan. Traffic resumes when there is allowance. |
Questions
Are custom domains a paid feature?
No. Your own domains, with certificates issued and renewed for you, are on every plan including Free.
Does the address ever change?
No. A tunnel's address under pprbt.app is generated when you create it and belongs to that tunnel until you delete it. Renaming the tunnel changes only its label.
Can I expose a database or another TCP service?
Yes, with a tcp route, which gets a stable public port. Free includes 1 public TCP address, Pro 10, Team 10 per seat; on an edge you host yourself there is no limit. If only your own machines need it, a tcp_private route or private access is safer.
Is this a Cloudflare Tunnel alternative?
For publishing a service from a machine behind NAT, yes, and you do not need to move your DNS anywhere to start. Cloudflare puts its CDN, WAF and Access in front of your tunnel, which Paperboat does not have. See the comparison.
Can I put a login in front of a tunnel?
A tunnel created with --private or --team only answers your own or your teammates' signed-in machines. There is no hosted login page for outside visitors; put your own authentication in the app for that.
Where does TLS end?
At the edge, as with any public HTTPS service you do not host yourself. From the edge to your machine the traffic is encrypted again. You can run the edge on your own server.
Related
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