dsh web behind a reverse proxy: let deployments declare the external origin (externalUrl) so DSH_WEB_URL, the surface prompt, and the URL line stop pointing at 127.0.0.1

[mrlfarano]

The setup. dsh web binds loopback (rightly — the GUI is an RCE surface) and a reverse proxy publishes it properly: TLS, a real hostname, verified identity. The natural instance is tailscale serve (https://host.tailnet.ts.net:8443 → http://127.0.0.1:3080), but the same shape applies to Caddy/nginx on a home LAN. With --trusted-host declared, this mostly works today: the SPA loads, WebSockets upgrade, /api passes the browser-trust fence (all verified empirically on v0.1.0-rc.7 + tailscale 1.102.2).

The gap. Everything the runtime narrates about where it lives is hardcoded to loopback (localWebUrl() in dsh-web-app):

• DSH_WEB_URL tells every agent shell the GUI is at http://127.0.0.1:3080 — an origin the remote operator's browser cannot resolve, so any user-facing link an agent or plugin mints from it is dead on arrival;
• the app:web-surface prompt section orients the model the same way;
• the URL line prints only loopback/LAN forms.

In our deployment this is the single largest source of "plugin broke when I went remote": skills that share diagrams minted 127.0.0.1:8765 links; a shared-browser viewer needed a second SSH forward; agents handed users localhost URLs in chat. All inherited from one hardcoded string.

The proposal (implemented, tested). One opt-in config:

- id: web-runtime
  name: '@deepseek-ai/dsh-web-app'
  config:
    externalUrl: https://host.tailnet.ts.net:8443   # + --external-url flag

When set, it becomes the canonical user-facing URL for the prompt section, DSH_WEB_URL, and the URL line (loopback/LAN kept as parenthetical local hints). When unset, behavior is byte-identical to today — the pre-existing web-app tests pass unchanged, and new tests cover both the set and the loader-shaped-undefined paths. The flag validates to a bare http(s) origin at parse time (normalized case, trailing slash stripped; bare hosts, paths, queries, credentials, non-http schemes fail the invocation loudly).

No trust implications: this is narration only. The /api fence is untouched; --trusted-host remains the only way a non-loopback Host passes it.

Tested change: web-app suite 18/18 green (4 new tests), tsc -b clean. Branch: mrlfarano:external-url · diff: compare with master (5 files, +138/−4, tests included).

Happy to rework any part of the shape (config name, flag semantics, URL-line format) — the goal is simply that a proxied deployment stops lying about its own address.

(PR creation appears restricted to collaborators, so posting here per CONTRIBUTING — glad to turn this into a PR whenever the team wants it.)

[zoahdev]

核验成立（当前 main HEAD 99f6f02）：packages/bundle/web-app/src/index.ts 的 localWebUrl 解析到 http://127.0.0.1:<port>（测试直接断言 http://127.0.0.1:4567），DSH_WEB_URL / app:web-surface prompt / URL line 三处都从它来——"一切叙事硬编码 loopback"的描述准确。

补两个设计点：

1. 把"narration only"做成不变量 + 测试，而不是文档承诺

你的 #3210 同一部署里已证明：Host-preserving 代理（tailscale serve）会把客户端提供的 Host: 127.0.0.1:3080 原样转发——特权钉扎在代理后是可伪造的。这意味着将来有人（很可能就是"顺手"）想用 externalUrl 参与信任判定（比如 Host == externalUrl.host → 放行特权方法）时，会把 loopback 绑定的特权边界从"socket 事实"漂移到"客户端可控的 Host"。建议在 web-app 测试里显式断言：externalUrl 设置与否，isTrustedApiRequest 的判定结果完全不变（可以传构造的 externalUrl 跑一遍现有 trust 测试矩阵），把"纯叙事"从设计意图变成被测试钉住的契约——这也和 #3210 的 privilegedIdentityLogins 有硬前置（非 loopback 绑定 + 非空白名单 → load 失败）形成对照：externalUrl 永远不需要这样的前置，因为它不参与判定。

2. 给 agent/插件同时暴露 loopback 提示

DSH_WEB_URL 指向 tailnet URL 对"给用户看的链接"正确，但宿主进程内跑的工具（比如本地浏览器、localhost-only 服务）在没有 tailnet 路由的机器上仍需要 127.0.0.1。建议除了 DSH_WEB_URL（canonical），再暴露一个 DSH_WEB_URL_LOCAL（或把 loopback 作为第二个 env）——UI 的"parenthetical local hints"只解决人看的叙事，agent 和插件读 env 时两个都得能拿到，避免又一轮"plugin broke when I went remote"。

其余部分（parse-time origin 校验、默认行为不变、18/18 测试）都很干净，支持进仓库。