From 7712bacb50954389dd2d24c7a21aa947e4829783 Mon Sep 17 00:00:00 2001 From: lntvan166 Date: Fri, 21 Aug 2026 10:18:04 +0700 Subject: [PATCH] docs: the tunnel is the feature, not a footnote MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `paddock tunnel` is what makes paddock worth installing — the dashboard on `127.0.0.1` is only half of it — and the README had it third in the install steps, after the detached verbs, and described in "from your phone" as "the shortcut" beneath the durable Cloudflare Access setup. So the one command that demonstrates the product read like an aside. It now comes directly after the first `paddock`, as the step to take next, and it opens "from your phone" with the Zero Trust setup behind it as the answer for anything lasting. A feature bullet names it too. Two things the ordering has to say out loud, both verified against the code rather than assumed: - `paddock tunnel` SERVES the dashboard itself, so it refuses to start beside a running instance — its preflight checks for one. The README now says to `ctrl+c` the foreground `paddock` first, and that a detached `paddock start` needs `paddock stop`. Following the old order landed on a refusal. - The pairing code is NOT one-time, which the README claimed in three places. `Pairing.attempt` mints a session on a correct code and leaves the code standing: it is valid for CODE_TTL_MS (10 minutes) and then rotates, pairs any number of devices inside that window, and burns early only after MAX_ATTEMPTS (5) WRONG guesses. "One-time" invites the reader to treat a leaked code as spent, when for ten minutes it is a password. Stated as what it is, next to the warning about the URL being public. The security framing keeps its prominence rather than being softened to sell the feature: a quick tunnel cannot have Access in front of it, the code is the only gate there is, and the URL is public until it is closed. README only — no code, no version bump. Co-Authored-By: Claude Opus 5 --- README.md | 66 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 47 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 524e2b6..cddc169 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,8 @@ walk back and look. - **answer** — the agent's own option labels, and what Enter will commit before you tap it - **notify** — a Telegram message when an agent needs you, sent only once the state has held, with mute and a per-agent cooldown. [settings →](docs/settings.md) +- **reach it in one command** — `paddock tunnel` publishes a temporary URL + gated by a short-lived pairing code. No DNS, no inbound port, nothing to configure - **install as an app** — Add to Home Screen gives it an icon and no browser chrome - **cheap to watch** — adaptive polling, and only changed lines on the wire @@ -80,24 +82,35 @@ then start it where herdr is running: paddock ``` -`ctrl+c` stops it. To keep it running after you close the terminal: +`ctrl+c` stops it. It serves on `127.0.0.1` only, which is what the next step +is for. + +**Do this next — it is the thing paddock is for.** `paddock tunnel` serves the +dashboard *itself*, so `ctrl+c` the one above first, then: ```bash -paddock start # detached -paddock status # is it up? -paddock stop +paddock tunnel ``` -To reach it from your phone without configuring anything first: +That publishes a temporary public URL and a pairing code, and prints both. Nothing to configure, no DNS, no inbound port: open the URL on your +phone, type the code once, and you are watching the same agents from the sofa. +`--for 2h` bounds how long it lives; `ctrl+c` ends it. + +It is a try-it path, not a deployment. A quick tunnel cannot have Cloudflare +Access in front of it, so that pairing code is the only gate there is, and the +URL is public until you close it — [from your phone](#from-your-phone) has what +that does and does not protect, and the durable setup. + +To keep paddock running after you close the terminal: ```bash -paddock tunnel +paddock start # detached +paddock status # is it up? +paddock stop ``` -That publishes a temporary public URL gated by a one-time pairing code, and -prints both. It is a try-it path, not a deployment — see -[from your phone](#from-your-phone) for what it does and does not protect, and -for the durable setup. +`paddock tunnel` serves the dashboard itself, so it refuses to start beside a +detached instance — `paddock stop` first, or run the tunnel in its place. `paddock update` upgrades it; paddock never updates itself unasked. `paddock --demo` runs it with synthetic agents and no herdr. @@ -116,16 +129,31 @@ says so and the dashboard shows a dismissable banner. ## from your phone -paddock stays on `127.0.0.1`. Put an authenticating tunnel in front — a -[Cloudflare Tunnel with Zero Trust Access](docs/deploy-cloudflare.md) dials -out, so no inbound port is opened and the identity check happens before any -request reaches paddock. +Start here. One command, nothing configured: + +```bash +paddock tunnel +``` -`paddock tunnel`, from the install steps above, is the shortcut: a temporary -Cloudflare quick tunnel gated by a one-time pairing code. It is a try-it path, -not a deployment — a quick tunnel cannot have Cloudflare Access in front of it, -so that code is the only gate there is, and the URL is public until you close -it. `--for 2h` bounds how long it lives. +A temporary Cloudflare quick tunnel, gated by a pairing code — both printed in +the terminal. It dials **out**, so no inbound port is opened and nothing on your +network changes. Pair the phone once and the session lasts as long as the tunnel +does. `--for 2h` bounds how long it lives. + +The code is good for **10 minutes**, then it rotates; five wrong guesses burn it +early. It is not single-use, so anything that can read it inside that window can +pair too — treat it like a password for the length of that window, not like a +receipt you have already spent. + +Know exactly what that is, though: a try-it path, not a deployment. A quick +tunnel **cannot** have Cloudflare Access in front of it, so the pairing code is +the only gate there is, and the URL is public until you close it. Close it when +you are done rather than leaving it up. + +For anything lasting, paddock stays on `127.0.0.1` and you put an +*authenticating* tunnel in front: a [Cloudflare Tunnel with Zero Trust +Access](docs/deploy-cloudflare.md) also dials out, and the identity check +happens before any request reaches paddock at all. Then **Share → Add to Home Screen**, and it is an app: its own icon, no browser chrome, and it opens where you left off.