phone-tunnel-pool
一键式 Cloudflare 快速隧道池，用于 dsh Web GUI——通过二维码从手机访问，支持自愈式生成机制和 chase service worker。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:iimaguest/phone-tunnel-pool#4cbeedb31a8d3e446d57c6a97864d1e00b5afd89
Phone Tunnel Pool 以 phone-tunnel-pool 发布，当前版本为 0.3.35。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English | 简体中文
Enable/disable a self-healing Cloudflare quick-tunnel pool for
http://127.0.0.1:3080 (the DeepSeek Harness web GUI) from a floating widget
with a scannable QR code. One scan from your phone, and the pool keeps
itself alive:
Extra: the daemon runs detached and adopts across dsh web restarts, so
the same URL, password and QR stay valid until you click Disable — no
re-scan (an OS reboot still costs one fresh scan; a named tunnel removes even
that — see PLAN.md §7).
# install (from this public repo)
dsh plugin --profile web add github:iimaguest/phone-tunnel-pool
dsh web # the GUI shows a floating 📱 widget (bottom-right)
# uninstall (one command — removes the dependency AND the dsh.profile.bundles layer)
dsh plugin --profile web remove phone-tunnel-pool
dsh web
After install: open the widget → Enable → scan the QR with your phone
camera. Install/remove reconcile dsh.profile.bundles against the installed
state automatically — never edit ~/.dsh/profiles/web/package.json by hand;
a stray bundle entry with no matching dependency is exactly the kind of state
that fails profile boot ("cannot resolve profile bundle").
| What | Needed? | Who provides it |
|---|---|---|
dsh web running on its default port 3080 (DSH_TARGET_PORT to override) | required | you (the plugin tunnels to it) |
cloudflared binary on PATH | required | you — brew install cloudflared (or apt/dnf/Chocolatey, or set DSH_CLOUDFLARED to the existing binary) |
| Node.js runtime | required | dsh itself — no separate install (the daemon reuses dsh's node) |
python3 + qrcode package | optional | you — pip install qrcode; without it the widget shows URL + login instead of a scannable QR |
caffeinate | optional | macOS ships it; skipped elsewhere |
| PowerShell | optional | Windows ships it — used only for process cleanup on Windows (no pkill there) |
| Outbound network | required | cloudflared → Cloudflare edge on 443/7844 (no inbound port needed) |
The widget preflights these on dsh web start and shows a yellow warning
line (with the exact fix, e.g. brew install cloudflared) before you even
click Enable; the daemon also fails fast with a readable error if cloudflared
is missing at Enable time, and refresh in the popup re-checks everything —
a stale error clears once the prereqs pass.
The feature flag set is version-gated on cloudflared --version:
2024.6+ enables the opt-in post-quantum handshake (DSH_PQ=1), 2024.8+ adds
--management-diagnostics=false; older builds (apt/dnf packages) get a
reduced, compatible flag set.
Platforms. macOS, Linux and Windows (Windows uses PowerShell for process
cleanup; caffeinate is macOS-only and silently skipped elsewhere). The
daemon's state file and log live in the per-OS temp directory
(os.tmpdir()); the widget settings file (iptunnel-settings.json) lives in
~/.dsh.
dsh web on a phone, reached through the tunnel pool
Tunnel pool widget: a phone tunnel enabled with a live pool of generations
Live hostnames, credentials and the QR are blurred out in these shots.
dsh web GUI <-- /iptunnel routes -- auth proxy (127.0.0.1:3090)
│ Basic + session cookie,
│ Host rewrite to 127.0.0.1:3080
│ (the GUI's browser-trust fence)
▼
cloudflared A ─ to ─ auth proxy ───────────────────────────────────┐
cloudflared B ─ to ─ auth proxy ───────────────────────────────────┤ (tunnel daemon
... new generations ... ────────────────────────────────── │ manages all)
Files: lib/index.js (host API: enable/disable/adopt, state + QR SVG routes),
lib/daemon.mjs (detached pool brain: spawn, probe, rotate, retire, respawn),
cf-auth-proxy.mjs (public /iptunnel/* service paths + Basic auth +
watchdog injection + credential handoff), iptunnel-sw.js (chase service
worker), iptunnel-watchdog.js (open-tab watchdog), lib/client.js
(widget), verify.sh (end-to-end audit). PLAN.md = full spec + edge cases;
NOTES.md = engineering history.
dsh 0.2 moved web auth into the connection service: the desktop URL carries a
per-process launch token (http://127.0.0.1:3080/?token=<secret>), a valid
token exchange mints a signed browser-session cookie, and every request with
neither gets 401. The tunnel path is phone → trycloudflare → this proxy →
the GUI, and a phone can never learn a token that only exists in the desktop
process output — so on 0.2 the tunnel answered 401 all the way down.
The fix (0.3.35): the plugin reads the token through the connection service's
public authenticatedUrl() API and hands it to the proxy — via the daemon
environment on a fresh enable, and via POST /iptunnel/__ctl/launch-token
whenever a surviving daemon outlives a dsh restart (the token is
per-process, the daemon is deliberately not). The proxy exchanges the token
against the GUI once, holds the resulting session cookie, and stamps it onto
every forwarded request and websocket handshake — re-minting on an upstream
401 and on every token push. A phone therefore presents only this proxy's
Basic auth, exactly as before, and the launch token never reaches cloudflared's
environment, the QR, or the published URL. On a dsh without the gate the token
is empty, every new code path no-ops, and forwarding is byte-identical to the
pre-0.2 behaviour (test/launch-token.test.mjs pins all of this against a
mock origin, including rotation).
cloudflared per live
generation. Default ceiling: 4 generations × 2 = 8 tunnels (a busy pool
runs all of them; idle generations retire on their own after 60 min).DSH_MAX_GENS=2 (≤4 tunnels), DSH_IDLE_MS=1200000
(retire after 20 min idle), DSH_PQ — post-quantum handshake is opt-in
(DSH_PQ=1) because it costs CPU per connection; without it the tunnel uses
the classic handshake.caffeinate (macOS) is off by default; turn it
on in the widget ("Keep machine awake while enabled") or via
DSH_CAFFEINATE=1 — it applies on the next Enable (and lets the display
sleep — -i only, no screen-on drain). Without it, an idle MacBook may
sleep and the pool goes quiet until it wakes.0600 state file under the OS
temp dir so the tunnel survives a dsh web restart; that file is deleted on
disable.)/iptunnel/* service paths (health, sw-config, sw.js, entry, watchdog.js,
telemetry, preauth) are public by necessity — browsers fetch service
workers without credentials; they carry hostnames and pool liveness only.
The credential handoff (/iptunnel/preauth) mints a cookie only for a
caller presenting the valid password; it never echoes anything.window.__ptAuth is injected only into HTML the proxy has authenticated.Apache-2.0 — see LICENSE. Third-party code:
cloudflared (distributed by
Cloudflare), the Python qrcode library — used at runtime, not vendored.