When a tunnel is the right tool
When there is a live process on the other end. Testing a webhook against a local server, demonstrating an application mid-development, letting a mobile device hit your dev environment, debugging something with real inbound traffic. In all of those the value is exactly that the request reaches your machine.
When it is the wrong tool
When the artifact is finished. Then the tunnel adds three failure modes for no benefit: the link dies when your laptop sleeps, the URL changes when the tunnel restarts, and whoever you sent it to gets an error at the exact moment they get around to looking. It is also, briefly, a public route into your machine.
The alternative
curl -X POST https://read.botook.ai/sites \
-H "Authorization: Bearer otr_live_YOUR_KEY" \
-F file=@index.htmlThe file is now on a URL that does not depend on your machine being awake, does not change, is not indexed, and closes itself when its expiry arrives.
Side by side, for the static case
| Tunnel | Publish | |
|---|---|---|
| Serves | A process on your machine | A stored document |
| Survives sleep | No | Yes |
| Stable URL | Not on the free tier | Yes |
| Access control | Basic auth if configured | Password, email gate, one-time, expiry |
| Exposure | A route into your machine | One document |
| Cleanup | Kill the process | Expires on its own |
Keeping the iteration loop
The reason people like tunnels is that the page updates when they save. You keep that with
one extra call — update_site or PUT /sites/:idOrSlug rewrites the bytes under the
same URL, so a watcher script or an agent loop gives the same experience without exposing the
machine.
What if my page calls a local API?
Then you have a process, not a file, and a tunnel is the right tool. Publish the static view of it — the report, the screenshot-shaped summary — and keep the tunnel for the live parts.
Can I password-protect the published link?
Yes, with set_password or a PATCH. You can also gate on a work-email domain,
which forwarding does not defeat.
How fast is this compared to starting a tunnel?
One HTTP request against about the same. The difference is what happens twenty minutes later when you close the laptop.
Can an agent do it mid-session?
That is the primary path — publish_html over MCP, no shell-out and no tunnel process to
supervise.