Proposal: Windows desktop application and installer for Vibe-Trading

[QCYTSN]

Hi Vibe-Trading maintainers — @warren618,

I have built a working Windows desktop prototype for Vibe-Trading and would like to ask for your direction before preparing formal pull requests or publishing it more broadly.

The current temporary name is Vibe-Trading Desktop Community. It is explicitly presented as an unofficial community Alpha, not an official HKUDS application.

Source and documentation:

https://github.com/QCYTSN/vibe-trading-desktop-handoff

Overview

This is not a rewrite of Vibe-Trading.

It preserves the existing React interface and Python/FastAPI agent architecture, while adding an Electron-based desktop host, an embedded Python runtime, Windows packaging, local process management, safer credential storage, and several desktop-focused usability improvements.

The current prototype targets Windows 10/11 x64.

Implemented work

The desktop version currently includes:

• automatic startup of the existing Vibe-Trading backend;
• a native desktop window loading the existing same-origin Web UI;
• a random loopback port and per-launch authentication secret;
• backend health checks, startup diagnostics, log capture, and controlled shutdown;
• single-instance handling and cleanup of the embedded Python process tree;
• an NSIS Windows installer with an isolated Python 3.12 runtime;
• credential storage using Electron safeStorage and Windows user-level encryption;
• a first-run disclosure covering local data, credentials, unofficial project status, model limitations, and financial risk;
• improved provider model discovery and model selection;
• display of the actual configured provider, model, reasoning setting, and response duration;
• provider-returned model metadata when available;
• corrected reply-copy behavior and route preloading;
• a registry-driven IM channel management interface for the adapters already supported by Vibe-Trading;
• the existing WeChat QR/pairing path;
• a draft Windows GitHub Actions build and release workflow;
• a manual GitHub Releases update-check foundation.

The desktop layer keeps the backend bound to 127.0.0.1 by default and does not intentionally bypass the existing live-trading authorization, mandate, confirmation, halt, or audit boundaries.

Validation completed

The following checks have been completed on the development machine:

• 282/282 frontend tests passed;
• 57/57 focused backend settings, channel, QVeris, and runtime-metadata tests passed;
• embedded-backend smoke testing passed;
• interface smoke testing covered 68 OpenAPI operations, the main UI routes, static assets, SSE ticket behavior, and configuration paths;
• the packaged desktop application starts the backend, loads the interface, exits normally, and leaves no packaged Electron or Python process behind;
• provider/model discovery, chat completion, tool-call visibility, detailed replies, and task completion were manually exercised with a live API;
• an earlier installer build was installed and launched successfully in a clean Windows 11 virtual machine.

Current limitations

I also want to be transparent about the remaining work:

• the exact final 0.3.0 installer still needs another clean-Windows regression test;
• the updater has not completed a real 0.3.0 -> 0.3.1 test;
• the current installer is unsigned;
• not every optional IM adapter has been tested end to end with a real account;
• dependency-license, bundled-binary, and SBOM review still need to be completed;
• installer size, cold start, and first-use performance need further optimization;
• macOS and Linux packaging have not been implemented.

Source-history limitation

The original implementation was developed from an extracted Vibe-Trading 0.1.11 source snapshot without its .git history.

The public repository therefore contains a path-preserving source overlay for architecture review. It is not presented as a clean patch series and should not be applied blindly to the current upstream main branch.

If the project is interested in the desktop version, I am willing to reconstruct the work in a real fork against a known current upstream commit and split it into focused, reviewable commits with the required DCO Signed-off-by: trailers.

A possible review order would be:

1. independent Electron shell and backend lifecycle management;
2. Windows packaging and release workflow;
3. secure credential integration;
4. minimal backend APIs and runtime metadata;
5. frontend model, chat, desktop, and channel interfaces;
6. tests and documentation.

Guidance requested

Before rebuilding the work as formal pull requests, could you please advise on the preferred direction?

1. Should a desktop version live under a desktop/ directory in the main repository, in a separate HKUDS companion repository, or remain an independent community project?
2. Would you prefer to review the independent Electron shell first, before the supporting frontend and backend changes?
3. Is the temporary name Vibe-Trading Desktop Community acceptable during review?
4. Is temporary use of the existing Vibe-Trading icon acceptable for an explicitly unofficial prototype?
5. If an official desktop distribution is desirable, who should own the Windows signing identity, GitHub Releases repository, and updater feed?
6. Which optional IM-channel dependencies should be included in the default Windows runtime?
7. Is the existing personal WeChat QR/pairing integration an intended supported surface for a desktop distribution?

I also have an unsigned Windows installer available for optional testing, together with its SHA-256 checksum. I have not made the installer the primary review material because the source, architecture, validation status, and known limitations should be reviewed first.

I am willing to adapt the implementation, branding, repository structure, package scope, and pull-request breakdown to the direction preferred by the maintainers.

Thank you for building and maintaining Vibe-Trading.

[warren618]

Thank you for presenting this so carefully, and sorry for the slow reply. The source-first handoff, the explicit unofficial status, the validation ledger, and the known-limitations section made this far easier to evaluate than most proposals of this size — that's appreciated.

We'd like to take it upstream. Please do prepare pull requests against this repository and we'll review them properly.

To keep the review tractable, could I ask you to split it rather than sending one large PR?

1. PR 1 — desktop shell and backend lifecycle only. Everything new under desktop/: the Electron host, the random loopback port and per-launch auth secret, health checks, startup diagnostics, log capture, controlled shutdown, single-instance handling, and the embedded Python process-tree cleanup. Ideally with no changes to the agent loop, providers, sessions, frontend model UX, channels, or any updater.
2. PR 2 — Windows packaging. The NSIS installer, the isolated Python 3.12 runtime, and credential storage via Electron safeStorage.
3. PR 3 — the UX improvements (provider model discovery, model selection, showing the actual configured provider / model / reasoning setting / response duration, the reply-copy fix). Several of these are useful independently of the desktop build, so if you'd rather send this one first, that's completely fine.

Two requests on how the branches are built. Please rebuild from a real fork of current main with DCO Signed-off-by: trailers — that's a standing requirement for community PRs here, documented in CONTRIBUTING.md, not something specific to this proposal. And please leave out the 0.1.11 source overlay: the tree has moved a fair amount since then, and we'd need the diff to be only your changes.

With PR 1, it would help a lot if you could include the file list, the process-boundary threat model (loopback auth, secret lifetime, what the renderer can reach), dependency and license/SBOM output, a clean-Windows startup and shutdown result, and the remaining unsigned-build limitations.

Two things I'd ask you to keep out of the default build: please don't bundle every optional IM adapter into the Windows runtime — a small base runtime with explicit adapter installs is much easier to reason about; and I'd like to treat the personal WeChat QR/pairing path as a separate opt-in review item rather than a default surface.

On naming and release ownership: for now, please keep Vibe-Trading Desktop (Unofficial Community Build) and your own signing identity and release feed. Once the shell has landed and we've reviewed the security boundary, we can decide separately whether HKUDS takes over signing and distribution — that needs release and maintenance ownership settled first, and I don't want it to hold up the code review.

Source is enough for the first pass; no need to send an unsigned installer yet. Thanks again for asking before publishing more widely — that was the right call.

[QCYTSN]

Thank you. PR 1 is now available as a draft for review:

#892

It contains only the Electron desktop shell and backend lifecycle changes requested for the first review stage.

[Noobru]

One more thought from my side: if Vibe-Trading eventually gets an official Windows app, I'd love for Electron not to become the permanent choice just because the current prototype uses it.

I completely understand why Electron makes sense for a first version. It lets us reuse the React interface and get something working much faster. But, as a Windows user, I often find Electron apps heavier and slower than they need to be. Claude Desktop is one example where I notice this quite a lot.

When there's time, I think it would be worth looking at a native Windows app with WinUI/.NET, or at least something lighter such as Tauri or a WebView2-based shell. Ideally, we could still reuse the Python backend and as much of the existing frontend as possible.

I'm not suggesting throwing away the current Electron work or delaying more important things. The prototype is useful and proves that the desktop workflow can work. I'd just prefer that the long-term architecture remain open until the alternatives have been compared.

Would you be open to considering that later on?

[QCYTSN]

Thanks for the thoughtful feedback. I agree that the current Electron shell should be treated as a practical first implementation, not an irreversible long-term architecture decision.

The current PR is intentionally focused on proving the desktop lifecycle boundary while keeping the existing React frontend and Python/FastAPI backend reusable. That should leave room to evaluate Electron, Tauri, WebView2, or a native WinUI/.NET host later without redesigning the backend.

Once the initial shell and security boundary have been reviewed, I think a comparison based on cold-start time, memory usage, installer size, Python sidecar management, security, accessibility, and maintenance cost would be valuable.

I won’t expand or delay the current PR for that evaluation, but I’m open to keeping it as a future architecture item.

[warren618]

@QCYTSN @Noobru — a decision from our side so you both know where this is heading.

Electron is accepted as the first implementation, and the desktop host will live in this repository. Noobru's point stands and is on the record: this is not a permanent architecture commitment. A later comparison of Electron / Tauri / WebView2 / WinUI on cold-start time, memory, installer size, Python sidecar management, security, accessibility and maintenance cost is a legitimate follow-up item. QCYTSN's framing of the current PR — prove the desktop lifecycle boundary while keeping the React frontend and the Python/FastAPI backend reusable — is exactly the scope that keeps that door open. What we are committing to now is the boundary, not the runtime.

I'll review #892 personally, and it lands on main rather than sitting on a long-lived branch.

One thing you need to know before that review, and it is our fault rather than yours. We rewrote this repository's history earlier today, and the force-push invalidated the merge base for every open pull request. #892 currently displays 1,661 files and roughly 275,000 insertions. That is not what you wrote — I fetched your head locally and checked: the real content is two commits (feat(desktop): add Electron shell lifecycle and docs(desktop): document shell security boundary) touching twelve files, all under desktop/electron/. Everything else in that diff is our own history reappearing because the common ancestor collapsed back to April.

So the PR is precisely the scope we agreed on, but GitHub can neither display that nor merge it. Could you rebuild the branch on top of the current main and force-push?

git remote add upstream https://github.com/HKUDS/Vibe-Trading.git
git fetch upstream main
git checkout -b desktop-shell-v2 upstream/main
git cherry-pick <shell-commit> <docs-commit>
git push --force-with-lease origin desktop-shell-v2

Opening a fresh PR from that branch is equally fine — I'll close the old one with credit either way.

What I'll be checking in review, so nothing is a surprise:

1. The shell must not touch the protected core — agent/src/agent/, agent/src/session/, agent/src/providers/. Your twelve files don't, which is the main reason this is quick to review.
2. The backend stays bound to 127.0.0.1, and the random port plus per-launch auth secret hold up under a second instance and after an unclean exit.
3. Nothing on the desktop path weakens the live-trading boundary — mandate gate, kill switch, audit ledger. The shell starts the backend and does nothing more.
4. Process-tree cleanup on quit, on force-quit, and across an update. An orphaned Python process still holding a loopback port with a valid secret is the failure mode I care most about.

Having THREAT_MODEL.md and REVIEW_NOTES.md in the PR already is appreciated — that is not common, and it makes 1–4 much faster to verify.

Two gates before packaging (PR 2) reaches users, flagged now rather than later:

• The installer needs to be signed. An unsigned NSIS installer trips SmartScreen, and a large share of this project's users are traders rather than developers — a frightening Windows warning on first launch is worse than no installer at all. Let's work out certificate options when PR 2 comes up, rather than shipping unsigned.
• The updater needs one real end-to-end run, an actual 0.3.0 → 0.3.1 upgrade on a clean machine, before it is enabled. A broken updater is harder to recover from than a missing one, because it breaks on users' machines instead of ours.

PR 3 (provider model discovery, model selection, showing the configured provider / model / reasoning setting / response duration) is useful independent of the desktop work — I'd happily take that one even if it arrives first.

Thank you for splitting this the way you did, and for keeping the prototype honestly labelled as unofficial while it lived outside the repo.

[QCYTSN]

Thank you again for the clear direction. I have now rebuilt the work from the rewritten current main and removed the invalid history from the review path.

• PR 1: feat(desktop): add Electron shell lifecycle #923 — desktop shell and backend lifecycle only. It is ready for review: two DCO-signed commits, 13 files, and no changes under the protected agent/session/provider core.
• PR 3: feat(llm): add model discovery and runtime identity UX #924 — provider model discovery and runtime identity UX. It is also ready for review and contains the protected-core disclosure requested for the narrowly scoped response-metadata propagation.

The old #892 has been closed as superseded by #923.

I am keeping PR 2 local for now, stacked on #923, so it does not duplicate the shell diff before PR 1 lands. The local packaging branch excludes the updater, optional IM adapter dependencies, and the personal WeChat/QR path. It now has separate fail-closed commands for unsigned review artifacts versus signed publishable artifacts; the signed path requires external signing credentials and verifies Authenticode on both the packaged app and installer. I will rebuild/rebase it after #923 lands, then complete the exact-branch clean-Windows run and resolve the signing identity before opening that PR.

[warren618]

Thanks @QCYTSN — rebuilding from current main and splitting this into bounded, separately-reviewable PRs is exactly the right shape.

CI for #923 and #924 is approved and running now. Once it is green we will do a proper review pass, with the usual bar: no changes under the protected agent/session/provider core (we will verify that in the diff rather than take it on faith), tests included, and each PR independently mergeable so the desktop shell can land without the model-runtime piece if one needs more iterations.

Will follow up on the PRs themselves once CI reports.