docs: examples/ for Gradio, Streamlit, FastAPI, and webhooks

Each example is a copy-paste flow: run app on a fixed local port -> add-route
to get a permanent HTTPS URL -> curl to verify. Cross-linked from a new
"Examples" section in the README.

Covers the four most common asks:
  - Gradio: replace share=True
  - Streamlit: local dashboard with stable URL
  - FastAPI: personal API + path-based routing under one domain
  - Webhooks: GitHub / Stripe / Slack receivers on a laptop, including
    a path-based pattern for multiple providers on one domain

Author: nachum10

README.md

@@ -341,7 +341,20 @@ A hermetic test suite lives in `tests/run-tests.sh` (27 tests, no real cloudflar
 bash tests/run-tests.sh
 ```
 
-Covers input validation, idempotency, catch-all sanity checks, remove-route correctness, and `detect.sh` rejection of tampered configs.
+Covers input validation, idempotency, catch-all sanity checks, remove-route correctness, and `detect.sh` rejection of tampered configs. CI runs the same suite on every push and PR — see the **tests** badge at the top.
+
+---
+
+## Examples
+
+End-to-end recipes for common stacks live in [`examples/`](./examples/):
+
+- [Gradio](./examples/gradio.md) — replace `share=True` with a permanent URL
+- [Streamlit](./examples/streamlit.md) — local dashboard with stable HTTPS
+- [FastAPI](./examples/fastapi.md) — personal API server with optional path-based routing
+- [Webhooks](./examples/webhooks.md) — receive GitHub / Stripe / Slack webhooks on your laptop
+
+Each one is a copy-pasteable `run app → add-route → curl` flow.
 
 ---
 

examples/fastapi.md

@@ -0,0 +1,51 @@
+# Expose a FastAPI service
+
+Useful for shipping a quick API from your laptop / home server without renting cloud compute or dealing with Vercel/Fly cold starts.
+
+## App
+
+`main.py`:
+
+```python
+from fastapi import FastAPI
+
+app = FastAPI()
+
+@app.get("/health")
+def health():
+    return {"ok": True}
+
+@app.get("/")
+def root():
+    return {"message": "Hello from a permanent URL"}
+```
+
+## Run + expose
+
+```bash
+# 1. Start uvicorn, localhost-only
+uvicorn main:app --host 127.0.0.1 --port 3000 &
+
+# 2. Tunnel route
+bash scripts/add-route.sh api.example.com http://127.0.0.1:3000 \
+    --comment "Personal FastAPI service"
+
+# 3. Verify
+curl -s https://api.example.com/health
+#   {"ok":true}
+```
+
+## Path-based routing on a single domain
+
+You can host several APIs under one domain by adding paths:
+
+```bash
+bash scripts/add-route.sh example.com 3000 --path "/api/v1.*" --comment "v1 API"
+bash scripts/add-route.sh example.com 3001 --path "/api/v2.*" --comment "v2 API"
+```
+
+`cloudflared` matches first-hit, top-down — `add-route.sh` always inserts above the catch-all `404`, so order is preserved.
+
+## Production hardening
+
+A public URL with no auth is exactly that — public. For anything sensitive, add a [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/applications/configure-apps/self-hosted-apps/) policy on the hostname (SSO / IP allowlist / one-time PIN), and consider a [WAF rule](https://developers.cloudflare.com/waf/) for rate limiting.

examples/gradio.md

@@ -0,0 +1,45 @@
+# Expose a Gradio app
+
+Replace `share=True` (random ngrok-style URL that resets every restart) with a permanent Cloudflare Tunnel URL.
+
+## App
+
+`app.py`:
+
+```python
+import gradio as gr
+
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+# Bind to localhost on a fixed port - the tunnel handles public access.
+gr.Interface(fn=greet, inputs="text", outputs="text").launch(
+    server_name="127.0.0.1",
+    server_port=7860,
+)
+```
+
+## Run + expose
+
+```bash
+# 1. Start the app (foreground or systemd / pm2 / tmux - your choice)
+python app.py &
+
+# 2. Wire up the tunnel route - one time per hostname
+bash scripts/add-route.sh demo.example.com 7860 \
+    --comment "Gradio greeter demo"
+
+# 3. Verify
+curl -I https://demo.example.com/
+#   HTTP/2 200
+#   ...
+```
+
+The URL `https://demo.example.com/` is now permanent — restart the Python process whenever you want; the route stays.
+
+## Tear-down
+
+```bash
+bash scripts/remove-route.sh demo.example.com
+# then delete the DNS CNAME via the Cloudflare dashboard
+```

examples/streamlit.md

@@ -0,0 +1,43 @@
+# Expose a Streamlit app
+
+Streamlit's hosted "Streamlit Cloud" works for many cases, but a local tunnel is faster to iterate on and keeps your data local.
+
+## App
+
+`app.py`:
+
+```python
+import streamlit as st
+
+st.title("Local dashboard")
+name = st.text_input("Name", "World")
+st.write(f"Hello, {name}!")
+```
+
+## Run + expose
+
+```bash
+# 1. Start Streamlit on a fixed port, bound to localhost only
+streamlit run app.py \
+    --server.address 127.0.0.1 \
+    --server.port 8501 \
+    --server.headless true &
+
+# 2. Add the route
+bash scripts/add-route.sh dash.example.com 8501 \
+    --comment "Streamlit local dashboard"
+
+# 3. Verify
+curl -sSI https://dash.example.com/ | head -1
+#   HTTP/2 200
+```
+
+## Notes
+
+- Streamlit websockets work over the tunnel — you don't need any extra config.
+- If you see "Please make sure your network connection is active" in the browser, check that `--server.address 127.0.0.1` is set. Binding to `0.0.0.0` is fine too, but the tunnel only needs `127.0.0.1`.
+- Use `--diff` to preview the change before writing:
+
+  ```bash
+  bash scripts/add-route.sh dash.example.com 8501 --diff
+  ```

examples/webhooks.md

@@ -0,0 +1,57 @@
+# Receive webhooks on your laptop
+
+Most webhook providers (GitHub, Stripe, Slack, Linear, Twilio…) need a public HTTPS URL they can `POST` to. A persistent Cloudflare Tunnel route is the cleanest way to receive them on a local dev machine without spinning up a server.
+
+## Receiver
+
+`webhook_server.py` (FastAPI; same idea works in any framework):
+
+```python
+import json
+from fastapi import FastAPI, Request
+
+app = FastAPI()
+
+@app.post("/webhook/github")
+async def github(req: Request):
+    payload = await req.json()
+    print(json.dumps(payload, indent=2))
+    return {"received": True}
+```
+
+## Run + expose
+
+```bash
+# 1. Start the receiver locally
+uvicorn webhook_server:app --host 127.0.0.1 --port 4000 &
+
+# 2. Add a tunnel route - permanent URL even after laptop restarts
+bash scripts/add-route.sh hooks.example.com 4000 \
+    --comment "Local webhook receiver"
+
+# 3. Point GitHub / Stripe / Slack at:
+#    https://hooks.example.com/webhook/github
+```
+
+## Smoke test
+
+Hit it from your phone or another machine to confirm it's reachable:
+
+```bash
+curl -sS -X POST https://hooks.example.com/webhook/github \
+    -H 'Content-Type: application/json' \
+    -d '{"event":"ping"}'
+```
+
+## Two providers, one domain
+
+Use path-based routing so each provider gets a distinct URL but you only run one tunnel:
+
+```bash
+bash scripts/add-route.sh hooks.example.com 4000 --path "/github.*" --comment "GitHub hooks"
+bash scripts/add-route.sh hooks.example.com 4001 --path "/stripe.*" --comment "Stripe hooks"
+```
+
+## Verify provider signatures
+
+Cloudflare terminates TLS at the edge, so the request body and headers reach your local service unchanged. That means signature verification (HMAC, JWT, etc.) works exactly as documented by the provider — no extra steps.