Skip to content

troupe-daemon open starts the daemon and opens the web app with the loopback WebSocket's port and token after a #; the page takes them off its address bar and keeps them in localStorage, and the loopback admits the linked plane's origin and the page's

Decision 797 · accepted · 2026-10-06 · issue #449

  • One command. troupe-daemon open [--url URL] starts the daemon if none answers, as a client does (Troupe.Protocol.Daemon.ensure_running/1, with this release's own wrapper where RELEASE_ROOT names one, so open starts the daemon it belongs to), waits for the WebSocket entry, and opens the default browser at <web app>#daemon=<ws.port>:<ws.token>. The web app is --url, or the one the plane the daemon is linked to serves at /app/ (where the chart mounts it, Decision 670). Not linked and no --url is a message naming --url, and nothing is started. The plane is not asked where its app is: its discovery document does not say, and open works offline; a plane whose app is elsewhere (plane.appUrl) is --url's. Nothing printed names the token: the address goes to the browser and nowhere else.
  • The origin, with no environment variable. The loopback's default list is now this machine's origins (localhost on any port and the desktop shell's), the origin of the plane in identity.json, and the origins in ws.origins in daemon.json, the last two read at each upgrade (Loopback.admitted/0), since a link or an open comes after the daemon started. open adds the web app's origin to ws.origins (Endpoint.admit_ws_origin/1) before it opens the browser. Kept beside the token it goes with rather than in a file or a setting of its own: a daemon that starts again writes a fresh ws entry without it, so it lasts exactly as long as the token the page was handed, and whoever can write daemon.json can already read the token, so it admits nobody who could not already attach. Not chosen: a protocol command to admit an origin, which widens the protocol for one command whose trust boundary is already this file; a config.yaml key, which outlives the token and is a setting a person did not write.
  • The token is on no command line where another user could read it. On Linux every user can read every process's arguments (/proc/<pid>/cmdline), for as long as it runs, and a browser started with the address keeps it there; the token admits whoever holds it to everything the daemon does as this user. So outside Windows the browser is given open.html beside daemon.json, made 0600 before the address is written into it, which sends it on with a meta refresh (as Jupyter does for its token). Windows shows one user's command lines to no other user, and a .html file there may open in something that is not the browser, so there start is given the address.
  • The exception to "one persisted secret". The GUI kept exactly one secret on disk, the identity provider's refresh token, and held the daemon's token in memory for the tab. The issue asked for sessionStorage; the maintainer chose localStorage, so a reload and a new tab reconnect, and this is that exception, said once here and in the code. Why it is acceptable: the token changes every time the daemon starts, so a kept one is good only until the next start, and a stale one fails and the page says to run troupe-daemon open again. What it costs: while the daemon runs, a script on the page's origin can read it, in any tab and on any page of that origin, not only in the app's tab while it is open.

Governs: apps/troupe_daemon/lib/troupe/daemon/cli.ex, apps/troupe_gateway/lib/troupe/gateway/loopback.ex, apps/troupe_gateway/lib/troupe/gateway/web.ex, apps/troupe_protocol/lib/troupe/protocol/endpoint.ex, clients/gui/apps/desktop/src/shell.ts, clients/gui/apps/desktop/src/hooks.ts, clients/gui/apps/desktop/src/views/Local.tsx