Proposal: Optional Windows desktop packaging architecture

[Bandonker]

Opening this because #603 was closed for scope, with the request to propose packaging architecture first.

Summary

This proposes an optional Windows desktop packaging architecture for Odysseus.

The desktop package would be a thin wrapper around the existing local app. It would not replace the browser, Docker, or native Python workflows, and it would not change core app behavior.

Architecture

The Windows desktop package would have four responsibilities:

1. Check whether required local runtime dependencies are available.
2. Run an approved bootstrap/install flow for missing dependencies, if maintainers agree that this belongs in the desktop package.
3. Start or connect to the local Odysseus server.
4. Wait until the app is available on localhost:7000, then open it in a native desktop window.

The wrapper should stay separate from the core app. Core routes, auth/session behavior, model serving, storage, and frontend app logic should remain owned by the existing Odysseus code.

Proposed File Layout

One possible layout:

desktop/
  windows/
    README.md
    launch-odysseus.bat
    src-tauri/
      tauri.conf.json
      icons/
      src/
        main.rs
    ui/
      startup.html
      startup.css

The exact layout can change, but the important boundary is that desktop packaging files stay grouped under a dedicated packaging directory instead of being mixed through core app code.

Startup Flow

1. User launches the desktop package.
2. The wrapper checks whether Odysseus is already running locally.
3. If not running, it checks whether required local runtime dependencies are available.
4. If dependencies are missing, it runs an approved bootstrap/install flow or shows clear instructions, depending on what maintainers prefer.
5. The wrapper starts the existing local server flow.
6. While startup is happening, the window shows clear local startup output/status.
7. Once localhost:7000 is ready, the window loads the app directly.
8. On exit, the wrapper shuts down only the processes it started.

Packaging Boundary

The desktop package may own:

• Tauri shell/window configuration
• Windows app metadata
• icons
• launch/bootstrap scripts
• dependency/runtime checks
• startup/readiness screen
• packaging documentation

The desktop package should not own:

• core app routes
• auth/session logic
• model/provider logic
• database/storage behavior
• Docker behavior
• existing browser/native Python launch flows
• broad frontend rewrites

Security / Maintenance Notes

The wrapper should:

• bind locally only
• avoid exposing the app on the LAN by default
• avoid handling secrets directly
• avoid writing outside documented local paths
• make dependency/bootstrap behavior explicit and reviewable
• avoid silently installing or modifying system-level dependencies
• make startup failures visible to the user
• avoid leaving hidden background processes running after exit

Open Questions

• Should dependency/bootstrap behavior live in the desktop package, or should the wrapper only show instructions when dependencies are missing?
• What bootstrap/dependency behavior would be acceptable?
• What verification would maintainers want before implementation PRs?

Follow-up Split

If this architecture is accepted, implementation could be split into smaller PRs:

1. Packaging docs
2. Local dependency/runtime checks
3. Local launch/bootstrap
4. Thin Tauri shell
5. Startup/readiness UI
6. Windows metadata/icons
7. Manual verification notes

[PcRoGamer]

Thanks for opening this ? this is exactly the right place to coordinate before implementation. I was the author of PR #1979 (the POC), which was closed with the request to route through here first.

I've been working on getting Odysseus running on Windows ARM64 (Surface Pro X/11), and the desktop wrapper was motivated by that experience. A few observations for the proposal:

1. Port number

The existing uvicorn invocation defaults to port 8000 (app:app without --port). The proposal and PR #603 both use 7000. This should match what the server actually binds to, or be made configurable so the desktop wrapper does not force a port change.

2. Dependency/bootstrap ? an answer to the open question

Auto-installing dependencies from a desktop wrapper is a sharp edge: it touches system Python, may fail on unusual architectures (ARM64 has no pre-built grpcio wheels), and creates support burden around "why did the installer break my environment?"

I would suggest show clear instructions when deps are missing, rather than auto-installing. This keeps the wrapper thin (window management + server lifecycle) and avoids bootstrap complexity. A standalone setup script the user runs once is fine, but baking install logic into the Tauri binary seems like a maintenance risk.

3. Windows ARM64 is a real target

The desktop package should account for non-x64 Windows:

• No MSVC ? must use LLVM MinGW (arm64 or x86_64 emulated)
• cargo test on the Tauri lib target crashes under emulation (missing RoOriginateErrorW) ? release binary works fine
• PyO3/maturin native extensions in Python deps fail to cross-compile
• The 65535-symbol export limit from full Tauri requires rlib crate type (not staticlib/cdylib) with MinGW

ARM64 awareness matters for CI/scripts even if the initial release targets x64.

4. Process management on Windows

The proposal says "shuts down only the processes it started" ? on Windows this needs:

• Explicit child-process handle kill (window close alone is not enough)
• CREATE_NO_WINDOW flag to suppress the uvicorn console window
• TerminateProcess since SIGTERM is not available (Rust child.kill() handles this)

5. File layout cross-platform consideration

Nesting under desktop/windows/ makes sense for Windows. If the architecture ever grows Linux/macOS support, extracting platform-common code (server manager, health-check poll, port detection) into a shared layer would avoid duplication. Not urgent, but worth noting.

My answers to the Open Questions

• Should bootstrap live in the desktop package? No ? instructions + optional standalone script, not baked into the Tauri binary. Less attack surface, less support burden.
• What verification before implementation PRs? At minimum: the architecture discussion should reach rough consensus on (a) whether bootstrap is in or out, (b) the port convention, and (c) where platform-specific vs shared code lives.

Happy to help with implementation once direction is settled ? items 2 (dep/runtime checks) and 4 (thin Tauri shell) align closely with the POC work already under feat/desktop-poc.

[CoolJohn-lab]

Agreed, Windows ARM64 is about to become the most important OS in the self-hosting AI space, those Nvidia Spark Windows Surface laptops with 128GB+ of unified ram and a dedicated AI inferencing chip are less than 6 months away.

[jhs88]

Some of us where talking about a dekstop app written in a framework that allows u to bundle a web app for all 3 major OS. #605

What you did here is nice. Let's all discuss over there too. We could prob use this

[PcRoGamer]

Re: @JosephScherreik's point about #605 and a cross-platform framework ? Tauri is already cross-platform (same Rust codebase targets Windows, macOS, Linux), so it matches the "bundle for all 3 major OS" goal well. The current POC at feat/desktop-poc targets Windows first but the architecture naturally extends: the server manager and health-check polling are platform-agnostic; only process spawning and window config need platform-specific handling.

If anyone wants to pick up the macOS/Linux side I am happy to coordinate on isolating the platform bits.

[jhs88]

I think we just need to properly support read/write for the application of the application storage. I haven't looked at ur solution that much, I'm going on my head here and i think we could do that in the python. I was playing around with electron doing this. Storing everything the app created in basically %AppData% equivalents something like:

dir: ~/.local linux & mac has one too in /Applications, i forget.

Linux also makes an AppImage for easy distribution

The app is basically a bundled python web server with is own isolated folder in the proper location. There are slight variations, but should be pretty straight forward.

[PcRoGamer]

Re: data storage paths -- good call. The dirs crate (already in the POC deps) handles exactly this cross-platform:

• Windows: %APPDATA%/odysseus
• macOS: ~/Library/Application Support/odysseus
• Linux: ~/.local/share/odysseus (XDG_DATA_HOME)

In Rust it is just dirs::data_dir().join("odysseus").

Electron can do this too via app.getPath("userData"), but Tauri has the same built-in through app.path().app_data_dir(). Since the architecture doc already endorses Tauri over Electron (#605 - Future Work), the Rust approach fits.

The repo-relative data dir (data/) stays for dev/Docker usage. The desktop wrapper would use the platform dir instead, keeping them cleanly separated. No changes needed to the existing Python code.

[jhs88]

Yeah im down for whatever solution is easiest right? I would assume lots of the functionality in electron im familair with has the same stuff in Tauri equivalents.

Data dir: Yeah that prob is best for sep of concerns and security. Giving the python direct access to the container's filesystem could create more holes. A wrapper that isolated to the desktop app makes a lot of sense.

[PcRoGamer]

Agreed on all points. The split is clean: Python owns business logic and the existing data/ convention; the Rust wrapper owns process lifecycle and deciding where that data/ lives (repo dir for dev, platform dir for installed). Zero changes to Python security surface either way.

For Tauri vs Electron equivalents -- Tauri's Rust ecosystem covers most of what Electron does via the tauri-plugin-* system (autostart, global shortcut, shell, fs access, updater). The main difference is those are opt-in crates rather than built-in APIs, which actually matches the thin wrapper philosophy better.

[jhs88]

Cool yeah ik shipping chrome everytime sucks. It's just the most popular solution. I'd assume they use rust libs to handle io and fs access?

[PcRoGamer]

Yes -- Tauri uses Rust's std::fs and std::io for all file access, plus crates like tauri-plugin-fs for exposing selected paths to the webview JS via a capability-based permission system. So you declare upfront which directories the frontend can read/write rather than giving blanket access. The Rust side can use any crate it wants (we use dirs for platform paths, reqwest for HTTP, which for finding Python).

[jhs88]

awesome that's prob the best of bost worlds