Prerequisites
Area
Docker / Deployment
Problem or Motivation
Odysseus runs as a server currently for the Windows native install(Docker or venv + uvicorn) that you
use through a browser tab. It works, but it isn't a native app: no window of its
own, no system tray, no Start Menu / search entry, no app icon. For
non-technical Windows users it can be an adoption barrier compared to a
double-click app like Slack or Discord.
Discussion #1409 shows there's already community interest in optional Windows
desktop packaging, but nothing has shipped yet. This proposal is a working
implementation of that idea, available today.
Proposed Solution
A thin, optional harness (odysseus-desktop.py) that wraps the backend already
shipped:
- starts uvicorn (app:app) as a managed subprocess, health-checked against
/api/health, with auto-restart on crash
- embeds the existing web UI in a native pywebview window (no browser tab)
- system-tray icon (start / stop / open / quit) with close-to-tray
- creates a per-user Start Menu shortcut on first launch
- sets an AppUserModelID so the taskbar shows the Odysseus icon instead of the
generic Python one
It does not touch app.py or any core route. The whole change is 3 new files
plus 3 deps (pywebview, pystray, pillow) added to requirements-optional.txt,
so core and Docker installs are completely unaffected. A PyInstaller spec for
building a standalone .exe is included.
This follows the principles agreed in discussion #1409 — wrapper fully
separate from core, no dependency auto-install, opens the native window once
localhost:7000 is healthy. Where #1409 proposes a Tauri wrapper as the
end-state, this is a pure-Python implementation using pip deps familiar to
this stack, so it needs no Rust toolchain and works today. I'm happy to
relocate the files under desktop/windows/ to match that thread's proposed
layout, and this can serve as the interim path that a future Tauri app
supersedes.
See it working (standalone build you can run right now):
https://github.com/whoxllm/odysseus-desktop
Ready branch on current dev (1 commit, 4 files, additive-only, no conflicts):
https://github.com/whoxllm/odysseus/tree/feat/windows-desktop-harness
Disclosure: Built with Claude Code assistance — the commit carries the usual
Co-Authored-By trailer, same convention this project already uses.
Alternatives Considered
- Tauri wrapper (discussion Proposal: Optional Windows desktop packaging architecture #1409): good end-state, but adds a Rust toolchain
to a pure-Python project and hasn't been implemented; this works today and
can be superseded by it.
- Electron: far heavier (hundreds of MB) for what pywebview does with the
OS-native webview.
- Browser PWA install: still a browser — no tray, no backend lifecycle
management.
- Keeping it as a standalone downstream repo: works, but Windows users of this
repo never find it.
Prior Art / Related Issues
Are you willing to implement this?
Yes — I can open a PR
Prerequisites
Area
Docker / Deployment
Problem or Motivation
Odysseus runs as a server currently for the Windows native install(Docker or venv + uvicorn) that you
use through a browser tab. It works, but it isn't a native app: no window of its
own, no system tray, no Start Menu / search entry, no app icon. For
non-technical Windows users it can be an adoption barrier compared to a
double-click app like Slack or Discord.
Discussion #1409 shows there's already community interest in optional Windows
desktop packaging, but nothing has shipped yet. This proposal is a working
implementation of that idea, available today.
Proposed Solution
A thin, optional harness (odysseus-desktop.py) that wraps the backend already
shipped:
/api/health, with auto-restart on crash
generic Python one
It does not touch app.py or any core route. The whole change is 3 new files
plus 3 deps (pywebview, pystray, pillow) added to requirements-optional.txt,
so core and Docker installs are completely unaffected. A PyInstaller spec for
building a standalone .exe is included.
This follows the principles agreed in discussion #1409 — wrapper fully
separate from core, no dependency auto-install, opens the native window once
localhost:7000 is healthy. Where #1409 proposes a Tauri wrapper as the
end-state, this is a pure-Python implementation using pip deps familiar to
this stack, so it needs no Rust toolchain and works today. I'm happy to
relocate the files under desktop/windows/ to match that thread's proposed
layout, and this can serve as the interim path that a future Tauri app
supersedes.
See it working (standalone build you can run right now):
https://github.com/whoxllm/odysseus-desktop
Ready branch on current dev (1 commit, 4 files, additive-only, no conflicts):
https://github.com/whoxllm/odysseus/tree/feat/windows-desktop-harness
Disclosure: Built with Claude Code assistance — the commit carries the usual
Co-Authored-By trailer, same convention this project already uses.
Alternatives Considered
to a pure-Python project and hasn't been implemented; this works today and
can be superseded by it.
OS-native webview.
management.
repo never find it.
Prior Art / Related Issues
architecture" (this is a working implementation of that idea)
Are you willing to implement this?
Yes — I can open a PR