Direction: a text-mode client (wmux attach) — offloading the work to a VPS, and two people on one session

[p-poppe]

A direction question, not a feature request — and one I'd rather ask badly than not ask, because the answer might be "deliberately out of scope" and that is useful to know.

Has a text-mode client ever been on the table? A wmux attach that joins the same daemon sessions from a plain terminal over SSH, with the GUI as one of several front-ends rather than the only one.

What already exists, so this isn't asking for a rewrite

I want to be accurate about the gap, because most of the machinery seems to be there already:

• the daemon owns the sessions and outlives the window (I have measured that rather more thoroughly than I intended, in [Bug]: In-app update never installs — the waiter aborts on wmux's own surviving processes, and the UI keeps offering "Install now" #980)
• wmux web serves them over HTTP
• remote workspace attach joins another machine's sessions
• the prefix keybinding config is already tmux-shaped

So the missing piece is narrow: a client that renders in a terminal rather than in Electron. Everything else — session ownership, ring buffers, hook signals, the MCP surface — looks like it would not need to know.

Why I keep wanting it

Three concrete situations from the last month, all on Windows 11 with 11 workspaces and several agents running:

1. The laptop is the wrong machine to be doing this on. Electron plus a dozen agent panes plus their MCP servers is a real load; when I'm on battery or on a plane I want the work to continue on a box that isn't the one I'm carrying. A VPS or a desktop at the office keeps the daemon, the agents keep grinding, and I attach with whatever thin thing I have to hand. Today the work is pinned to the machine that renders it — which is backwards, because rendering is the cheap part.

2. Someone else needs to see the same session, not a screenshot of it. This week a colleague and I spent a while going back and forth over what a workflow had actually done — the kind of thing that is thirty seconds if two people are looking at the same live pane, and thirty messages if they aren't. tmux attach culture solved this a long time ago: same session, two humans, no screen sharing, no "can you paste that again". wmux web is presumably the nearest thing today, and maybe that IS the answer — if so I'd love to know how you think about it, because I have not used it in anger yet.

3. Survival when the front-end is the problem. Twice I have had a session I wanted to reach while the GUI itself was in a bad way (renderer wedged, and separately a GPU-ish repaint mess). A text client attaching to a daemon that was fine the whole time turns "restart everything and hope the sessions come back" into "attach from another window".

The part I expect to be hard

I don't want to pretend this is small. Rendering is the app's core: xterm.js in a browser context, mouse protocols, the theme system, the sidebar as a first-class surface. A terminal client means either a second renderer or accepting a deliberately reduced surface — and then the question becomes which parts are the product and which are chrome. Notifications, approvals, the Deck, the browser panes — some of that has no meaning in a text client, and deciding that is a product call, not an engineering one.

Which is why this is a question rather than a proposal. If the answer is "the GUI is the product, wmux web is the remote story, a TUI client is out of scope" — that is a perfectly good answer and I'll stop wishing for it. If it is "interesting but not now", knowing the shape you'd want (thin renderer over the existing daemon protocol? a --headless mode plus an existing multiplexer? something else?) would at least tell me whether the idea is worth anyone's evenings.

For what it's worth, the reason I'm asking rather than shrugging: the daemon surviving on its own is already the hard half, and you've built that.

[openwong2kim]

Not out of scope — but the three situations in your post have three different
answers, and only one of them is a gap.

Have you tried remote workspace attach?

Genuinely asking, because the post doesn't mention it and it's the closest thing
to what you're describing. Titlebar + → "Attach remote workspace…". The
remote box runs wmux web --tailscale --allow-input; you pair with the
8-character code from its Web popover, and its workspaces appear in your local
sidebar — live, typeable, in your own wmux window.

That's your "desktop at the office" case today: the agents grind there, the
laptop only renders. Two people on one session falls out of the same mechanism
(#815 made those grants per-device, so you can revoke one PC without cutting
everyone off). And because the web server runs inside the daemon rather than
in the app, it's also your third case — a wedged renderer doesn't take the
sessions with it.

The rough edge you'd hit within a minute: mirrored panes keep the remote's
grid and the local side only shrinks the font to fit, so a pane narrower than
your local box letterboxes and long lines clip at the remote's width (#905,
closed not-planned). That's a deliberate trade — geometry has exactly one owner,
so there is no size fight to referee.

If you have used it and it still didn't answer the need, that is the most useful
thing you could tell me, because it changes what the gap actually is.

The VPS case is the real gap — and it isn't the renderer

The daemon is only ever spawned by the Electron main process. There is no
wmux daemon verb. On a headless box you cannot get a daemon at all, so a text
client would have nothing to attach to; conversely a headless daemon alone gets
you the VPS story with nothing but a browser tab. Lifecycle first, client second.

The premise worth inverting

You called rendering the hard part. For a terminal client it is the part that
disappears. The web client carries xterm.js because a browser can't display
ANSI — a terminal can. The stream already ships raw PTY bytes (base64 over SSE)
plus an initial snapshot event, so the shape is:

GET /api/stream → base64-decode → stdout
stdin in raw mode → POST /api/input
SIGWINCH → POST /api/sessions/:id/resize

No second renderer, no grid model, and auth, Tailscale fronting and multi-viewer
come along for free. (The desktop's per-session byte pipe is not the road —
it's single-consumer, and a second client would evict the GUI.)

What's actually hard is size, not pixels

#769 implemented exactly this arbitration between desk and phone and was parked
by owner decision, not by CI: no hysteresis (a 20-second alt-tab while the phone
holds the pane hard-wraps that window of scrollback at phone width, permanently)
and no indication to the desk that something took the size. A terminal attacher
makes that a third claimant.

But remote attach already shows the escape hatch — single geometry owner, viewer
letterboxes, essentially tmux's aggressive-resize off. That turns the hardest
problem into a product decision already made once. Multiplexer chrome (pane
switching, the Deck, approvals) can be punted the same way: one pane at a time,
and the outer terminal owns layout.

One thing not to be misdirected by

#814 built remote execution over SSH — declare kind: "ssh" in wmux.json and a
pane runs on a remote box. It's closed unmerged for lack of demand evidence, and
it is not this: it keeps the daemon, the Electron process and the MCP servers
on your laptop and sends only the pty over the wire — precisely the load you want
to stop carrying.

So: not "the GUI is the product, go away." It's "remote attach answers 2 and 3
today, and 1 needs a headless daemon lifecycle before a text client is even
meaningful." If you want to spend evenings on something, that lifecycle is the
half that unblocks everything else.

[p-poppe]

Thanks for the detailed breakdown — that clarified a lot. To close the loop:

We haven't actually tried "Attach remote workspace" yet for the team-collaboration case — will do, and report back if it doesn't fully cover it. From your description it sounds like it does.

The VPS/laptop-offload case is the one we actually care about, and we agree with your framing: the daemon-lifecycle gap (wmux daemon can currently only be spawned by the Electron main process) is the real blocker, not rendering. We dug into spawnDaemon() in src/main/daemon/launcher.ts to see how big that gap actually is, and it looks smaller than we expected — the daemon entry point (src/daemon/index.ts) is already plain Node with zero Electron imports (the module comment even says so explicitly). The only Electron-specific bits in the spawn path are app.getAppPath() (locating the bundled daemon script) and app.getVersion() (stamped for the B′ replacement staleness check) — both trivially replaceable with CLI-context equivalents (process.cwd()-relative resolution, package.json version). Everything else — node path detection, spawn(), the readiness poll — is already OS/GUI-neutral.

Two things we found while poking around this, in case they're useful before anyone commits to a direction:

1. Appearance carries over for free. Theme/palette settings live in the local renderer's session.json, not the daemon — so a laptop attaching to a VPS-hosted daemon would look exactly like it does today, no extra work needed there. Rendering was never really the hard part, as you said.
2. One A2A path is Electron-coupled the same way the daemon spawn is. ClaudeWorker (src/main/a2a/ClaudeWorker.ts) — the "run a background A2A task without occupying a visible pane" path — imports BrowserWindow directly and pushes status via sendToRenderer. It'd need the same kind of decoupling, or callers would just fall back to running the task in a real daemon-native pane (which already works fine headless). Not a blocker for the main idea, just a secondary thing that'd surface once someone actually tries this end to end.

If you're fine with the direction — a wmux daemon (or similar) headless-start verb, reusing the existing spawn/readiness logic minus the two Electron calls — we'd like to give it a shot as a PR. Let us know if you'd rather shape the CLI surface yourself first (flags, where it should live, whether it should also handle first-run setup like wmux web does), or if there's prior art/an approach you already have in mind that we'd just be duplicating.

[openwong2kim]

Green light — go ahead. You asked whether I'd rather shape the CLI surface first, so here is the direction I'm currently thinking. Treat it as a reference, not a spec: you've been right about the code so far, and where the code disagrees with any of this, say so in the PR and we'll sort it out there.

The v1 shape I have in mind

wmux daemon start | stop | status, and probably nothing else — no first-run wizard, no web setup (wmux web already owns enable/pairing/TLS and talks to the daemon directly), no service management. My instinct is that systemd wants a docs snippet, not a flag. If you find yourself needing a fourth verb, that's worth a comment before building it.

The one preference I'd hold onto: extraction over duplication

If there's a single thing I'd ask for, it's that the spawn path doesn't fork: pull the spawn/readiness chain out of src/main/daemon/launcher.ts into a shared module both the Electron main process and the CLI consume. Two copies of that code would drift apart, and the spawn path is where our nastiest lifecycle bugs have lived (#537, #980) — so it's also the part I'll read most carefully.

The file is already mostly shaped for it, for what it's worth:

• pollDaemonReady() is already exported and fully dependency-injected (done for unit tests) — it should move as-is.
• readPipeNameFromFile, the DAEMON_EXIT_ALREADY_RUNNING split-brain handling, and the stale-PID guards are Electron-free at function level; only the module-level import { app, dialog } pins the file to main.
• The stale-PID recovery dialog already has a headless path — WMUX_NO_DIALOG=1 suppresses it and falls back to the throw. The CLI would just take that branch unconditionally.

Reuse pointers — most of the verb already exists as RPC

You likely don't need to write a kill path or a status probe:

• status ≈ daemon.ping on the daemon control pipe. The CLI already knows how to reach that pipe without the app — sendDaemonStringRequest in src/cli/client.ts, and the comment block above it explains the resolution order (wmux doctor was built on exactly the premise "diagnose the daemon even when the app is dead").
• stop ≈ daemon.shutdown — the daemon's own suspend-everything RPC, the same one the stale-daemon auto-replacement uses. I'd lean on that rather than a new termination path; it's the one that has been through the wars.

So the genuinely new code is roughly: src/cli/commands/daemon.ts, the extraction refactor, and script resolution.

My current thinking on the two questions you couldn't decide alone

Version stamp. I'd stamp ENV_KEYS.SPAWNED_BY_VERSION with the CLI's own package.json version, unconditionally. The trap to know about: unset, the daemon falls back to an 'unknown' sentinel and the staleness gate reads that as "positively old" — the first GUI to connect would replace your daemon on sight. With a real version stamped, mixed CLI/GUI versions fall into the existing auto-replacement semantics (release-to-release comparison, session-preserving), which seems like the right behavior to me: a newer GUI attaching to a VPS-started daemon may upgrade it, and sessions survive that by design.

Where the daemon bundle comes from. For v1 I'd resolve the script the way the launcher does, minus app.getAppPath(): try the installed app's resources layout if one is findable, else dist/daemon-bundle/index.js relative to a checkout. That makes v1's headless story "install the app (Linux .deb/.rpm/.AppImage are built on every release) or build the repo, then wmux daemon start". A standalone headless distribution artifact is a real question, but a separate one — I'd rather not couple your PR to it.

Things I'd punt

• ClaudeWorker — agree with your read: not a blocker, callers fall back to daemon-native panes. Leave it.
• Renderer-routed surfaces (browser panes, a few MCP tools) won't function against a headless daemon. Expected; a line in the docs is enough for v1.

House rules for the PR: English throughout, no version bump, changelog entry as a fragment in changelog.d/<pr-number>.md (see the README there). Looking forward to it — and thanks for doing the spelunking before asking. It made this an easy yes.

[p-poppe]

Closing the loop: #1019 merged (wmux daemon start | stop | status), built to the shape you outlined — extraction into daemonLauncherCore.ts shared by the Electron launcher and the CLI, status/stop riding the existing daemon.ping/daemon.shutdown RPCs, version stamped from the CLI's own package.json. Thanks for the precise spec, it made this a much smaller PR than it could have been.

Not released yet — still sitting on main ahead of the next tag — so we haven't run the actual "spawn it headless on a box, attach from the laptop" test yet. Will report back once we have, since that's the real proof this closes the gap rather than just adding a CLI verb.

One thing worth flagging here rather than leaving buried in review threads: #1025 (the cmdline-identity hole in killVerifiedDaemonPid) and the #1027/#1028 back-and-forth are downstream of the same code #1019 touched, and the split-brain risk you called out in #1028 is exactly the class of bug you said this module earns the most scrutiny for. We're not picking it up unprompted given how sensitive that path is — flagging it here in case it's useful to have it visible next to the discussion that started this thread.

[p-poppe]

Ran the real end-to-end test we said we'd report back on: installed the .deb on a fresh Hetzner VPS (Ubuntu 24.04, no GUI, ever), ran wmux daemon start there, tunneled wmux web over SSH, and paired it from the desktop app via "Attach remote workspace" — pairing itself worked cleanly, the remote host showed up in the paired-hosts list on the first try.

Where it stopped: the paired host showed "no workspaces" and stayed that way, including after creating a pane directly against the daemon's own web API (POST /api/sessions, no GUI involved). Traced it — GET /api/workspaces builds its list from WMUX_WORKSPACE_ID on each pane's env, which only the app's main process stamps at spawn. A pane created without going through main has no such env, so it's invisible to that endpoint even though the daemon correctly reports it as a live session. And rejectWorkspaceId in the same file won't let you supply that id yourself unless a pane already carries it — by design, to stop a paired phone from impersonating a workspace it was never granted. So there's no path today to create the first pane of a new workspace against a daemon that has no main process anywhere — only to add a sibling pane to a workspace the GUI already created.

Everything else in the #1019 lifecycle held up under a real test, for what it's worth: daemon start/stop/status all worked headless, spawnedByVersion correctly read "unknown" on the real installed layout (not "0.0.0" — the #1019 review fix, confirmed live) rather than getting the daemon killed on the first connect.

Feature ask this points at: "New workspace" in the desktop app could offer local vs. one of your already-paired remote hosts, and creating one on a remote host would be the thing that finally stamps a workspace id on that host for the first time — closing exactly this gap. Not proposing an implementation, since I don't know how you'd want the id minted/that first pane's ownership handled remotely — just flagging that this is the concrete next wall, found by actually running it rather than reading the code.

[p-poppe]

Dug into whether "New workspace → local or one of your paired remote hosts" is a scoped fix or a bigger call, since it touches rejectWorkspaceId's security boundary directly. Found something worth surfacing before anyone (including me) codes it: there are two defensible designs here, and this codebase has already gone back and forth on the underlying question once.

Credential path confirmed first, since it changes the risk picture: the desktop's "Attach remote workspace" → paste-the-wmux web-URL flow (what we used in the VPS test) stores the operator bearer token directly (RemoteHost.token, "bearer token parsed from the pasted wmux web URL" — src/shared/remoteHosts.ts), and RemoteHostClient sends it as Authorization: Bearer. So that flow already authenticates as { kind: 'operator' } in WebTerminalServer, full stop — it's not going through the phone-style device-pairing/rejectWorkspaceId-impersonation path at all today. The code-based pairing flow (REMOTE_HOSTS_PAIR) is the one that mints a device-scoped credential instead.

The actual gap is rejectWorkspaceId (src/daemon/web/WebTerminalServer.ts): POST /api/sessions accepts a caller-supplied workspaceId, but the check only accepts one that's already stamped on a live pane — there's no way to mint the first one. Its own doc comment says this replaced an earlier, looser version on purpose ("a deliberate decision that went the other way ... 'I cannot verify this' must not resolve to 'so I will accept it' for a value that becomes an identity").

Two ways to close it:

• A — gate on principal.kind === 'operator'. Only the (already highest-trust, whole-daemon-control) operator credential can mint a brand-new id; a paired device still can't. Matches the "Attach remote workspace" path we actually used.
• B — gate on mayInput(principal) (the same grant handleSessionCreate already requires for spawning at all), consistent with the comment two methods above it: "Both credential forms may call it ... the operator token is not more trusted here, only differently revocable, so gating on the credential FORM ... would be a boundary that is not one." A device with allowInput: true can already spawn an arbitrary shell into any existing workspace (full arbitrary execution) — B says minting a not-yet-live id isn't meaningfully more dangerous than that, and the "impersonation" threat the doc comment warns about doesn't apply to an id nothing is running under yet.

I don't think I should pick between A and B myself and open a PR — A is the more conservative reading and matches how we'd actually use it from the desktop, but B is what the codebase's own stated philosophy right next to this code argues for, and I'd rather not quietly relitigate that call inside an unrelated feature PR. Whichever one you'd pick, the desktop-side half (host-picker on "new workspace", wiring into RemoteHostClient) is straightforward once the server contract is settled — happy to build that part once you've said which way this should go, or both together if you'd rather just decide it yourself.

[openwong2kim]

A — and thank you for refusing to pick it yourself. Writing the answer down surfaced the argument that decides it.

B is not a relaxation, it is a deletion. rejectWorkspaceId lives inside a route that is already gated on mayInput. Gating the mint on mayInput therefore admits exactly the set of callers the route already admits — the existence check becomes unreachable code. And because the daemon has no registry, it cannot distinguish "a brand-new id" from "a genuine workspace whose every pane happens to be closed". So for every input-granted device, B reduces the check to shape-only — precisely the previous behaviour that comment says was replaced on purpose. "Not live" is not "nonexistent": channel grants and the app-side filing of a dormant workspace are real things a minted id would claim, and the dormant window is exactly the one the existence check exists to close.

On the philosophy you quoted: that comment is about execution capability — allowInput already IS arbitrary execution, so form-gating spawn would add a boundary that isn't one. Minting a workspace id is an identity operation: it decides how a pane is filed and scoped, not what it can run. For typing, the operator token is "only differently revocable"; for identity it genuinely is the desktop's own credential. A just says the thing that owns the workspace registry is the thing that may extend it.

Server contract I'd take: keep the shape check for everyone; relax only the existence check when principal.kind === 'operator'. Mint the uuid on the desktop side — the renderer owns the registry today, so the server accepts an operator-supplied new id rather than generating one. No separate POST /api/workspaces mint endpoint: if it records anything it invents the registry the daemon deliberately doesn't have, and if it doesn't, it is the same relaxation with more API surface.

Stated limitation, so nobody later mistakes A for more than it is: this is an audit-and-revocability boundary, not a hard one — a shell on the daemon's own host can read the operator token, and a phone-only headless bootstrap still needs the operator credential once. Both deserve a line in the rejectWorkspaceId comment when this lands.

Happy to see the desktop half (host picker on "New workspace", RemoteHostClient wiring) come from you — the server-side gate is small enough to land in the same PR. House rules as before: English, no version bump, changelog fragment in changelog.d/<pr-number>.md.